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