clang-tools 8.0.0

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