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 <set>
   9 #include <string>
  10
  11 #include "base/callback.h"
  12 #include "content/common/content_export.h"
  13
  14 namespace base {
  15 class FilePath;
  16 };
  17
  18 namespace content {
  19
  20 class TracingController;
  21
  22 // TracingController is used on the browser processes to enable/disable
  23 // trace status and collect trace data. Only the browser UI thread is allowed
  24 // to interact with the TracingController object. All callbacks are called on
  25 // the UI thread.
  26 class TracingController {
  27  public:
  28   enum Options {
  29     DEFAULT_OPTIONS = 0,
  30     ENABLE_SYSTRACE = 1 << 0,
  31     ENABLE_SAMPLING = 1 << 1,
  32     RECORD_CONTINUOUSLY = 1 << 2,  // For EnableRecording() only.
  33   };
  34
  35   CONTENT_EXPORT static TracingController* GetInstance();
  36
  37   // Get a set of category groups. The category groups can change as
  38   // new code paths are reached.
  39   //
  40   // Once all child processes have acked to the GetCategories request,
  41   // GetCategoriesDoneCallback is called back with a set of category
  42   // groups.
  43   typedef base::Callback<void(const std::set<std::string>&)>
  44       GetCategoriesDoneCallback;
  45   virtual bool GetCategories(
  46       const GetCategoriesDoneCallback& callback) = 0;
  47
  48   // Start recording on all processes.
  49   //
  50   // Recording begins immediately locally, and asynchronously on child processes
  51   // as soon as they receive the EnableRecording request.
  52   //
  53   // Once all child processes have acked to the EnableRecording request,
  54   // EnableRecordingDoneCallback will be called back.
  55   //
  56   // |category_filter| is a filter to control what category groups should be
  57   // traced. A filter can have an optional '-' prefix to exclude category groups
  58   // that contain a matching category. Having both included and excluded
  59   // category patterns in the same list would not be supported.
  60   //
  61   // Examples: "test_MyTest*",
  62   //           "test_MyTest*,test_OtherStuff",
  63   //           "-excluded_category1,-excluded_category2"
  64   //
  65   // |options| controls what kind of tracing is enabled.
  66   typedef base::Callback<void()> EnableRecordingDoneCallback;
  67   virtual bool EnableRecording(
  68       const std::string& category_filter,
  69       TracingController::Options options,
  70       const EnableRecordingDoneCallback& callback) = 0;
  71
  72   // Stop recording on all processes.
  73   //
  74   // Child processes typically are caching trace data and only rarely flush
  75   // and send trace data back to the browser process. That is because it may be
  76   // an expensive operation to send the trace data over IPC, and we would like
  77   // to avoid much runtime overhead of tracing. So, to end tracing, we must
  78   // asynchronously ask all child processes to flush any pending trace data.
  79   //
  80   // Once all child processes have acked to the DisableRecording request,
  81   // TracingFileResultCallback will be called back with a file that contains
  82   // the traced data.
  83   //
  84   // Trace data will be written into |result_file_path| if it is not empty, or
  85   // into a temporary file. The actual file path will be passed to |callback| if
  86   // it's not null.
  87   //
  88   // If |result_file_path| is empty and |callback| is null, trace data won't be
  89   // written to any file.
  90   typedef base::Callback<void(const base::FilePath&)> TracingFileResultCallback;
  91   virtual bool DisableRecording(const base::FilePath& result_file_path,
  92                                 const TracingFileResultCallback& callback) = 0;
  93
  94   // Start monitoring on all processes.
  95   //
  96   // Monitoring begins immediately locally, and asynchronously on child
  97   // processes as soon as they receive the EnableMonitoring request.
  98   //
  99   // Once all child processes have acked to the EnableMonitoring request,
 100   // EnableMonitoringDoneCallback will be called back.
 101   //
 102   // |category_filter| is a filter to control what category groups should be
 103   // traced.
 104   //
 105   // |options| controls what kind of tracing is enabled.
 106   typedef base::Callback<void()> EnableMonitoringDoneCallback;
 107   virtual bool EnableMonitoring(
 108       const std::string& category_filter,
 109       TracingController::Options options,
 110       const EnableMonitoringDoneCallback& callback) = 0;
 111
 112   // Stop monitoring on all processes.
 113   //
 114   // Once all child processes have acked to the DisableMonitoring request,
 115   // DisableMonitoringDoneCallback is called back.
 116   typedef base::Callback<void()> DisableMonitoringDoneCallback;
 117   virtual bool DisableMonitoring(
 118       const DisableMonitoringDoneCallback& callback) = 0;
 119
 120   // Get the current monitoring configuration.
 121   virtual void GetMonitoringStatus(bool* out_enabled,
 122                                    std::string* out_category_filter,
 123                                    TracingController::Options* out_options) = 0;
 124
 125   // Get the current monitoring traced data.
 126   //
 127   // Child processes typically are caching trace data and only rarely flush
 128   // and send trace data back to the browser process. That is because it may be
 129   // an expensive operation to send the trace data over IPC, and we would like
 130   // to avoid much runtime overhead of tracing. So, to end tracing, we must
 131   // asynchronously ask all child processes to flush any pending trace data.
 132   //
 133   // Once all child processes have acked to the CaptureMonitoringSnapshot
 134   // request, TracingFileResultCallback will be called back with a file that
 135   // contains the traced data.
 136   //
 137   // Trace data will be written into |result_file_path| if it is not empty, or
 138   // into a temporary file. The actual file path will be passed to |callback|.
 139   //
 140   // If |result_file_path| is empty and |callback| is null, trace data won't be
 141   // written to any file.
 142   virtual bool CaptureMonitoringSnapshot(
 143       const base::FilePath& result_file_path,
 144       const TracingFileResultCallback& callback) = 0;
 145
 146   // Get the maximum across processes of trace buffer percent full state.
 147   // When the TraceBufferPercentFull value is determined, the callback is
 148   // called.
 149   typedef base::Callback<void(float)> GetTraceBufferPercentFullCallback;
 150   virtual bool GetTraceBufferPercentFull(
 151       const GetTraceBufferPercentFullCallback& callback) = 0;
 152
 153   // |callback| will will be called every time the given event occurs on any
 154   // process.
 155   typedef base::Callback<void()> WatchEventCallback;
 156   virtual bool SetWatchEvent(const std::string& category_name,
 157                              const std::string& event_name,
 158                              const WatchEventCallback& callback) = 0;
 159
 160   // Cancel the watch event. If tracing is enabled, this may race with the
 161   // watch event callback.
 162   virtual bool CancelWatchEvent() = 0;
 163
 164  protected:
 165   virtual ~TracingController() {}
 166 };
 167
 168 }  // namespace content
 169
 170 #endif  // CONTENT_PUBLIC_BROWSER_TRACING_CONTROLLER_H_