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 23 #include <windows.h> 24 #include <wmistr.h> 25 #include <evntrace.h> 26 #include <string> 27 28 #include "base/base_export.h" 29 #include "base/basictypes.h" 30 31 namespace base { 32 namespace win { 33 34 // Utility class to make it easier to work with EVENT_TRACE_PROPERTIES. 35 // The EVENT_TRACE_PROPERTIES structure contains information about an 36 // event tracing session. 37 class BASE_EXPORT EtwTraceProperties { 38 public: 39 EtwTraceProperties(); 40 41 EVENT_TRACE_PROPERTIES* get() { 42 return &properties_; 43 } 44 45 const EVENT_TRACE_PROPERTIES* get() const { 46 return reinterpret_cast<const EVENT_TRACE_PROPERTIES*>(&properties_); 47 } 48 49 const wchar_t* GetLoggerName() const { 50 return reinterpret_cast<const wchar_t *>(buffer_ + get()->LoggerNameOffset); 51 } 52 53 // Copies logger_name to the properties structure. 54 HRESULT SetLoggerName(const wchar_t* logger_name); 55 const wchar_t* GetLoggerFileName() const { 56 return reinterpret_cast<const wchar_t*>(buffer_ + get()->LogFileNameOffset); 57 } 58 59 // Copies logger_file_name to the properties structure. 60 HRESULT SetLoggerFileName(const wchar_t* logger_file_name); 61 62 // Max string len for name and session name is 1024 per documentation. 63 static const size_t kMaxStringLen = 1024; 64 // Properties buffer allocates space for header and for 65 // max length for name and session name. 66 static const size_t kBufSize = sizeof(EVENT_TRACE_PROPERTIES) 67 + 2 * sizeof(wchar_t) * (kMaxStringLen); 68 69 private: 70 // The EVENT_TRACE_PROPERTIES structure needs to be overlaid on a 71 // larger buffer to allow storing the logger name and logger file 72 // name contiguously with the structure. 73 union { 74 public: 75 // Our properties header. 76 EVENT_TRACE_PROPERTIES properties_; 77 // The actual size of the buffer is forced by this member. 78 char buffer_[kBufSize]; 79 }; 80 81 DISALLOW_COPY_AND_ASSIGN(EtwTraceProperties); 82 }; 83 84 // This class implements an ETW controller, which knows how to start and 85 // stop event tracing sessions, as well as controlling ETW provider 86 // log levels and enable bit masks under the session. 87 class BASE_EXPORT EtwTraceController { 88 public: 89 EtwTraceController(); 90 ~EtwTraceController(); 91 92 // Start a session with given name and properties. 93 HRESULT Start(const wchar_t* session_name, EtwTraceProperties* prop); 94 95 // Starts a session tracing to a file with some default properties. 96 HRESULT StartFileSession(const wchar_t* session_name, 97 const wchar_t* logfile_path, 98 bool realtime = false); 99 100 // Starts a realtime session with some default properties. 101 HRESULT StartRealtimeSession(const wchar_t* session_name, 102 size_t buffer_size); 103 104 // Enables "provider" at "level" for this session. 105 // This will cause all providers registered with the GUID 106 // "provider" to start tracing at the new level, systemwide. 107 HRESULT EnableProvider(const GUID& provider, UCHAR level, 108 ULONG flags = 0xFFFFFFFF); 109 // Disables "provider". 110 HRESULT DisableProvider(const GUID& provider); 111 112 // Stops our session and retrieve the new properties of the session, 113 // properties may be NULL. 114 HRESULT Stop(EtwTraceProperties* properties); 115 116 // Flushes our session and retrieve the current properties, 117 // properties may be NULL. 118 HRESULT Flush(EtwTraceProperties* properties); 119 120 // Static utility functions for controlling 121 // sessions we don't necessarily own. 122 static HRESULT Start(const wchar_t* session_name, 123 EtwTraceProperties* properties, 124 TRACEHANDLE* session_handle); 125 126 static HRESULT Query(const wchar_t* session_name, 127 EtwTraceProperties* properties); 128 129 static HRESULT Update(const wchar_t* session_name, 130 EtwTraceProperties* properties); 131 132 static HRESULT Stop(const wchar_t* session_name, 133 EtwTraceProperties* properties); 134 static HRESULT Flush(const wchar_t* session_name, 135 EtwTraceProperties* properties); 136 137 // Accessors. 138 TRACEHANDLE session() const { return session_; } 139 const wchar_t* session_name() const { return session_name_.c_str(); } 140 141 private: 142 std::wstring session_name_; 143 TRACEHANDLE session_; 144 145 DISALLOW_COPY_AND_ASSIGN(EtwTraceController); 146 }; 147 148 } // namespace win 149 } // namespace base 150 151 #endif // BASE_WIN_EVENT_TRACE_CONTROLLER_H_ 152