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 "base/memory/ref_counted.h"
14#include "content/common/content_export.h"
15
16namespace content {
17
18class 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.
24class 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 Close() {}
42
43   protected:
44    friend class base::RefCountedThreadSafe<TraceDataSink>;
45    virtual ~TraceDataSink() {}
46  };
47
48  // Create a trace sink that may be supplied to DisableRecording or
49  // CaptureMonitoringSnapshot to capture the trace data as a string.
50  CONTENT_EXPORT static scoped_refptr<TraceDataSink> CreateStringSink(
51      const base::Callback<void(base::RefCountedString*)>& callback);
52
53  // Create a trace sink that may be supplied to DisableRecording or
54  // CaptureMonitoringSnapshot to dump the trace data to a file.
55  CONTENT_EXPORT static scoped_refptr<TraceDataSink> CreateFileSink(
56      const base::FilePath& file_path,
57      const base::Closure& callback);
58
59  // Get a set of category groups. The category groups can change as
60  // new code paths are reached.
61  //
62  // Once all child processes have acked to the GetCategories request,
63  // GetCategoriesDoneCallback is called back with a set of category
64  // groups.
65  typedef base::Callback<void(const std::set<std::string>&)>
66      GetCategoriesDoneCallback;
67  virtual bool GetCategories(
68      const GetCategoriesDoneCallback& callback) = 0;
69
70  // Start recording on all processes.
71  //
72  // Recording begins immediately locally, and asynchronously on child processes
73  // as soon as they receive the EnableRecording request.
74  //
75  // Once all child processes have acked to the EnableRecording request,
76  // EnableRecordingDoneCallback will be called back.
77  //
78  // |category_filter| is a filter to control what category groups should be
79  // traced. A filter can have an optional '-' prefix to exclude category groups
80  // that contain a matching category. Having both included and excluded
81  // category patterns in the same list would not be supported.
82  //
83  // Examples: "test_MyTest*",
84  //           "test_MyTest*,test_OtherStuff",
85  //           "-excluded_category1,-excluded_category2"
86  //
87  // |options| controls what kind of tracing is enabled.
88  typedef base::Callback<void()> EnableRecordingDoneCallback;
89  virtual bool EnableRecording(
90      const base::debug::CategoryFilter& category_filter,
91      const base::debug::TraceOptions& trace_options,
92      const EnableRecordingDoneCallback& callback) = 0;
93
94  // Stop recording on all processes.
95  //
96  // Child processes typically are caching trace data and only rarely flush
97  // and send trace data back to the browser process. That is because it may be
98  // an expensive operation to send the trace data over IPC, and we would like
99  // to avoid much runtime overhead of tracing. So, to end tracing, we must
100  // asynchronously ask all child processes to flush any pending trace data.
101  //
102  // Once all child processes have acked to the DisableRecording request,
103  // TracingFileResultCallback will be called back with a file that contains
104  // the traced data.
105  //
106  // If |trace_data_sink| is not null, it will receive chunks of trace data
107  // as a comma-separated sequences of JSON-stringified events, followed by
108  // a notification that the trace collection is finished.
109  //
110  virtual bool DisableRecording(
111      const scoped_refptr<TraceDataSink>& trace_data_sink) = 0;
112
113  // Start monitoring on all processes.
114  //
115  // Monitoring begins immediately locally, and asynchronously on child
116  // processes as soon as they receive the EnableMonitoring request.
117  //
118  // Once all child processes have acked to the EnableMonitoring request,
119  // EnableMonitoringDoneCallback will be called back.
120  //
121  // |category_filter| is a filter to control what category groups should be
122  // traced.
123  //
124  // |options| controls what kind of tracing is enabled.
125  typedef base::Callback<void()> EnableMonitoringDoneCallback;
126  virtual bool EnableMonitoring(
127      const base::debug::CategoryFilter& category_filter,
128      const base::debug::TraceOptions& trace_options,
129      const EnableMonitoringDoneCallback& callback) = 0;
130
131  // Stop monitoring on all processes.
132  //
133  // Once all child processes have acked to the DisableMonitoring request,
134  // DisableMonitoringDoneCallback is called back.
135  typedef base::Callback<void()> DisableMonitoringDoneCallback;
136  virtual bool DisableMonitoring(
137      const DisableMonitoringDoneCallback& callback) = 0;
138
139  // Get the current monitoring configuration.
140  virtual void GetMonitoringStatus(
141      bool* out_enabled,
142      base::debug::CategoryFilter* out_category_filter,
143      base::debug::TraceOptions* out_trace_options) = 0;
144
145  // Get the current monitoring traced data.
146  //
147  // Child processes typically are caching trace data and only rarely flush
148  // and send trace data back to the browser process. That is because it may be
149  // an expensive operation to send the trace data over IPC, and we would like
150  // to avoid much runtime overhead of tracing. So, to end tracing, we must
151  // asynchronously ask all child processes to flush any pending trace data.
152  //
153  // Once all child processes have acked to the CaptureMonitoringSnapshot
154  // request, TracingFileResultCallback will be called back with a file that
155  // contains the traced data.
156  //
157  // If |trace_data_sink| is not null, it will receive chunks of trace data
158  // as a comma-separated sequences of JSON-stringified events, followed by
159  // a notification that the trace collection is finished.
160  virtual bool CaptureMonitoringSnapshot(
161      const scoped_refptr<TraceDataSink>& trace_data_sink) = 0;
162
163  // Get the maximum across processes of trace buffer percent full state.
164  // When the TraceBufferPercentFull value is determined, the callback is
165  // called.
166  typedef base::Callback<void(float)> GetTraceBufferPercentFullCallback;
167  virtual bool GetTraceBufferPercentFull(
168      const GetTraceBufferPercentFullCallback& callback) = 0;
169
170  // |callback| will will be called every time the given event occurs on any
171  // process.
172  typedef base::Callback<void()> WatchEventCallback;
173  virtual bool SetWatchEvent(const std::string& category_name,
174                             const std::string& event_name,
175                             const WatchEventCallback& callback) = 0;
176
177  // Cancel the watch event. If tracing is enabled, this may race with the
178  // watch event callback.
179  virtual bool CancelWatchEvent() = 0;
180
181 protected:
182  virtual ~TracingController() {}
183};
184
185}  // namespace content
186
187#endif  // CONTENT_PUBLIC_BROWSER_TRACING_CONTROLLER_H_
188