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/memory/ref_counted.h"
  13 #include "base/trace_event/trace_event.h"
  14 #include "content/common/content_export.h"
  15
  16 namespace content {
  17
  18 class TracingController;
  19
  20 // TracingController is used on the browser processes to enable/disable
  21 // trace status and collect trace data. Only the browser UI thread is allowed
  22 // to interact with the TracingController object. All callbacks are called on
  23 // the UI thread.
  24 class TracingController {
  25  public:
  26
  27   CONTENT_EXPORT static TracingController* GetInstance();
  28
  29   // An interface for trace data consumer. An implemnentation of this interface
  30   // is passed to either DisableTracing() or CaptureMonitoringSnapshot() and
  31   // receives the trace data followed by a notification that all child processes
  32   // have completed tracing and the data collection is over.
  33   // All methods are called on the UI thread.
  34   // Close method will be called exactly once and no methods will be
  35   // called after that.
  36   class CONTENT_EXPORT TraceDataSink
  37       : public base::RefCountedThreadSafe<TraceDataSink> {
  38    public:
  39     virtual void AddTraceChunk(const std::string& chunk) {}
  40     virtual void SetSystemTrace(const std::string& data) {}
  41     virtual void SetMetadata(const std::string& data) {}
  42     // TODO(prabhur) Replace all the Set* functions with a generic function:
  43     // TraceDataSink::AppendAdditionalData(const std::string& name,
  44     // const std::string& trace_data)
  45     virtual void SetPowerTrace(const std::string& data) {}
  46     virtual void Close() {}
  47
  48    protected:
  49     friend class base::RefCountedThreadSafe<TraceDataSink>;
  50     virtual ~TraceDataSink() {}
  51   };
  52
  53   // An implementation of this interface is passed when constructing a
  54   // TraceDataSink, and receives chunks of the final trace data as it's being
  55   // constructed.
  56   // Methods may be called from any thread.
  57   class CONTENT_EXPORT TraceDataEndpoint
  58       : public base::RefCountedThreadSafe<TraceDataEndpoint> {
  59    public:
  60     virtual void ReceiveTraceChunk(const std::string& chunk) {}
  61     virtual void ReceiveTraceFinalContents(const std::string& contents) {}
  62
  63    protected:
  64     friend class base::RefCountedThreadSafe<TraceDataEndpoint>;
  65     virtual ~TraceDataEndpoint() {}
  66   };
  67
  68   // Create a trace sink that may be supplied to DisableRecording or
  69   // CaptureMonitoringSnapshot to capture the trace data as a string.
  70   CONTENT_EXPORT static scoped_refptr<TraceDataSink> CreateStringSink(
  71       const base::Callback<void(base::RefCountedString*)>& callback);
  72
  73   CONTENT_EXPORT static scoped_refptr<TraceDataSink> CreateCompressedStringSink(
  74       scoped_refptr<TraceDataEndpoint> endpoint);
  75
  76   // Create a trace sink that may be supplied to DisableRecording or
  77   // CaptureMonitoringSnapshot to dump the trace data to a file.
  78   CONTENT_EXPORT static scoped_refptr<TraceDataSink> CreateFileSink(
  79       const base::FilePath& file_path,
  80       const base::Closure& callback);
  81
  82   // Create an endpoint that may be supplied to any TraceDataSink to
  83   // dump the trace data to a callback.
  84   CONTENT_EXPORT static scoped_refptr<TraceDataEndpoint> CreateCallbackEndpoint(
  85       const base::Callback<void(base::RefCountedString*)>& callback);
  86
  87   // Create an endpoint that may be supplied to any TraceDataSink to
  88   // dump the trace data to a file.
  89   CONTENT_EXPORT static scoped_refptr<TraceDataEndpoint> CreateFileEndpoint(
  90       const base::FilePath& file_path,
  91       const base::Closure& callback);
  92
  93   // Get a set of category groups. The category groups can change as
  94   // new code paths are reached.
  95   //
  96   // Once all child processes have acked to the GetCategories request,
  97   // GetCategoriesDoneCallback is called back with a set of category
  98   // groups.
  99   typedef base::Callback<void(const std::set<std::string>&)>
 100       GetCategoriesDoneCallback;
 101   virtual bool GetCategories(
 102       const GetCategoriesDoneCallback& callback) = 0;
 103
 104   // Start recording on all processes.
 105   //
 106   // Recording begins immediately locally, and asynchronously on child processes
 107   // as soon as they receive the EnableRecording request.
 108   //
 109   // Once all child processes have acked to the EnableRecording request,
 110   // EnableRecordingDoneCallback will be called back.
 111   //
 112   // |category_filter| is a filter to control what category groups should be
 113   // traced. A filter can have an optional '-' prefix to exclude category groups
 114   // that contain a matching category. Having both included and excluded
 115   // category patterns in the same list would not be supported.
 116   //
 117   // Examples: "test_MyTest*",
 118   //           "test_MyTest*,test_OtherStuff",
 119   //           "-excluded_category1,-excluded_category2"
 120   //
 121   // |options| controls what kind of tracing is enabled.
 122   typedef base::Callback<void()> EnableRecordingDoneCallback;
 123   virtual bool EnableRecording(
 124       const base::trace_event::TraceConfig& trace_config,
 125       const EnableRecordingDoneCallback& callback) = 0;
 126
 127   // Stop recording on all processes.
 128   //
 129   // Child processes typically are caching trace data and only rarely flush
 130   // and send trace data back to the browser process. That is because it may be
 131   // an expensive operation to send the trace data over IPC, and we would like
 132   // to avoid much runtime overhead of tracing. So, to end tracing, we must
 133   // asynchronously ask all child processes to flush any pending trace data.
 134   //
 135   // Once all child processes have acked to the DisableRecording request,
 136   // TracingFileResultCallback will be called back with a file that contains
 137   // the traced data.
 138   //
 139   // If |trace_data_sink| is not null, it will receive chunks of trace data
 140   // as a comma-separated sequences of JSON-stringified events, followed by
 141   // a notification that the trace collection is finished.
 142   //
 143   virtual bool DisableRecording(
 144       const scoped_refptr<TraceDataSink>& trace_data_sink) = 0;
 145
 146   // Start monitoring on all processes.
 147   //
 148   // Monitoring begins immediately locally, and asynchronously on child
 149   // processes as soon as they receive the EnableMonitoring request.
 150   //
 151   // Once all child processes have acked to the EnableMonitoring request,
 152   // EnableMonitoringDoneCallback will be called back.
 153   //
 154   // |category_filter| is a filter to control what category groups should be
 155   // traced.
 156   //
 157   // |options| controls what kind of tracing is enabled.
 158   typedef base::Callback<void()> EnableMonitoringDoneCallback;
 159   virtual bool EnableMonitoring(
 160       const base::trace_event::TraceConfig& trace_config,
 161       const EnableMonitoringDoneCallback& callback) = 0;
 162
 163   // Stop monitoring on all processes.
 164   //
 165   // Once all child processes have acked to the DisableMonitoring request,
 166   // DisableMonitoringDoneCallback is called back.
 167   typedef base::Callback<void()> DisableMonitoringDoneCallback;
 168   virtual bool DisableMonitoring(
 169       const DisableMonitoringDoneCallback& callback) = 0;
 170
 171   // Get the current monitoring configuration.
 172   virtual void GetMonitoringStatus(
 173       bool* out_enabled,
 174       base::trace_event::TraceConfig* out_trace_config) = 0;
 175
 176   // Get the current monitoring traced data.
 177   //
 178   // Child processes typically are caching trace data and only rarely flush
 179   // and send trace data back to the browser process. That is because it may be
 180   // an expensive operation to send the trace data over IPC, and we would like
 181   // to avoid much runtime overhead of tracing. So, to end tracing, we must
 182   // asynchronously ask all child processes to flush any pending trace data.
 183   //
 184   // Once all child processes have acked to the CaptureMonitoringSnapshot
 185   // request, TracingFileResultCallback will be called back with a file that
 186   // contains the traced data.
 187   //
 188   // If |trace_data_sink| is not null, it will receive chunks of trace data
 189   // as a comma-separated sequences of JSON-stringified events, followed by
 190   // a notification that the trace collection is finished.
 191   virtual bool CaptureMonitoringSnapshot(
 192       const scoped_refptr<TraceDataSink>& trace_data_sink) = 0;
 193
 194   // Get the maximum across processes of trace buffer percent full state.
 195   // When the TraceBufferUsage value is determined, the callback is
 196   // called.
 197   typedef base::Callback<void(float, size_t)> GetTraceBufferUsageCallback;
 198   virtual bool GetTraceBufferUsage(
 199       const GetTraceBufferUsageCallback& callback) = 0;
 200
 201   // |callback| will will be called every time the given event occurs on any
 202   // process.
 203   typedef base::Callback<void()> WatchEventCallback;
 204   virtual bool SetWatchEvent(const std::string& category_name,
 205                              const std::string& event_name,
 206                              const WatchEventCallback& callback) = 0;
 207
 208   // Cancel the watch event. If tracing is enabled, this may race with the
 209   // watch event callback.
 210   virtual bool CancelWatchEvent() = 0;
 211
 212   // Check if the tracing system is recording
 213   virtual bool IsRecording() const = 0;
 214
 215  protected:
 216   virtual ~TracingController() {}
 217 };
 218
 219 }  // namespace content
 220
 221 #endif  // CONTENT_PUBLIC_BROWSER_TRACING_CONTROLLER_H_