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