tracing_controller.h revision 58537e28ecd584eab876aee8be7156509866d23a 
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 "base/debug/trace_event.h"
9#include "content/common/content_export.h"
10
11namespace base {
12class FilePath;
13};
14
15namespace content {
16
17class TracingController;
18
19// TracingController is used on the browser processes to enable/disable
20// trace status and collect trace data. Only the browser UI thread is allowed
21// to interact with the TracingController object. All callbacks are called on
22// the UI thread.
23class TracingController {
24 public:
25  enum Options {
26    ENABLE_SYSTRACE = 1 << 0,
27    ENABLE_SAMPLING = 1 << 1,
28  };
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 void 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  // |filter| is a filter to control what category groups should be traced.
52  // 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 void EnableRecording(
63      const base::debug::CategoryFilter& filter,
64      TracingController::Options 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  typedef base::Callback<void(scoped_ptr<base::FilePath>)>
79      TracingFileResultCallback;
80  virtual void DisableRecording(const TracingFileResultCallback& callback) = 0;
81
82  // Start monitoring on all processes.
83  //
84  // Monitoring begins immediately locally, and asynchronously on child
85  // processes as soon as they receive the EnableMonitoring request.
86  //
87  // Once all child processes have acked to the EnableMonitoring request,
88  // EnableMonitoringDoneCallback will be called back.
89  //
90  // |filter| is a filter to control what category groups should be traced.
91  //
92  // |options| controls what kind of tracing is enabled.
93  typedef base::Callback<void()> EnableMonitoringDoneCallback;
94  virtual void EnableMonitoring(const base::debug::CategoryFilter& filter,
95      TracingController::Options options,
96      const EnableMonitoringDoneCallback& callback) = 0;
97
98  // Stop monitoring on all processes.
99  //
100  // Once all child processes have acked to the DisableMonitoring request,
101  // DisableMonitoringDoneCallback is called back.
102  typedef base::Callback<void()> DisableMonitoringDoneCallback;
103  virtual void DisableMonitoring(
104      const DisableMonitoringDoneCallback& callback) = 0;
105
106  // Get the current monitoring configuration.
107  virtual void GetMonitoringStatus(bool* out_enabled,
108      base::debug::CategoryFilter* out_filter,
109      TracingController::Options* out_options) = 0;
110
111  // Get the current monitoring traced data.
112  //
113  // Child processes typically are caching trace data and only rarely flush
114  // and send trace data back to the browser process. That is because it may be
115  // an expensive operation to send the trace data over IPC, and we would like
116  // to avoid much runtime overhead of tracing. So, to end tracing, we must
117  // asynchronously ask all child processes to flush any pending trace data.
118  //
119  // Once all child processes have acked to the CaptureCurrentMonitoringSnapshot
120  // request, TracingFileResultCallback will be called back with a file that
121  // contains the traced data.
122  virtual void CaptureCurrentMonitoringSnapshot(
123      const TracingFileResultCallback& callback) = 0;
124
125 protected:
126  virtual ~TracingController() {}
127};
128
129}  // namespace content
130
131#endif  // CONTENT_PUBLIC_BROWSER_TRACING_CONTROLLER_H_
132