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