content/public/browser/tracing_controller.h

   1 // Copyright 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef CONTENT_PUBLIC_BROWSER_TRACING_CONTROLLER_H_
   6 #define CONTENT_PUBLIC_BROWSER_TRACING_CONTROLLER_H_
   7
   8 #include "base/debug/trace_event.h"
   9 #include "content/common/content_export.h"
  10
  11 namespace base {
  12 class FilePath;
  13 };
  14
  15 namespace content {
  16
  17 class TracingController;
  18
  19 // TracingController is used on the browser processes to enable/disable
  20 // trace status and collect trace data. Only the browser UI thread is allowed
  21 // to interact with the TracingController object. All callbacks are called on
  22 // the UI thread.
  23 class TracingController {
  24  public:
  25   enum Options {
  26     ENABLE_SYSTRACE = 1 << 0,
  27     ENABLE_SAMPLING = 1 << 1,
  28   };
  29
  30   CONTENT_EXPORT static TracingController* GetInstance();
  31
  32   // Get a set of category groups. The category groups can change as
  33   // new code paths are reached.
  34   //
  35   // Once all child processes have acked to the GetCategories request,
  36   // GetCategoriesDoneCallback is called back with a set of category
  37   // groups.
  38   typedef base::Callback<void(const std::set<std::string>&)>
  39       GetCategoriesDoneCallback;
  40   virtual void GetCategories(
  41       const GetCategoriesDoneCallback& callback) = 0;
  42
  43   // Start recording on all processes.
  44   //
  45   // Recording begins immediately locally, and asynchronously on child processes
  46   // as soon as they receive the EnableRecording request.
  47   //
  48   // Once all child processes have acked to the EnableRecording request,
  49   // EnableRecordingDoneCallback will be called back.
  50   //
  51   // |filter| is a filter to control what category groups should be traced.
  52   // A filter can have an optional '-' prefix to exclude category groups
  53   // that contain a matching category. Having both included and excluded
  54   // category patterns in the same list would not be supported.
  55   //
  56   // Examples: "test_MyTest*",
  57   //           "test_MyTest*,test_OtherStuff",
  58   //           "-excluded_category1,-excluded_category2"
  59   //
  60   // |options| controls what kind of tracing is enabled.
  61   typedef base::Callback<void()> EnableRecordingDoneCallback;
  62   virtual bool EnableRecording(
  63       const base::debug::CategoryFilter& filter,
  64       TracingController::Options options,
  65       const EnableRecordingDoneCallback& callback) = 0;
  66
  67   // Stop recording on all processes.
  68   //
  69   // Child processes typically are caching trace data and only rarely flush
  70   // and send trace data back to the browser process. That is because it may be
  71   // an expensive operation to send the trace data over IPC, and we would like
  72   // to avoid much runtime overhead of tracing. So, to end tracing, we must
  73   // asynchronously ask all child processes to flush any pending trace data.
  74   //
  75   // Once all child processes have acked to the DisableRecording request,
  76   // TracingFileResultCallback will be called back with a file that contains
  77   // the traced data.
  78   typedef base::Callback<void(scoped_ptr<base::FilePath>)>
  79       TracingFileResultCallback;
  80   virtual bool DisableRecording(const TracingFileResultCallback& callback) = 0;
  81
  82   // Start monitoring on all processes.
  83   //
  84   // Monitoring begins immediately locally, and asynchronously on child
  85   // processes as soon as they receive the EnableMonitoring request.
  86   //
  87   // Once all child processes have acked to the EnableMonitoring request,
  88   // EnableMonitoringDoneCallback will be called back.
  89   //
  90   // |filter| is a filter to control what category groups should be traced.
  91   //
  92   // |options| controls what kind of tracing is enabled.
  93   typedef base::Callback<void()> EnableMonitoringDoneCallback;
  94   virtual bool EnableMonitoring(const base::debug::CategoryFilter& filter,
  95       TracingController::Options options,
  96       const EnableMonitoringDoneCallback& callback) = 0;
  97
  98   // Stop monitoring on all processes.
  99   //
 100   // Once all child processes have acked to the DisableMonitoring request,
 101   // DisableMonitoringDoneCallback is called back.
 102   typedef base::Callback<void()> DisableMonitoringDoneCallback;
 103   virtual bool DisableMonitoring(
 104       const DisableMonitoringDoneCallback& callback) = 0;
 105
 106   // Get the current monitoring configuration.
 107   virtual void GetMonitoringStatus(bool* out_enabled,
 108       base::debug::CategoryFilter* out_filter,
 109       TracingController::Options* out_options) = 0;
 110
 111   // Get the current monitoring traced data.
 112   //
 113   // Child processes typically are caching trace data and only rarely flush
 114   // and send trace data back to the browser process. That is because it may be
 115   // an expensive operation to send the trace data over IPC, and we would like
 116   // to avoid much runtime overhead of tracing. So, to end tracing, we must
 117   // asynchronously ask all child processes to flush any pending trace data.
 118   //
 119   // Once all child processes have acked to the CaptureMonitoringSnapshot
 120   // request, TracingFileResultCallback will be called back with a file that
 121   // contains the traced data.
 122   virtual void CaptureMonitoringSnapshot(
 123       const TracingFileResultCallback& callback) = 0;
 124
 125  protected:
 126   virtual ~TracingController() {}
 127 };
 128
 129 }  // namespace content
 130
 131 #endif  // CONTENT_PUBLIC_BROWSER_TRACING_CONTROLLER_H_