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 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_EVENT_TRACE_CONTROLLER_WIN_H_
21#define BASE_EVENT_TRACE_CONTROLLER_WIN_H_
22
23#include <windows.h>
24#include <wmistr.h>
25#include <evntrace.h>
26#include <string>
27#include "base/basictypes.h"
28
29// Utility class to make it easier to work with EVENT_TRACE_PROPERTIES.
30// The EVENT_TRACE_PROPERTIES structure contains information about an
31// event tracing session.
32class EtwTraceProperties {
33 public:
34  EtwTraceProperties() {
35    memset(buffer_, 0, sizeof(buffer_));
36    EVENT_TRACE_PROPERTIES* prop = get();
37
38    prop->Wnode.BufferSize = sizeof(buffer_);
39    prop->Wnode.Flags = WNODE_FLAG_TRACED_GUID;
40    prop->LoggerNameOffset = sizeof(EVENT_TRACE_PROPERTIES);
41    prop->LogFileNameOffset = sizeof(EVENT_TRACE_PROPERTIES) +
42                              sizeof(wchar_t) * kMaxStringLen;
43  }
44
45  EVENT_TRACE_PROPERTIES* get() {
46    return &properties_;
47  }
48  const EVENT_TRACE_PROPERTIES* get() const {
49    return reinterpret_cast<const EVENT_TRACE_PROPERTIES*>(&properties_);
50  }
51
52  const wchar_t* GetLoggerName() const {
53    return reinterpret_cast<const wchar_t *>(buffer_ + get()->LoggerNameOffset);
54  }
55
56  HRESULT SetLoggerName(const wchar_t* logger_name) {
57    size_t len = wcslen(logger_name) + 1;
58    if (kMaxStringLen < len)
59      return E_INVALIDARG;
60
61    memcpy(buffer_ + get()->LoggerNameOffset,
62           logger_name,
63           sizeof(wchar_t) * len);
64    return S_OK;
65  }
66
67  const wchar_t* GetLoggerFileName() const {
68    return reinterpret_cast<const wchar_t*>(buffer_ + get()->LogFileNameOffset);
69  }
70
71  HRESULT SetLoggerFileName(const wchar_t* logger_file_name) {
72    size_t len = wcslen(logger_file_name) + 1;
73    if (kMaxStringLen < len)
74      return E_INVALIDARG;
75
76    memcpy(buffer_ + get()->LogFileNameOffset,
77           logger_file_name,
78           sizeof(wchar_t) * len);
79    return S_OK;
80  }
81
82  // Max string len for name and session name is 1024 per documentation.
83  static const size_t kMaxStringLen = 1024;
84  // Properties buffer allocates space for header and for
85  // max length for name and session name.
86  static const size_t kBufSize = sizeof(EVENT_TRACE_PROPERTIES)
87      + 2 * sizeof(wchar_t) * (kMaxStringLen);
88
89 private:
90  // The EVENT_TRACE_PROPERTIES structure needs to be overlaid on a
91  // larger buffer to allow storing the logger name and logger file
92  // name contiguously with the structure.
93  union {
94   public:
95    // Our properties header.
96    EVENT_TRACE_PROPERTIES properties_;
97    // The actual size of the buffer is forced by this member.
98    char buffer_[kBufSize];
99  };
100
101  DISALLOW_COPY_AND_ASSIGN(EtwTraceProperties);
102};
103
104// This class implements an ETW controller, which knows how to start and
105// stop event tracing sessions, as well as controlling ETW provider
106// log levels and enable bit masks under the session.
107class EtwTraceController {
108 public:
109  EtwTraceController();
110  ~EtwTraceController();
111
112  // Start a session with given name and properties.
113  HRESULT Start(const wchar_t* session_name, EtwTraceProperties* prop);
114
115  // Starts a session tracing to a file with some default properties.
116  HRESULT StartFileSession(const wchar_t* session_name,
117                           const wchar_t* logfile_path,
118                           bool realtime = false);
119
120  // Starts a realtime session with some default properties.
121  HRESULT StartRealtimeSession(const wchar_t* session_name,
122                               size_t buffer_size);
123
124  // Enables "provider" at "level" for this session.
125  // This will cause all providers registered with the GUID
126  // "provider" to start tracing at the new level, systemwide.
127  HRESULT EnableProvider(const GUID& provider, UCHAR level,
128                         ULONG flags = 0xFFFFFFFF);
129  // Disables "provider".
130  HRESULT DisableProvider(const GUID& provider);
131
132  // Stops our session and retrieve the new properties of the session,
133  // properties may be NULL.
134  HRESULT Stop(EtwTraceProperties* properties);
135
136  // Flushes our session and retrieve the current properties,
137  // properties may be NULL.
138  HRESULT Flush(EtwTraceProperties* properties);
139
140  // Static utility functions for controlling
141  // sessions we don't necessarily own.
142  static HRESULT Start(const wchar_t* session_name,
143                       EtwTraceProperties* properties,
144                       TRACEHANDLE* session_handle);
145
146  static HRESULT Query(const wchar_t* session_name,
147                       EtwTraceProperties* properties);
148
149  static HRESULT Update(const wchar_t* session_name,
150                        EtwTraceProperties* properties);
151
152  static HRESULT Stop(const wchar_t* session_name,
153                      EtwTraceProperties* properties);
154  static HRESULT Flush(const wchar_t* session_name,
155                       EtwTraceProperties* properties);
156
157  // Accessors.
158  TRACEHANDLE session() const { return session_; }
159  const wchar_t* session_name() const { return session_name_.c_str(); }
160
161 private:
162  std::wstring session_name_;
163  TRACEHANDLE session_;
164
165  DISALLOW_COPY_AND_ASSIGN(EtwTraceController);
166};
167
168#endif  // BASE_EVENT_TRACE_CONTROLLER_WIN_H_
169