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/Error.h" 81 82 namespace llvm { 83 84 class raw_pwrite_stream; 85 86 // Type of the time trace event. 87 enum class TimeTraceEventType { 88 // Complete events have a duration (start and end time points) and are marked 89 // by the "X" phase type. 90 CompleteEvent, 91 // Instant events don't have a duration, they happen at an instant in time. 92 // They are marked with "i" phase type. The field End is ignored for them. 93 InstantEvent, 94 // Async events mark asynchronous operations and are specified by the "b" 95 // (start) and "e" (end) phase types. 96 AsyncEvent 97 }; 98 99 struct TimeTraceMetadata { 100 std::string Detail; 101 // Source file and line number information for the event. 102 std::string File; 103 int Line = 0; 104 105 bool isEmpty() const { return Detail.empty() && File.empty(); } 106 }; 107 108 struct TimeTraceProfiler; 109 TimeTraceProfiler *getTimeTraceProfilerInstance(); 110 111 bool isTimeTraceVerbose(); 112 113 struct TimeTraceProfilerEntry; 114 115 /// Initialize the time trace profiler. 116 /// This sets up the global \p TimeTraceProfilerInstance 117 /// variable to be the profiler instance. 118 void timeTraceProfilerInitialize(unsigned TimeTraceGranularity, 119 StringRef ProcName, 120 bool TimeTraceVerbose = false); 121 122 /// Cleanup the time trace profiler, if it was initialized. 123 void timeTraceProfilerCleanup(); 124 125 /// Finish a time trace profiler running on a worker thread. 126 void timeTraceProfilerFinishThread(); 127 128 /// Is the time trace profiler enabled, i.e. initialized? 129 inline bool timeTraceProfilerEnabled() { 130 return getTimeTraceProfilerInstance() != nullptr; 131 } 132 133 /// Write profiling data to output stream. 134 /// Data produced is JSON, in Chrome "Trace Event" format, see 135 /// https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview 136 void timeTraceProfilerWrite(raw_pwrite_stream &OS); 137 138 /// Write profiling data to a file. 139 /// The function will write to \p PreferredFileName if provided, if not 140 /// then will write to \p FallbackFileName appending .time-trace. 141 /// Returns a StringError indicating a failure if the function is 142 /// unable to open the file for writing. 143 Error timeTraceProfilerWrite(StringRef PreferredFileName, 144 StringRef FallbackFileName); 145 146 /// Manually begin a time section, with the given \p Name and \p Detail. 147 /// Profiler copies the string data, so the pointers can be given into 148 /// temporaries. Time sections can be hierarchical; every Begin must have a 149 /// matching End pair but they can nest. 150 TimeTraceProfilerEntry *timeTraceProfilerBegin(StringRef Name, 151 StringRef Detail); 152 TimeTraceProfilerEntry * 153 timeTraceProfilerBegin(StringRef Name, 154 llvm::function_ref<std::string()> Detail); 155 156 TimeTraceProfilerEntry * 157 timeTraceProfilerBegin(StringRef Name, 158 llvm::function_ref<TimeTraceMetadata()> MetaData); 159 160 /// Manually begin a time section, with the given \p Name and \p Detail. 161 /// This starts Async Events having \p Name as a category which is shown 162 /// separately from other traces. See 163 /// https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview#heading=h.jh64i9l3vwa1 164 /// for more details. 165 TimeTraceProfilerEntry *timeTraceAsyncProfilerBegin(StringRef Name, 166 StringRef Detail); 167 168 // Mark an instant event. 169 void timeTraceAddInstantEvent(StringRef Name, 170 llvm::function_ref<std::string()> Detail); 171 172 /// Manually end the last time section. 173 void timeTraceProfilerEnd(); 174 void timeTraceProfilerEnd(TimeTraceProfilerEntry *E); 175 176 /// The TimeTraceScope is a helper class to call the begin and end functions 177 /// of the time trace profiler. When the object is constructed, it begins 178 /// the section; and when it is destroyed, it stops it. If the time profiler 179 /// is not initialized, the overhead is a single branch. 180 class TimeTraceScope { 181 public: 182 TimeTraceScope() = delete; 183 TimeTraceScope(const TimeTraceScope &) = delete; 184 TimeTraceScope &operator=(const TimeTraceScope &) = delete; 185 TimeTraceScope(TimeTraceScope &&) = delete; 186 TimeTraceScope &operator=(TimeTraceScope &&) = delete; 187 188 TimeTraceScope(StringRef Name) 189 : Entry(timeTraceProfilerBegin(Name, StringRef())) {} 190 TimeTraceScope(StringRef Name, StringRef Detail) 191 : Entry(timeTraceProfilerBegin(Name, Detail)) {} 192 TimeTraceScope(StringRef Name, llvm::function_ref<std::string()> Detail) 193 : Entry(timeTraceProfilerBegin(Name, Detail)) {} 194 TimeTraceScope(StringRef Name, 195 llvm::function_ref<TimeTraceMetadata()> Metadata) 196 : Entry(timeTraceProfilerBegin(Name, Metadata)) {} 197 ~TimeTraceScope() { 198 if (Entry) 199 timeTraceProfilerEnd(Entry); 200 } 201 202 private: 203 TimeTraceProfilerEntry *Entry = nullptr; 204 }; 205 206 } // end namespace llvm 207 208 #endif 209