base/win/event_trace_controller.h

   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_