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