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