tracing_agent.h 4.1 KB

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