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 32namespace base { 33namespace 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. 38class BASE_API EtwTraceProperties { 39 public: 40 EtwTraceProperties(); 41 42 EVENT_TRACE_PROPERTIES* get() { 43 return &properties_; 44 } 45 46 const EVENT_TRACE_PROPERTIES* get() const { 47 return reinterpret_cast<const EVENT_TRACE_PROPERTIES*>(&properties_); 48 } 49 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); 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. 88class 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. 139 TRACEHANDLE session() const { return session_; } 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