src/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 "base/debug/trace_event.h"
  13 #include "content/common/content_export.h"
  14
  15 namespace base {
  16 class FilePath;
  17 };
  18
  19 namespace content {
  20
  21 class TracingController;
  22
  23 // TracingController is used on the browser processes to enable/disable
  24 // trace status and collect trace data. Only the browser UI thread is allowed
  25 // to interact with the TracingController object. All callbacks are called on
  26 // the UI thread.
  27 class TracingController {
  28  public:
  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 bool 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   // |category_filter| is a filter to control what category groups should be
  52   // traced. 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& category_filter,
  64       const base::debug::TraceOptions& trace_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   //
  79   // Trace data will be written into |result_file_path| if it is not empty, or
  80   // into a temporary file. The actual file path will be passed to |callback| if
  81   // it's not null.
  82   //
  83   // If |result_file_path| is empty and |callback| is null, trace data won't be
  84   // written to any file.
  85   typedef base::Callback<void(const base::FilePath&)> TracingFileResultCallback;
  86   virtual bool DisableRecording(const base::FilePath& result_file_path,
  87                                 const TracingFileResultCallback& callback) = 0;
  88
  89   // Start monitoring on all processes.
  90   //
  91   // Monitoring begins immediately locally, and asynchronously on child
  92   // processes as soon as they receive the EnableMonitoring request.
  93   //
  94   // Once all child processes have acked to the EnableMonitoring request,
  95   // EnableMonitoringDoneCallback will be called back.
  96   //
  97   // |category_filter| is a filter to control what category groups should be
  98   // traced.
  99   //
 100   // |options| controls what kind of tracing is enabled.
 101   typedef base::Callback<void()> EnableMonitoringDoneCallback;
 102   virtual bool EnableMonitoring(
 103       const base::debug::CategoryFilter& category_filter,
 104       const base::debug::TraceOptions& trace_options,
 105       const EnableMonitoringDoneCallback& callback) = 0;
 106
 107   // Stop monitoring on all processes.
 108   //
 109   // Once all child processes have acked to the DisableMonitoring request,
 110   // DisableMonitoringDoneCallback is called back.
 111   typedef base::Callback<void()> DisableMonitoringDoneCallback;
 112   virtual bool DisableMonitoring(
 113       const DisableMonitoringDoneCallback& callback) = 0;
 114
 115   // Get the current monitoring configuration.
 116   virtual void GetMonitoringStatus(
 117       bool* out_enabled,
 118       base::debug::CategoryFilter* out_category_filter,
 119       base::debug::TraceOptions* out_trace_options) = 0;
 120
 121   // Get the current monitoring traced data.
 122   //
 123   // Child processes typically are caching trace data and only rarely flush
 124   // and send trace data back to the browser process. That is because it may be
 125   // an expensive operation to send the trace data over IPC, and we would like
 126   // to avoid much runtime overhead of tracing. So, to end tracing, we must
 127   // asynchronously ask all child processes to flush any pending trace data.
 128   //
 129   // Once all child processes have acked to the CaptureMonitoringSnapshot
 130   // request, TracingFileResultCallback will be called back with a file that
 131   // contains the traced data.
 132   //
 133   // Trace data will be written into |result_file_path| if it is not empty, or
 134   // into a temporary file. The actual file path will be passed to |callback|.
 135   //
 136   // If |result_file_path| is empty and |callback| is null, trace data won't be
 137   // written to any file.
 138   virtual bool CaptureMonitoringSnapshot(
 139       const base::FilePath& result_file_path,
 140       const TracingFileResultCallback& callback) = 0;
 141
 142   // Get the maximum across processes of trace buffer percent full state.
 143   // When the TraceBufferPercentFull value is determined, the callback is
 144   // called.
 145   typedef base::Callback<void(float)> GetTraceBufferPercentFullCallback;
 146   virtual bool GetTraceBufferPercentFull(
 147       const GetTraceBufferPercentFullCallback& callback) = 0;
 148
 149   // |callback| will will be called every time the given event occurs on any
 150   // process.
 151   typedef base::Callback<void()> WatchEventCallback;
 152   virtual bool SetWatchEvent(const std::string& category_name,
 153                              const std::string& event_name,
 154                              const WatchEventCallback& callback) = 0;
 155
 156   // Cancel the watch event. If tracing is enabled, this may race with the
 157   // watch event callback.
 158   virtual bool CancelWatchEvent() = 0;
 159
 160  protected:
 161   virtual ~TracingController() {}
 162 };
 163
 164 }  // namespace content
 165
 166 #endif  // CONTENT_PUBLIC_BROWSER_TRACING_CONTROLLER_H_