1 // Copyright 2015 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 BASE_TRACE_EVENT_TRACING_AGENT_H_
6 #define BASE_TRACE_EVENT_TRACING_AGENT_H_
7 
8 #include "base/base_export.h"
9 #include "base/callback.h"
10 #include "base/memory/ref_counted_memory.h"
11 #include "base/values.h"
12 
13 namespace base {
14 
15 class TimeTicks;
16 
17 namespace trace_event {
18 
19 class TraceConfig;
20 
21 // A tracing agent is an entity that records its own sort of trace. Each
22 // tracing method that produces its own trace log should implement this
23 // interface. All tracing agents must only be controlled by TracingController.
24 // Some existing examples include TracingControllerImpl for Chrome trace events,
25 // DebugDaemonClient for CrOs system trace, EtwTracingAgent for Windows system
26 // trace and PowerTracingAgent for BattOr power trace.
27 class BASE_EXPORT TracingAgent {
28  public:
29   using StartAgentTracingCallback =
30       base::OnceCallback<void(const std::string& agent_name, bool success)>;
31   // Passing a null or empty events_str_ptr indicates that no trace data is
32   // available for the specified agent.
33   using StopAgentTracingCallback = base::OnceCallback<void(
34       const std::string& agent_name,
35       const std::string& events_label,
36       const scoped_refptr<base::RefCountedString>& events_str_ptr)>;
37   using RecordClockSyncMarkerCallback =
38       base::OnceCallback<void(const std::string& sync_id,
39                               const TimeTicks& issue_ts,
40                               const TimeTicks& issue_end_ts)>;
41 
42   virtual ~TracingAgent();
43 
44   // Gets the name of the tracing agent. Each tracing agent's name should be
45   // unique.
46   virtual std::string GetTracingAgentName() = 0;
47 
48   // Gets the trace event label of this tracing agent. The label will be used to
49   // label this agent's trace when all traces from different tracing agents are
50   // combined. Multiple tracing agents could have the same label. The tracing
51   // agents using the same label should not be able to run at the same time. For
52   // example, ETW on Windows and CrOS system tracing both use
53   // "systemTraceEvents" as the label. Those two agents never run at the same
54   // time because they are for different platforms.
55   virtual std::string GetTraceEventLabel() = 0;
56 
57   // Starts tracing on the tracing agent with the trace configuration.
58   virtual void StartAgentTracing(const TraceConfig& trace_config,
59                                  StartAgentTracingCallback callback) = 0;
60 
61   // Stops tracing on the tracing agent. The trace data will be passed back to
62   // the TracingController via the callback.
63   virtual void StopAgentTracing(StopAgentTracingCallback callback) = 0;
64 
65   // Checks if the tracing agent supports explicit clock synchronization.
66   virtual bool SupportsExplicitClockSync();
67 
68   // Records a clock sync marker issued by another tracing agent. This is only
69   // used if the tracing agent supports explicit clock synchronization.
70   //
71   // Two things need to be done:
72   // 1. The issuer asks the receiver to record the clock sync marker.
73   // 2. The issuer records how long the receiver takes to do the recording.
74   //
75   // In Chrome, the receiver thread also runs in Chrome and it will talk to the
76   // real receiver entity, e.g., power monitor or Android device system, via
77   // different communication methods, e.g., through USB or file reading/writing.
78   // The 2nd task measures that communication latency.
79   //
80   // Having a reliable timing measurement for the 2nd task requires synchronous
81   // function call without any cross-thread or cross-process activity. However,
82   // tracing agents in Chrome run in their own threads. Therefore, the issuer
83   // needs to dedicate the 2nd task to the receiver to take time measurements
84   // in the receiver thread, and the receiver thread needs to pass them back to
85   // the issuer in the callback.
86   //
87   // The assumption is that the receiver thread knows the issuer's clock, which
88   // is true in Chrome because all agent threads' clocks are Chrome clock.
89   virtual void RecordClockSyncMarker(const std::string& sync_id,
90                                      RecordClockSyncMarkerCallback callback);
91 };
92 
93 }  // namespace trace_event
94 }  // namespace base
95 
96 #endif  // BASE_TRACE_EVENT_TRACING_AGENT_H_
97