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 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 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
