1//===- llvm/Support/TimeProfiler.h - Hierarchical Time Profiler -*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// This provides lightweight and dependency-free machinery to trace execution
10// time around arbitrary code. Two API flavors are available.
11//
12// The primary API uses a RAII object to trigger tracing:
13//
14// \code
15// {
16// TimeTraceScope scope("my_event_name");
17// ...my code...
18// }
19// \endcode
20//
21// If the code to be profiled does not have a natural lexical scope then
22// it is also possible to start and end events with respect to an implicit
23// per-thread stack of profiling entries:
24//
25// \code
26// timeTraceProfilerBegin("my_event_name");
27// ...my code...
28// timeTraceProfilerEnd(); // must be called on all control flow paths
29// \endcode
30//
31// Time profiling entries can be given an arbitrary name and, optionally,
32// an arbitrary 'detail' string. The resulting trace will include 'Total'
33// entries summing the time spent for each name. Thus, it's best to choose
34// names to be fairly generic, and rely on the detail field to capture
35// everything else of interest.
36//
37// To avoid lifetime issues name and detail strings are copied into the event
38// entries at their time of creation. Care should be taken to make string
39// construction cheap to prevent 'Heisenperf' effects. In particular, the
40// 'detail' argument may be a string-returning closure:
41//
42// \code
43// int n;
44// {
45// TimeTraceScope scope("my_event_name",
46// [n]() { return (Twine("x=") + Twine(n)).str(); });
47// ...my code...
48// }
49// \endcode
50// The closure will not be called if tracing is disabled. Otherwise, the
51// resulting string will be directly moved into the entry.
52//
53// The main process should begin with a timeTraceProfilerInitialize, and
54// finish with timeTraceProfileWrite and timeTraceProfilerCleanup calls.
55// Each new thread should begin with a timeTraceProfilerInitialize, and
56// finish with a timeTraceProfilerFinishThread call.
57//
58// Timestamps come from std::chrono::stable_clock. Note that threads need
59// not see the same time from that clock, and the resolution may not be
60// the best available.
61//
62// Currently, there are a number of compatible viewers:
63// - chrome://tracing is the original chromium trace viewer.
64// - http://ui.perfetto.dev is the replacement for the above, under active
65// development by Google as part of the 'Perfetto' project.
66// - https://www.speedscope.app/ has also been reported as an option.
67//
68// Future work:
69// - Support akin to LLVM_DEBUG for runtime enable/disable of named tracing
70// families for non-debug builds which wish to support optional tracing.
71// - Evaluate the detail closures at profile write time to avoid
72// stringification costs interfering with tracing.
73//
74//===----------------------------------------------------------------------===//
75
76#ifndef LLVM_SUPPORT_TIMEPROFILER_H
77#define LLVM_SUPPORT_TIMEPROFILER_H
78
79#include "llvm/ADT/STLFunctionalExtras.h"
80#include "llvm/Support/Compiler.h"
81#include "llvm/Support/Error.h"
82
83namespace llvm {
84
85class raw_pwrite_stream;
86
87// Type of the time trace event.
88enum class TimeTraceEventType {
89 // Complete events have a duration (start and end time points) and are marked
90 // by the "X" phase type.
91 CompleteEvent,
92 // Instant events don't have a duration, they happen at an instant in time.
93 // They are marked with "i" phase type. The field End is ignored for them.
94 InstantEvent,
95 // Async events mark asynchronous operations and are specified by the "b"
96 // (start) and "e" (end) phase types.
97 AsyncEvent
98};
99
100/// Compression mode for time trace output.
101enum class TimeTraceCompression {
102 Infer,
103 None,
104 Zstd,
105};
106
107struct TimeTraceMetadata {
108 std::string Detail;
109 // Source file and line number information for the event.
110 std::string File;
111 int Line = 0;
112
113 bool isEmpty() const { return Detail.empty() && File.empty(); }
114};
115
116struct TimeTraceProfiler;
117LLVM_ABI TimeTraceProfiler *getTimeTraceProfilerInstance();
118
119LLVM_ABI bool isTimeTraceVerbose();
120
121struct TimeTraceProfilerEntry;
122
123/// Infer the time trace compression format from \p Path based on its file
124/// extension (.zst/.zstd -> Zstd, otherwise None).
125LLVM_ABI TimeTraceCompression inferTimeTraceCompressionFromPath(StringRef Path);
126
127/// Initialize the time trace profiler.
128/// This sets up the global \p TimeTraceProfilerInstance
129/// variable to be the profiler instance.
130LLVM_ABI void timeTraceProfilerInitialize(
131 unsigned TimeTraceGranularity, StringRef ProcName,
132 bool TimeTraceVerbose = false,
133 TimeTraceCompression TimeTraceCompress = TimeTraceCompression::Infer);
134
135/// Cleanup the time trace profiler, if it was initialized.
136LLVM_ABI void timeTraceProfilerCleanup();
137
138/// Finish a time trace profiler running on a worker thread.
139LLVM_ABI void timeTraceProfilerFinishThread();
140
141/// Is the time trace profiler enabled, i.e. initialized?
142inline bool timeTraceProfilerEnabled() {
143 return getTimeTraceProfilerInstance() != nullptr;
144}
145
146/// Write profiling data to output stream.
147/// Data produced is JSON, in Chrome "Trace Event" format, see
148/// https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview
149LLVM_ABI void timeTraceProfilerWrite(raw_pwrite_stream &OS);
150
151/// Write profiling data to a file.
152/// The function will write to \p PreferredFileName if provided, if not
153/// then will write to \p FallbackFileName appending .time-trace.json.
154/// Returns a StringError indicating a failure if the function is
155/// unable to open the file for writing.
156LLVM_ABI Error timeTraceProfilerWrite(StringRef PreferredFileName,
157 StringRef FallbackFileName);
158
159/// Manually begin a time section, with the given \p Name and \p Detail.
160/// Profiler copies the string data, so the pointers can be given into
161/// temporaries. Time sections can be hierarchical; every Begin must have a
162/// matching End pair but they can nest.
163LLVM_ABI TimeTraceProfilerEntry *timeTraceProfilerBegin(StringRef Name,
164 StringRef Detail);
165LLVM_ABI TimeTraceProfilerEntry *
166timeTraceProfilerBegin(StringRef Name,
167 llvm::function_ref<std::string()> Detail);
168
169LLVM_ABI TimeTraceProfilerEntry *
170timeTraceProfilerBegin(StringRef Name,
171 llvm::function_ref<TimeTraceMetadata()> MetaData);
172
173/// Manually begin a time section, with the given \p Name and \p Detail.
174/// This starts Async Events having \p Name as a category which is shown
175/// separately from other traces. See
176/// https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview#heading=h.jh64i9l3vwa1
177/// for more details.
178LLVM_ABI TimeTraceProfilerEntry *timeTraceAsyncProfilerBegin(StringRef Name,
179 StringRef Detail);
180
181// Mark an instant event.
182LLVM_ABI void
183timeTraceAddInstantEvent(StringRef Name,
184 llvm::function_ref<std::string()> Detail);
185
186/// Manually end the last time section.
187LLVM_ABI void timeTraceProfilerEnd();
188LLVM_ABI void timeTraceProfilerEnd(TimeTraceProfilerEntry *E);
189
190/// The TimeTraceScope is a helper class to call the begin and end functions
191/// of the time trace profiler. When the object is constructed, it begins
192/// the section; and when it is destroyed, it stops it. If the time profiler
193/// is not initialized, the overhead is a single branch.
194class [[nodiscard]] TimeTraceScope {
195public:
196 TimeTraceScope() = delete;
197 TimeTraceScope(const TimeTraceScope &) = delete;
198 TimeTraceScope &operator=(const TimeTraceScope &) = delete;
199 TimeTraceScope(TimeTraceScope &&) = delete;
200 TimeTraceScope &operator=(TimeTraceScope &&) = delete;
201
202 TimeTraceScope(StringRef Name)
203 : Entry(timeTraceProfilerBegin(Name, Detail: StringRef())) {}
204 TimeTraceScope(StringRef Name, StringRef Detail)
205 : Entry(timeTraceProfilerBegin(Name, Detail)) {}
206 TimeTraceScope(StringRef Name, llvm::function_ref<std::string()> Detail)
207 : Entry(timeTraceProfilerBegin(Name, Detail)) {}
208 TimeTraceScope(StringRef Name,
209 llvm::function_ref<TimeTraceMetadata()> Metadata)
210 : Entry(timeTraceProfilerBegin(Name, MetaData: Metadata)) {}
211 ~TimeTraceScope() {
212 if (Entry)
213 timeTraceProfilerEnd(E: Entry);
214 }
215
216private:
217 TimeTraceProfilerEntry *Entry = nullptr;
218};
219
220} // end namespace llvm
221
222#endif
223