1 // Copyright (c) 2012 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_TRACE_CONTROLLER_H_
6 #define CONTENT_PUBLIC_BROWSER_TRACE_CONTROLLER_H_
8 #include "base/debug/trace_event.h"
9 #include "content/common/content_export.h"
13 class TraceSubscriber
;
15 // TraceController is used on the browser processes to enable/disable
16 // trace status and collect trace data. Only the browser UI thread is allowed
17 // to interact with the TraceController object. All calls on the TraceSubscriber
18 // happen on the UI thread.
19 class TraceController
{
21 CONTENT_EXPORT
static TraceController
* GetInstance();
23 // Called by browser process to start tracing events on all processes.
25 // Currently only one subscriber is allowed at a time.
26 // Tracing begins immediately locally, and asynchronously on child processes
27 // as soon as they receive the BeginTracing request.
29 // If BeginTracing was already called previously,
30 // or if an EndTracingAsync is pending,
31 // or if another subscriber is tracing,
32 // BeginTracing will return false meaning it failed.
34 // |category_patterns| is a comma-delimited list of category wildcards.
35 // A category pattern can have an optional '-' prefix to exclude category
36 // groups that contain a matching category.
37 // All the same rules apply above, so for example, having both included and
38 // excluded category patterns in the same list would not be supported.
40 // |mode| is the tracing mode being used.
42 // Example: BeginTracing("test_MyTest*");
43 // Example: BeginTracing("test_MyTest*,test_OtherStuff");
44 // Example: BeginTracing("-excluded_category1,-excluded_category2");
45 virtual bool BeginTracing(TraceSubscriber
* subscriber
,
46 const std::string
& category_patterns
,
47 base::debug::TraceLog::Options options
) = 0;
49 // Called by browser process to stop tracing events on all processes.
51 // Child processes typically are caching trace data and only rarely flush
52 // and send trace data back to the browser process. That is because it may be
53 // an expensive operation to send the trace data over IPC, and we would like
54 // to avoid much runtime overhead of tracing. So, to end tracing, we must
55 // asynchronously ask all child processes to flush any pending trace data.
57 // Once all child processes have acked the EndTracing request,
58 // TraceSubscriber will be called with OnEndTracingComplete.
60 // If a previous call to EndTracingAsync is already pending,
61 // or if another subscriber is tracing,
62 // EndTracingAsync will return false meaning it failed.
63 virtual bool EndTracingAsync(TraceSubscriber
* subscriber
) = 0;
65 // Get the maximum across processes of trace buffer percent full state.
66 // When the TraceBufferPercentFull value is determined,
67 // subscriber->OnTraceBufferPercentFullReply is called.
68 // When any child process reaches 100% full, the TraceController will end
69 // tracing, and call TraceSubscriber::OnEndTracingComplete.
70 // GetTraceBufferPercentFullAsync fails in the following conditions:
71 // trace is ending or disabled;
72 // a previous call to GetTraceBufferPercentFullAsync is pending; or
73 // the caller is not the current subscriber.
74 virtual bool GetTraceBufferPercentFullAsync(TraceSubscriber
* subscriber
) = 0;
76 // |subscriber->OnEventWatchNotification()| will be called every time the
77 // given event occurs on any process.
78 virtual bool SetWatchEvent(TraceSubscriber
* subscriber
,
79 const std::string
& category_name
,
80 const std::string
& event_name
) = 0;
82 // Cancel the watch event. If tracing is enabled, this may race with the
83 // watch event notification firing.
84 virtual bool CancelWatchEvent(TraceSubscriber
* subscriber
) = 0;
86 // Cancel the subscriber so that it will not be called when EndTracingAsync is
87 // acked by all child processes. This will also call EndTracingAsync
88 // internally if necessary.
89 // Safe to call even if caller is not the current subscriber.
90 virtual void CancelSubscriber(TraceSubscriber
* subscriber
) = 0;
92 // Get set of known category groups. This can change as new code paths are
93 // reached. If true is returned, subscriber->OnKnownCategoriesCollected will
94 // be called once the categories are retrieved from child processes.
95 virtual bool GetKnownCategoryGroupsAsync(TraceSubscriber
* subscriber
) = 0;
98 virtual ~TraceController() {}
101 } // namespace content
103 #endif // CONTENT_PUBLIC_BROWSER_TRACE_CONTROLLER_H_