clang-tools  9.0.0
Trace.h
Go to the documentation of this file.
1 //===--- Trace.h - Performance tracing facilities ---------------*- 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 // Supports writing performance traces describing clangd's behavior.
10 // Traces are consumed by implementations of the EventTracer interface.
11 //
12 //
13 // All APIs are no-ops unless a Session is active (created by ClangdMain).
14 //
15 //===----------------------------------------------------------------------===//
16 
17 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_TRACE_H_
18 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_TRACE_H_
19 
20 #include "Context.h"
21 #include "Function.h"
22 #include "llvm/ADT/Twine.h"
23 #include "llvm/Support/JSON.h"
24 #include "llvm/Support/raw_ostream.h"
25 
26 namespace clang {
27 namespace clangd {
28 namespace trace {
29 
30 /// A consumer of trace events. The events are produced by Spans and trace::log.
31 /// Implmentations of this interface must be thread-safe.
32 class EventTracer {
33 public:
34  virtual ~EventTracer() = default;
35 
36  /// Called when event that has a duration starts. \p Name describes the event.
37  /// Returns a derived context that will be destroyed when the event ends.
38  /// Usually implementations will store an object in the returned context
39  /// whose destructor records the end of the event.
40  /// The args are *Args, only complete when the event ends.
41  virtual Context beginSpan(llvm::StringRef Name, llvm::json::Object *Args) = 0;
42  // Called when a Span is destroyed (it may still be active on other threads).
43  // beginSpan() and endSpan() will always form a proper stack on each thread.
44  // The Context returned by beginSpan is active, but Args is not ready.
45  // Tracers should not override this unless they need to observe strict
46  // per-thread nesting. Instead they should observe context destruction.
47  virtual void endSpan(){};
48 
49  /// Called for instant events.
50  virtual void instant(llvm::StringRef Name, llvm::json::Object &&Args) = 0;
51 };
52 
53 /// Sets up a global EventTracer that consumes events produced by Span and
54 /// trace::log. Only one TracingSession can be active at a time and it should be
55 /// set up before calling any clangd-specific functions.
56 class Session {
57 public:
58  Session(EventTracer &Tracer);
59  ~Session();
60 };
61 
62 /// Create an instance of EventTracer that produces an output in the Trace Event
63 /// format supported by Chrome's trace viewer (chrome://tracing).
64 ///
65 /// The format is documented here:
66 /// https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview
67 std::unique_ptr<EventTracer> createJSONTracer(llvm::raw_ostream &OS,
68  bool Pretty = false);
69 
70 /// Records a single instant event, associated with the current thread.
71 void log(const llvm::Twine &Name);
72 
73 /// Records an event whose duration is the lifetime of the Span object.
74 /// This lifetime is extended when the span's context is reused.
75 ///
76 /// This is the main public interface for producing tracing events.
77 ///
78 /// Arbitrary JSON metadata can be attached while this span is active:
79 /// SPAN_ATTACH(MySpan, "Payload", SomeJSONExpr);
80 ///
81 /// SomeJSONExpr is evaluated and copied only if actually needed.
82 class Span {
83 public:
84  Span(llvm::Twine Name);
85  ~Span();
86 
87  /// Mutable metadata, if this span is interested.
88  /// Prefer to use SPAN_ATTACH rather than accessing this directly.
89  /// The lifetime of Args is the whole event, even if the Span dies.
90  llvm::json::Object *const Args;
91 
92 private:
93  WithContext RestoreCtx;
94 };
95 
96 /// Attach a key-value pair to a Span event.
97 /// This is not threadsafe when used with the same Span.
98 #define SPAN_ATTACH(S, Name, Expr) \
99  do { \
100  if (auto *Args = (S).Args) \
101  (*Args)[Name] = Expr; \
102  } while (0)
103 
104 } // namespace trace
105 } // namespace clangd
106 } // namespace clang
107 
108 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_TRACE_H_
Sets up a global EventTracer that consumes events produced by Span and trace::log.
Definition: Trace.h:56
virtual void instant(llvm::StringRef Name, llvm::json::Object &&Args)=0
Called for instant events.
static constexpr llvm::StringLiteral Name
A context is an immutable container for per-request data that must be propagated through layers that ...
Definition: Context.h:69
WithContext replaces Context::current() with a provided scope.
Definition: Context.h:189
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
void log(const llvm::Twine &Message)
Records a single instant event, associated with the current thread.
Definition: Trace.cpp:206
std::unique_ptr< EventTracer > createJSONTracer(llvm::raw_ostream &OS, bool Pretty)
Create an instance of EventTracer that produces an output in the Trace Event format supported by Chro...
Definition: Trace.cpp:201
llvm::json::Object *const Args
Mutable metadata, if this span is interested.
Definition: Trace.h:90
Records an event whose duration is the lifetime of the Span object.
Definition: Trace.h:82
virtual Context beginSpan(llvm::StringRef Name, llvm::json::Object *Args)=0
Called when event that has a duration starts.
A consumer of trace events.
Definition: Trace.h:32