trace_event.h revision ddb351dbec246cf1fab5ec20d2d5520909041de1 
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// Trace events to track application performance.  Events consist of a name
6// a type (BEGIN, END or INSTANT), a tracking id and extra string data.
7// In addition, the current process id, thread id, a timestamp down to the
8// microsecond and a file and line number of the calling location.
9//
10// The current implementation logs these events into a log file of the form
11// trace_<pid>.log where it's designed to be post-processed to generate a
12// trace report.  In the future, it may use another mechansim to facilitate
13// real-time analysis.
14
15#ifndef BASE_DEBUG_TRACE_EVENT_H_
16#define BASE_DEBUG_TRACE_EVENT_H_
17#pragma once
18
19#include "build/build_config.h"
20
21#if defined(OS_WIN)
22// On Windows we always pull in an alternative implementation
23// which logs to Event Tracing for Windows.
24//
25// Note that the Windows implementation is always enabled, irrespective the
26// value of the CHROMIUM_ENABLE_TRACE_EVENT define. The Windows implementation
27// is controlled by Event Tracing for Windows, which will turn tracing on only
28// if there is someone listening for the events it generates.
29#include "base/debug/trace_event_win.h"
30#else  // defined(OS_WIN)
31
32#include <string>
33
34#include "base/memory/scoped_ptr.h"
35#include "base/memory/singleton.h"
36#include "base/synchronization/lock.h"
37#include "base/time.h"
38#include "base/timer.h"
39
40#ifndef CHROMIUM_ENABLE_TRACE_EVENT
41#define TRACE_EVENT_BEGIN(name, id, extra) ((void) 0)
42#define TRACE_EVENT_END(name, id, extra) ((void) 0)
43#define TRACE_EVENT_INSTANT(name, id, extra) ((void) 0)
44
45#else  // CHROMIUM_ENABLE_TRACE_EVENT
46// Use the following macros rather than using the TraceLog class directly as the
47// underlying implementation may change in the future.  Here's a sample usage:
48// TRACE_EVENT_BEGIN("v8.run", documentId, scriptLocation);
49// RunScript(script);
50// TRACE_EVENT_END("v8.run", documentId, scriptLocation);
51
52// Record that an event (of name, id) has begun.  All BEGIN events should have
53// corresponding END events with a matching (name, id).
54#define TRACE_EVENT_BEGIN(name, id, extra) \
55  base::debug::TraceLog::GetInstance()->Trace( \
56      name, \
57      base::debug::TraceLog::EVENT_BEGIN, \
58      reinterpret_cast<const void*>(id), \
59      extra, \
60      __FILE__, \
61      __LINE__)
62
63// Record that an event (of name, id) has ended.  All END events should have
64// corresponding BEGIN events with a matching (name, id).
65#define TRACE_EVENT_END(name, id, extra) \
66  base::debug::TraceLog::GetInstance()->Trace( \
67      name, \
68      base::debug::TraceLog::EVENT_END, \
69      reinterpret_cast<const void*>(id), \
70      extra, \
71      __FILE__, \
72      __LINE__)
73
74// Record that an event (of name, id) with no duration has happened.
75#define TRACE_EVENT_INSTANT(name, id, extra) \
76  base::debug::TraceLog::GetInstance()->Trace( \
77      name, \
78      base::debug::TraceLog::EVENT_INSTANT, \
79      reinterpret_cast<const void*>(id), \
80      extra, \
81      __FILE__, \
82      __LINE__)
83#endif  // CHROMIUM_ENABLE_TRACE_EVENT
84
85namespace base {
86
87class ProcessMetrics;
88
89namespace debug {
90
91class TraceLog {
92 public:
93  enum EventType {
94    EVENT_BEGIN,
95    EVENT_END,
96    EVENT_INSTANT
97  };
98
99  static TraceLog* GetInstance();
100
101  // Is tracing currently enabled.
102  static bool IsTracing();
103  // Start logging trace events.
104  static bool StartTracing();
105  // Stop logging trace events.
106  static void StopTracing();
107
108  // Log a trace event of (name, type, id) with the optional extra string.
109  void Trace(const std::string& name,
110             EventType type,
111             const void* id,
112             const std::wstring& extra,
113             const char* file,
114             int line);
115  void Trace(const std::string& name,
116             EventType type,
117             const void* id,
118             const std::string& extra,
119             const char* file,
120             int line);
121
122 private:
123  // This allows constructor and destructor to be private and usable only
124  // by the Singleton class.
125  friend struct DefaultSingletonTraits<TraceLog>;
126
127  TraceLog();
128  ~TraceLog();
129  bool OpenLogFile();
130  void CloseLogFile();
131  bool Start();
132  void Stop();
133  void Heartbeat();
134  void Log(const std::string& msg);
135
136  bool enabled_;
137  FILE* log_file_;
138  base::Lock file_lock_;
139  TimeTicks trace_start_time_;
140#ifndef ANDROID
141  scoped_ptr<base::ProcessMetrics> process_metrics_;
142#endif
143  RepeatingTimer<TraceLog> timer_;
144};
145
146}  // namespace debug
147}  // namespace base
148
149#endif  // defined(OS_WIN)
150
151#endif  // BASE_DEBUG_TRACE_EVENT_H_
152