event_trace_controller.h 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154
  1. // Copyright (c) 2011 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. // Declaration of a Windows event trace controller class.
  6. // The controller takes care of creating and manipulating event trace
  7. // sessions.
  8. //
  9. // Event tracing for Windows is a system-provided service that provides
  10. // logging control and high-performance transport for generic, binary trace
  11. // events. Event trace providers register with the system by their name,
  12. // which is a GUID, and can from that point forward receive callbacks that
  13. // start or end tracing and that change their trace level and enable mask.
  14. //
  15. // A trace controller can create an event tracing session, which either
  16. // sends events to a binary file, or to a realtime consumer, or both.
  17. //
  18. // A trace consumer consumes events from zero or one realtime session,
  19. // as well as potentially from multiple binary trace files.
  20. #ifndef BASE_WIN_EVENT_TRACE_CONTROLLER_H_
  21. #define BASE_WIN_EVENT_TRACE_CONTROLLER_H_
  22. #include <windows.h>
  23. #include <evntrace.h>
  24. #include <stddef.h>
  25. #include <wmistr.h>
  26. #include <string>
  27. #include "base/base_export.h"
  28. namespace base {
  29. namespace win {
  30. // Utility class to make it easier to work with EVENT_TRACE_PROPERTIES.
  31. // The EVENT_TRACE_PROPERTIES structure contains information about an
  32. // event tracing session.
  33. class BASE_EXPORT EtwTraceProperties {
  34. public:
  35. EtwTraceProperties();
  36. EtwTraceProperties(const EtwTraceProperties&) = delete;
  37. EtwTraceProperties& operator=(const EtwTraceProperties&) = delete;
  38. EVENT_TRACE_PROPERTIES* get() { return &properties_; }
  39. const EVENT_TRACE_PROPERTIES* get() const {
  40. return reinterpret_cast<const EVENT_TRACE_PROPERTIES*>(&properties_);
  41. }
  42. const wchar_t* GetLoggerName() const {
  43. return reinterpret_cast<const wchar_t*>(buffer_ + get()->LoggerNameOffset);
  44. }
  45. // Copies logger_name to the properties structure.
  46. HRESULT SetLoggerName(const wchar_t* logger_name);
  47. const wchar_t* GetLoggerFileName() const {
  48. return reinterpret_cast<const wchar_t*>(buffer_ + get()->LogFileNameOffset);
  49. }
  50. // Copies logger_file_name to the properties structure.
  51. HRESULT SetLoggerFileName(const wchar_t* logger_file_name);
  52. // Max string len for name and session name is 1024 per documentation.
  53. static const size_t kMaxStringLen = 1024;
  54. // Properties buffer allocates space for header and for
  55. // max length for name and session name.
  56. static const size_t kBufSize =
  57. sizeof(EVENT_TRACE_PROPERTIES) + 2 * sizeof(wchar_t) * (kMaxStringLen);
  58. private:
  59. // The EVENT_TRACE_PROPERTIES structure needs to be overlaid on a
  60. // larger buffer to allow storing the logger name and logger file
  61. // name contiguously with the structure.
  62. union {
  63. // Our properties header.
  64. EVENT_TRACE_PROPERTIES properties_;
  65. // The actual size of the buffer is forced by this member.
  66. char buffer_[kBufSize];
  67. };
  68. };
  69. // This class implements an ETW controller, which knows how to start and
  70. // stop event tracing sessions, as well as controlling ETW provider
  71. // log levels and enable bit masks under the session.
  72. class BASE_EXPORT EtwTraceController {
  73. public:
  74. EtwTraceController();
  75. EtwTraceController(const EtwTraceController&) = delete;
  76. EtwTraceController& operator=(const EtwTraceController&) = delete;
  77. ~EtwTraceController();
  78. // Start a session with given name and properties.
  79. HRESULT Start(const wchar_t* session_name, EtwTraceProperties* prop);
  80. // Starts a session tracing to a file with some default properties.
  81. HRESULT StartFileSession(const wchar_t* session_name,
  82. const wchar_t* logfile_path,
  83. bool realtime = false);
  84. // Starts a realtime session with some default properties. |buffer_size| is
  85. // in KB. A default value for |buffer_size| is used if 0 is passed in.
  86. HRESULT StartRealtimeSession(const wchar_t* session_name, size_t buffer_size);
  87. // Enables "provider" at "level" for this session.
  88. // This will cause all providers registered with the GUID
  89. // "provider" to start tracing at the new level, systemwide.
  90. HRESULT EnableProvider(const GUID& provider,
  91. UCHAR level,
  92. ULONG flags = 0xFFFFFFFF);
  93. // Disables "provider".
  94. HRESULT DisableProvider(const GUID& provider);
  95. // Stops our session and retrieve the new properties of the session,
  96. // properties may be NULL.
  97. HRESULT Stop(EtwTraceProperties* properties);
  98. // Flushes our session and retrieve the current properties,
  99. // properties may be NULL.
  100. HRESULT Flush(EtwTraceProperties* properties);
  101. // Static utility functions for controlling
  102. // sessions we don't necessarily own.
  103. static HRESULT Start(const wchar_t* session_name,
  104. EtwTraceProperties* properties,
  105. TRACEHANDLE* session_handle);
  106. static HRESULT Query(const wchar_t* session_name,
  107. EtwTraceProperties* properties);
  108. static HRESULT Update(const wchar_t* session_name,
  109. EtwTraceProperties* properties);
  110. static HRESULT Stop(const wchar_t* session_name,
  111. EtwTraceProperties* properties);
  112. static HRESULT Flush(const wchar_t* session_name,
  113. EtwTraceProperties* properties);
  114. // Accessors.
  115. TRACEHANDLE session() const { return session_; }
  116. const wchar_t* session_name() const { return session_name_.c_str(); }
  117. private:
  118. std::wstring session_name_;
  119. TRACEHANDLE session_ = NULL;
  120. };
  121. } // namespace win
  122. } // namespace base
  123. #endif // BASE_WIN_EVENT_TRACE_CONTROLLER_H_