base/event_trace_provider_win.h

   1 // Copyright (c) 2009 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 provider class, to allow using
   6 // Windows Event Tracing for logging transport and control.
   7 #ifndef BASE_EVENT_TRACE_PROVIDER_WIN_H_
   8 #define BASE_EVENT_TRACE_PROVIDER_WIN_H_
   9
  10 #include <windows.h>
  11 #include <wmistr.h>
  12 #include <evntrace.h>
  13 #include "base/basictypes.h"
  14
  15 typedef GUID EtwEventClass;
  16 typedef UCHAR EtwEventType;
  17 typedef UCHAR EtwEventLevel;
  18 typedef USHORT EtwEventVersion;
  19 typedef ULONG EtwEventFlags;
  20
  21 // Base class is a POD for correctness.
  22 template <size_t N> struct EtwMofEventBase {
  23   EVENT_TRACE_HEADER header;
  24   MOF_FIELD fields[N];
  25 };
  26
  27 // Utility class to auto-initialize event trace header structures.
  28 template <size_t N> class EtwMofEvent: public EtwMofEventBase<N> {
  29  public:
  30   typedef EtwMofEventBase<N> Super;
  31
  32   EtwMofEvent() {
  33     memset(static_cast<Super*>(this), 0, sizeof(Super));
  34   }
  35
  36   EtwMofEvent(const EtwEventClass& event_class, EtwEventType type,
  37               EtwEventLevel level) {
  38     memset(static_cast<Super*>(this), 0, sizeof(Super));
  39     header.Size = sizeof(Super);
  40     header.Guid = event_class;
  41     header.Class.Type = type;
  42     header.Class.Level = level;
  43     header.Flags = WNODE_FLAG_TRACED_GUID | WNODE_FLAG_USE_MOF_PTR;
  44   }
  45
  46   EtwMofEvent(const EtwEventClass& event_class, EtwEventType type,
  47               EtwEventVersion version, EtwEventLevel level) {
  48     memset(static_cast<Super*>(this), 0, sizeof(Super));
  49     header.Size = sizeof(Super);
  50     header.Guid = event_class;
  51     header.Class.Type = type;
  52     header.Class.Version = version;
  53     header.Class.Level = level;
  54     header.Flags = WNODE_FLAG_TRACED_GUID | WNODE_FLAG_USE_MOF_PTR;
  55   }
  56
  57   void SetField(int field, size_t size, const void *data) {
  58     // DCHECK(field < N);
  59     if ((field < N) && (size <= kuint32max)) {
  60       fields[field].DataPtr = reinterpret_cast<ULONG64>(data);
  61       fields[field].Length = static_cast<ULONG>(size);
  62     }
  63   }
  64
  65   EVENT_TRACE_HEADER* get() { return& header; }
  66
  67  private:
  68   DISALLOW_COPY_AND_ASSIGN(EtwMofEvent);
  69 };
  70
  71 // Trace provider with Event Tracing for Windows. The trace provider
  72 // registers with ETW by its name which is a GUID. ETW calls back to
  73 // the object whenever the trace level or enable flags for this provider
  74 // name changes.
  75 // Users of this class can test whether logging is currently enabled at
  76 // a particular trace level, and whether particular enable flags are set,
  77 // before other resources are consumed to generate and issue the log
  78 // messages themselves.
  79 class EtwTraceProvider {
  80  public:
  81   // Creates an event trace provider identified by provider_name, which
  82   // will be the name registered with Event Tracing for Windows (ETW).
  83   explicit EtwTraceProvider(const GUID& provider_name);
  84
  85   // Creates an unnamed event trace provider, the provider must be given
  86   // a name before registration.
  87   EtwTraceProvider();
  88   virtual ~EtwTraceProvider();
  89
  90   // Registers the trace provider with Event Tracing for Windows.
  91   // Note: from this point forward ETW may call the provider's control
  92   //    callback. If the provider's name is enabled in some trace session
  93   //    already, the callback may occur recursively from this call, so
  94   //    call this only when you're ready to handle callbacks.
  95   ULONG Register();
  96   // Unregisters the trace provider with ETW.
  97   ULONG Unregister();
  98
  99   // Accessors.
 100   void set_provider_name(const GUID& provider_name) {
 101     provider_name_ = provider_name;
 102   }
 103   const GUID& provider_name() const { return provider_name_; }
 104   TRACEHANDLE registration_handle() const { return registration_handle_; }
 105   TRACEHANDLE session_handle() const { return session_handle_; }
 106   EtwEventFlags enable_flags() const { return enable_flags_; }
 107   EtwEventLevel enable_level() const { return enable_level_; }
 108
 109   // Returns true iff logging should be performed for "level" and "flags".
 110   // Note: flags is treated as a bitmask, and should normally have a single
 111   //      bit set, to test whether to log for a particular sub "facility".
 112   bool ShouldLog(EtwEventLevel level, EtwEventFlags flags) {
 113     return NULL != session_handle_ && level >= enable_level_ &&
 114         (0 != (flags & enable_flags_));
 115   }
 116
 117   // Simple wrappers to log Unicode and ANSI strings.
 118   // Do nothing if !ShouldLog(level, 0xFFFFFFFF).
 119   ULONG Log(const EtwEventClass& event_class, EtwEventType type,
 120             EtwEventLevel level, const char *message);
 121   ULONG Log(const EtwEventClass& event_class, EtwEventType type,
 122             EtwEventLevel level, const wchar_t *message);
 123
 124   // Log the provided event.
 125   ULONG Log(EVENT_TRACE_HEADER* event);
 126
 127  protected:
 128   // These are called after events have been enabled or disabled.
 129   // Override them if you want to do processing at the start or
 130   // end of collection.
 131   // Note: These may be called ETW's thread and they may be racy.
 132   virtual void OnEventsEnabled() {}
 133   virtual void OnEventsDisabled() {}
 134
 135  private:
 136   ULONG EnableEvents(PVOID buffer);
 137   ULONG DisableEvents();
 138   ULONG Callback(WMIDPREQUESTCODE request, PVOID buffer);
 139   static ULONG WINAPI ControlCallback(WMIDPREQUESTCODE request, PVOID context,
 140                                       ULONG *reserved, PVOID buffer);
 141
 142   GUID provider_name_;
 143   TRACEHANDLE registration_handle_;
 144   TRACEHANDLE session_handle_;
 145   EtwEventFlags enable_flags_;
 146   EtwEventLevel enable_level_;
 147
 148   // We don't use this, but on XP we're obliged to pass one in to
 149   // RegisterTraceGuids. Non-const, because that's how the API needs it.
 150   static TRACE_GUID_REGISTRATION obligatory_guid_registration_;
 151
 152   DISALLOW_COPY_AND_ASSIGN(EtwTraceProvider);
 153 };
 154
 155 #endif  // BASE_EVENT_TRACE_PROVIDER_WIN_H_