1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
|
# Time Trace and Profiling
Use Google's [Perfetto](https://ui.perfetto.dev/) to visualize time traces, enabling simple profiling of your C++. Glaze writes out JSON traces conformant to Google's [Trace Event Format](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview).
> The glz::trace class is entirely thread safe.
Glaze provides `begin` and `end` members for duration traces. Asynchronous traces use `async_begin` and `async_end`.
An example of the API in use:
```c++
#include "glaze/trace/trace.hpp"
glz::trace trace{}; // make a structure to store a trace
trace.begin("my event name");
// compute something here
trace.end("my event name");
auto ec = glz::write_file_json(trace, "trace.json", std::string{});
```
Or, for async events:
```c++
glz::trace trace{}; // make a structure to store a trace
trace.async_begin("my event name");
// compute something here
trace.async_end("my event name");
```
## Args (metadata)
Glaze allows `args` as an additional argument to `begin` and `end` methods, which will provide metadata in [Perfetto](https://ui.perfetto.dev/).
```c++
// arguments could be any type that can be serialized to JSON
trace.begin("my event name", arguments);
// do stuff
trace.end("my event name");
```
Example with a string:
```c++
trace.begin("my event name", "My event description");
// do stuff
trace.end("my event name");
```
## Runtime Disabling Trace
```c++
trace.disabled = true; // no data will be collected
```
## Compile Time Disabling Trace
A boolean template parameter `Enabled` defaults to `true`, but can be set to `false` to compile time disable tracing and thus remove the binary when compiled.
```c++
glz::trace<false> trace{};
```
When disabled, writing `glz::trace` as JSON will result in an empty JSON object: `{}`
## Scoped Tracing
Automatically ends the event when it goes out of scope:
```c++
{
auto scoper = trace.scope("event name"); // trace.begin("event name") called
// run event
}
// end("event name") automatically called when leaving scope
```
Automatically ends the async event when it goes out of scope:
```c++
{
auto scoper = trace.async_scope("event name"); // trace.async_begin("event name") called
// run event
}
// trace.async_end("event name") automatically called when leaving scope
```
## Global tracing
It can be bothersome to pass around a `glz::trace` instance. A global instance can be made for convenience:
```c++
inline glz::trace global_trace{};
```
|
