Skip to content

# Time Trace and Profiling

Use Google's Perfetto to visualize time traces, enabling simple profiling of your C++. Glaze writes out JSON traces conformant to Google's Trace Event Format.

> 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:

    #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:

    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.

    // 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:

    trace.begin("my event name", "My event description");
    // do stuff
    trace.end("my event name");

## Runtime Disabling Trace

    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.

    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:

    {
      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:

    {
      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:

    inline glz::trace global_trace{};