Home | History | Annotate | Download | only in win 
      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