[Android WebView] Fix webview perf bot switchover to use org.chromium.webview_shell...
[chromium-blink-merge.git] / content / public / browser / tracing_controller.h
blobf541107763a07ab3e92de75339767a26d7494544
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.
5 #ifndef CONTENT_PUBLIC_BROWSER_TRACING_CONTROLLER_H_
6 #define CONTENT_PUBLIC_BROWSER_TRACING_CONTROLLER_H_
8 #include <set>
9 #include <string>
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"
16 namespace content {
18 class TracingController;
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:
27 CONTENT_EXPORT static TracingController* GetInstance();
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 virtual void Close() {}
44 protected:
45 friend class base::RefCountedThreadSafe<TraceDataSink>;
46 virtual ~TraceDataSink() {}
49 // An implementation of this interface is passed when constructing a
50 // TraceDataSink, and receives chunks of the final trace data as it's being
51 // constructed.
52 // Methods may be called from any thread.
53 class CONTENT_EXPORT TraceDataEndpoint
54 : public base::RefCountedThreadSafe<TraceDataEndpoint> {
55 public:
56 virtual void ReceiveTraceChunk(const std::string& chunk) {}
57 virtual void ReceiveTraceFinalContents(const std::string& contents) {}
59 protected:
60 friend class base::RefCountedThreadSafe<TraceDataEndpoint>;
61 virtual ~TraceDataEndpoint() {}
64 // Create a trace sink that may be supplied to DisableRecording or
65 // CaptureMonitoringSnapshot to capture the trace data as a string.
66 CONTENT_EXPORT static scoped_refptr<TraceDataSink> CreateStringSink(
67 const base::Callback<void(base::RefCountedString*)>& callback);
69 CONTENT_EXPORT static scoped_refptr<TraceDataSink> CreateCompressedStringSink(
70 scoped_refptr<TraceDataEndpoint> endpoint);
72 // Create a trace sink that may be supplied to DisableRecording or
73 // CaptureMonitoringSnapshot to dump the trace data to a file.
74 CONTENT_EXPORT static scoped_refptr<TraceDataSink> CreateFileSink(
75 const base::FilePath& file_path,
76 const base::Closure& callback);
78 // Create an endpoint that may be supplied to any TraceDataSink to
79 // dump the trace data to a file.
80 CONTENT_EXPORT static scoped_refptr<TraceDataEndpoint> CreateFileEndpoint(
81 const base::FilePath& file_path,
82 const base::Closure& callback);
84 // Get a set of category groups. The category groups can change as
85 // new code paths are reached.
87 // Once all child processes have acked to the GetCategories request,
88 // GetCategoriesDoneCallback is called back with a set of category
89 // groups.
90 typedef base::Callback<void(const std::set<std::string>&)>
91 GetCategoriesDoneCallback;
92 virtual bool GetCategories(
93 const GetCategoriesDoneCallback& callback) = 0;
95 // Start recording on all processes.
97 // Recording begins immediately locally, and asynchronously on child processes
98 // as soon as they receive the EnableRecording request.
100 // Once all child processes have acked to the EnableRecording request,
101 // EnableRecordingDoneCallback will be called back.
103 // |category_filter| is a filter to control what category groups should be
104 // traced. A filter can have an optional '-' prefix to exclude category groups
105 // that contain a matching category. Having both included and excluded
106 // category patterns in the same list would not be supported.
108 // Examples: "test_MyTest*",
109 // "test_MyTest*,test_OtherStuff",
110 // "-excluded_category1,-excluded_category2"
112 // |options| controls what kind of tracing is enabled.
113 typedef base::Callback<void()> EnableRecordingDoneCallback;
114 virtual bool EnableRecording(
115 const base::trace_event::TraceConfig& trace_config,
116 const EnableRecordingDoneCallback& callback) = 0;
118 // Stop recording on all processes.
120 // Child processes typically are caching trace data and only rarely flush
121 // and send trace data back to the browser process. That is because it may be
122 // an expensive operation to send the trace data over IPC, and we would like
123 // to avoid much runtime overhead of tracing. So, to end tracing, we must
124 // asynchronously ask all child processes to flush any pending trace data.
126 // Once all child processes have acked to the DisableRecording request,
127 // TracingFileResultCallback will be called back with a file that contains
128 // the traced data.
130 // If |trace_data_sink| is not null, it will receive chunks of trace data
131 // as a comma-separated sequences of JSON-stringified events, followed by
132 // a notification that the trace collection is finished.
134 virtual bool DisableRecording(
135 const scoped_refptr<TraceDataSink>& trace_data_sink) = 0;
137 // Start monitoring on all processes.
139 // Monitoring begins immediately locally, and asynchronously on child
140 // processes as soon as they receive the EnableMonitoring request.
142 // Once all child processes have acked to the EnableMonitoring request,
143 // EnableMonitoringDoneCallback will be called back.
145 // |category_filter| is a filter to control what category groups should be
146 // traced.
148 // |options| controls what kind of tracing is enabled.
149 typedef base::Callback<void()> EnableMonitoringDoneCallback;
150 virtual bool EnableMonitoring(
151 const base::trace_event::TraceConfig& trace_config,
152 const EnableMonitoringDoneCallback& callback) = 0;
154 // Stop monitoring on all processes.
156 // Once all child processes have acked to the DisableMonitoring request,
157 // DisableMonitoringDoneCallback is called back.
158 typedef base::Callback<void()> DisableMonitoringDoneCallback;
159 virtual bool DisableMonitoring(
160 const DisableMonitoringDoneCallback& callback) = 0;
162 // Get the current monitoring configuration.
163 virtual void GetMonitoringStatus(
164 bool* out_enabled,
165 base::trace_event::TraceConfig* out_trace_config) = 0;
167 // Get the current monitoring traced data.
169 // Child processes typically are caching trace data and only rarely flush
170 // and send trace data back to the browser process. That is because it may be
171 // an expensive operation to send the trace data over IPC, and we would like
172 // to avoid much runtime overhead of tracing. So, to end tracing, we must
173 // asynchronously ask all child processes to flush any pending trace data.
175 // Once all child processes have acked to the CaptureMonitoringSnapshot
176 // request, TracingFileResultCallback will be called back with a file that
177 // contains the traced data.
179 // If |trace_data_sink| is not null, it will receive chunks of trace data
180 // as a comma-separated sequences of JSON-stringified events, followed by
181 // a notification that the trace collection is finished.
182 virtual bool CaptureMonitoringSnapshot(
183 const scoped_refptr<TraceDataSink>& trace_data_sink) = 0;
185 // Get the maximum across processes of trace buffer percent full state.
186 // When the TraceBufferUsage value is determined, the callback is
187 // called.
188 typedef base::Callback<void(float, size_t)> GetTraceBufferUsageCallback;
189 virtual bool GetTraceBufferUsage(
190 const GetTraceBufferUsageCallback& callback) = 0;
192 // |callback| will will be called every time the given event occurs on any
193 // process.
194 typedef base::Callback<void()> WatchEventCallback;
195 virtual bool SetWatchEvent(const std::string& category_name,
196 const std::string& event_name,
197 const WatchEventCallback& callback) = 0;
199 // Cancel the watch event. If tracing is enabled, this may race with the
200 // watch event callback.
201 virtual bool CancelWatchEvent() = 0;
203 // Check if the tracing system is recording
204 virtual bool IsRecording() const = 0;
206 protected:
207 virtual ~TracingController() {}
210 } // namespace content
212 #endif // CONTENT_PUBLIC_BROWSER_TRACING_CONTROLLER_H_