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 "content/common/content_export.h" 13 14 namespace base { 15 class FilePath; 16 }; 17 18 namespace content { 19 20 class TracingController; 21 22 // TracingController is used on the browser processes to enable/disable 23 // trace status and collect trace data. Only the browser UI thread is allowed 24 // to interact with the TracingController object. All callbacks are called on 25 // the UI thread. 26 class TracingController { 27 public: 28 enum Options { 29 DEFAULT_OPTIONS = 0, 30 ENABLE_SYSTRACE = 1 << 0, 31 ENABLE_SAMPLING = 1 << 1, 32 RECORD_CONTINUOUSLY = 1 << 2, // For EnableRecording() only. 33 }; 34 35 CONTENT_EXPORT static TracingController* GetInstance(); 36 37 // Get a set of category groups. The category groups can change as 38 // new code paths are reached. 39 // 40 // Once all child processes have acked to the GetCategories request, 41 // GetCategoriesDoneCallback is called back with a set of category 42 // groups. 43 typedef base::Callback<void(const std::set<std::string>&)> 44 GetCategoriesDoneCallback; 45 virtual bool GetCategories( 46 const GetCategoriesDoneCallback& callback) = 0; 47 48 // Start recording on all processes. 49 // 50 // Recording begins immediately locally, and asynchronously on child processes 51 // as soon as they receive the EnableRecording request. 52 // 53 // Once all child processes have acked to the EnableRecording request, 54 // EnableRecordingDoneCallback will be called back. 55 // 56 // |category_filter| is a filter to control what category groups should be 57 // traced. A filter can have an optional '-' prefix to exclude category groups 58 // that contain a matching category. Having both included and excluded 59 // category patterns in the same list would not be supported. 60 // 61 // Examples: "test_MyTest*", 62 // "test_MyTest*,test_OtherStuff", 63 // "-excluded_category1,-excluded_category2" 64 // 65 // |options| controls what kind of tracing is enabled. 66 typedef base::Callback<void()> EnableRecordingDoneCallback; 67 virtual bool EnableRecording( 68 const std::string& category_filter, 69 TracingController::Options options, 70 const EnableRecordingDoneCallback& callback) = 0; 71 72 // Stop recording on all processes. 73 // 74 // Child processes typically are caching trace data and only rarely flush 75 // and send trace data back to the browser process. That is because it may be 76 // an expensive operation to send the trace data over IPC, and we would like 77 // to avoid much runtime overhead of tracing. So, to end tracing, we must 78 // asynchronously ask all child processes to flush any pending trace data. 79 // 80 // Once all child processes have acked to the DisableRecording request, 81 // TracingFileResultCallback will be called back with a file that contains 82 // the traced data. 83 // 84 // Trace data will be written into |result_file_path| if it is not empty, or 85 // into a temporary file. The actual file path will be passed to |callback| if 86 // it's not null. 87 // 88 // If |result_file_path| is empty and |callback| is null, trace data won't be 89 // written to any file. 90 typedef base::Callback<void(const base::FilePath&)> TracingFileResultCallback; 91 virtual bool DisableRecording(const base::FilePath& result_file_path, 92 const TracingFileResultCallback& callback) = 0; 93 94 // Start monitoring on all processes. 95 // 96 // Monitoring begins immediately locally, and asynchronously on child 97 // processes as soon as they receive the EnableMonitoring request. 98 // 99 // Once all child processes have acked to the EnableMonitoring request, 100 // EnableMonitoringDoneCallback will be called back. 101 // 102 // |category_filter| is a filter to control what category groups should be 103 // traced. 104 // 105 // |options| controls what kind of tracing is enabled. 106 typedef base::Callback<void()> EnableMonitoringDoneCallback; 107 virtual bool EnableMonitoring( 108 const std::string& category_filter, 109 TracingController::Options options, 110 const EnableMonitoringDoneCallback& callback) = 0; 111 112 // Stop monitoring on all processes. 113 // 114 // Once all child processes have acked to the DisableMonitoring request, 115 // DisableMonitoringDoneCallback is called back. 116 typedef base::Callback<void()> DisableMonitoringDoneCallback; 117 virtual bool DisableMonitoring( 118 const DisableMonitoringDoneCallback& callback) = 0; 119 120 // Get the current monitoring configuration. 121 virtual void GetMonitoringStatus(bool* out_enabled, 122 std::string* out_category_filter, 123 TracingController::Options* out_options) = 0; 124 125 // Get the current monitoring traced data. 126 // 127 // Child processes typically are caching trace data and only rarely flush 128 // and send trace data back to the browser process. That is because it may be 129 // an expensive operation to send the trace data over IPC, and we would like 130 // to avoid much runtime overhead of tracing. So, to end tracing, we must 131 // asynchronously ask all child processes to flush any pending trace data. 132 // 133 // Once all child processes have acked to the CaptureMonitoringSnapshot 134 // request, TracingFileResultCallback will be called back with a file that 135 // contains the traced data. 136 // 137 // Trace data will be written into |result_file_path| if it is not empty, or 138 // into a temporary file. The actual file path will be passed to |callback|. 139 // 140 // If |result_file_path| is empty and |callback| is null, trace data won't be 141 // written to any file. 142 virtual bool CaptureMonitoringSnapshot( 143 const base::FilePath& result_file_path, 144 const TracingFileResultCallback& callback) = 0; 145 146 // Get the maximum across processes of trace buffer percent full state. 147 // When the TraceBufferPercentFull value is determined, the callback is 148 // called. 149 typedef base::Callback<void(float)> GetTraceBufferPercentFullCallback; 150 virtual bool GetTraceBufferPercentFull( 151 const GetTraceBufferPercentFullCallback& callback) = 0; 152 153 // |callback| will will be called every time the given event occurs on any 154 // process. 155 typedef base::Callback<void()> WatchEventCallback; 156 virtual bool SetWatchEvent(const std::string& category_name, 157 const std::string& event_name, 158 const WatchEventCallback& callback) = 0; 159 160 // Cancel the watch event. If tracing is enabled, this may race with the 161 // watch event callback. 162 virtual bool CancelWatchEvent() = 0; 163 164 protected: ~TracingController()165 virtual ~TracingController() {} 166 }; 167 168 } // namespace content 169 170 #endif // CONTENT_PUBLIC_BROWSER_TRACING_CONTROLLER_H_ 171