When you instrument a Fuchsia component as a tracing provider, you can create
and observe various types of events. This document explains the differences
between the types of events, the best use cases for each type of event, how to
use events in your components, and the various arguments that you can use in a
tracing event.

## Events

A Fuchsia event type can be any of the following:

> [!NOTE]
> **Note:** In the Fuchsia trace format a tracing event is known as an [Event Record](https://fuchsia.dev/docs/reference/tracing/trace-format#event-record).

- [Instant event](https://fuchsia.dev/fuchsia-src/development/tracing/trace_events#instant-event) Marks a point of time that has a name, category, and optional arguments.
- [Duration event](https://fuchsia.dev/fuchsia-src/development/tracing/trace_events#duration-event) Marks two points in time and can contain a name, category, and optional arguments.
- [Counter event](https://fuchsia.dev/fuchsia-src/development/tracing/trace_events#counter-event) Captures numeric samples that are typically represented in Perfetto as a stacked area chart.
- [Flow event](https://fuchsia.dev/fuchsia-src/development/tracing/trace_events#flow-event) Describes flow handoffs between threads and across processes.
- [Async event](https://fuchsia.dev/fuchsia-src/development/tracing/trace_events#async-event) Allows specifying an `id` that links events across different threads together and places these events on a single track.
- [Custom Track event](https://fuchsia.dev/fuchsia-src/development/tracing/trace_events#custom-track-event) Allows grouping related duration and instant events on a dedicated, named track associated with the component's process (backed by a virtual thread).

In its most basic form, a trace event has a category (the first parameter) and
a name (the second parameter).

A trace event can accept up to 15 [arguments](https://fuchsia.dev/fuchsia-src/development/tracing/trace_events#arguments).

When you use trace events, it is important to understand how categories work.
The following are some key concepts related to categories:

- Categories allow you to group events so that you can enable or disable them together.
- Categories are typically short ASCII string literals of `[A-Za-z-_:]+` such as `gfx` or `audio`.
- Categories are global. Consider namespacing them to your component.
- Categories are not enabled by default. If you add a category, make sure that you specify it when you capture a trace with `--categories #default,your_category`.
- `ffx trace` supports prefix matching. If you run `ffx trace start --categories your_component::*`, this enables `your_component::category1`, `your_component::category2`, and any other associated categories.

When you use an event, make sure to include the relevant library in your code:

### C

> [!NOTE]
> **Note:** The header file is defined in [//zircon/system/ulib/trace/include/lib/trace/internal/event_common.h](https://cs.opensource.google/fuchsia/fuchsia/+/main:/zircon/system/ulib/trace/include/lib/trace/internal/event_common.h). See [Tracing: C and C++ macros](https://fuchsia.dev/docs/reference/tracing/c_cpp_macros) for the reference page.

    #include <lib/trace/event.h>

### C++

> [!NOTE]
> **Note:** The header file is defined in [/zircon/system/ulib/trace/include/lib/trace/internal/event_common.h](https://cs.opensource.google/fuchsia/fuchsia/+/main:/zircon/system/ulib/trace/include/lib/trace/internal/event_common.h). See [Tracing: C and C++ macros](https://fuchsia.dev/docs/reference/tracing/c_cpp_macros) for the reference page.

    #include <lib/trace/event.h>

### Rust

> [!NOTE]
> **Note:** See the [rustdoc page](https://fuchsia-docs.firebaseapp.com/rust/fuchsia_trace/index.html) for the `fuchsia_trace` crate reference page.

    use fuchsia_trace::{ArgValue, Scope, ...};

You can also see a [simple example](https://cs.opensource.google/fuchsia/fuchsia/+/main:/src/performance/example_trace_provider/README.md) in C++ on using
a trace provider.

### Instant event

This is the most basic of events. An instant event can mark a point of time that
has a name, category, and optional arguments.

Categories can optionally be registered, but most tracing providers do not.

> [!NOTE]
> **Note:** The trace scope is not used in Perfetto.

At the minimum, an instant trace has both a name and a category to differentiate
it:

### C

    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD);

### C++

    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD);

### Rust

    instant!("trace_category", "trace_name", Scope::Thread);

You can also make an instant event that includes additional arguments:

> [!NOTE]
> **Note:** For more information on arguments, see [Arguments](https://fuchsia.dev/fuchsia-src/development/tracing/trace_events#arguments).

### C

    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, argument_1, argument_1_value, argument_2, "argument_2_string");

### C++

    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, argument_1, argument_1_value, argument_2, "argument_2_string");

### Rust

    instant!("trace_category", "trace_name", Scope::Thread, argument_1 => argument_1_value, argument_2 => "argument_2_string");

In Perfetto, an instant event is indicated by a small arrow as shown in this
screenshot.

> [!NOTE]
> **Note:** The instant event is shown by a black box in the screenshot.

![A screenshot of the Perfetto trace viewer displaying the trace of a process
that is executing on multiple CPUs (CPU 0, CPU 1, CPU 2, and CPU 3). The event
is emitted at the 00:00:00.194617950 and shows a duration of 0s as it is an
instant event. The process is called `example_trace_provider.cm`.](https://fuchsia.dev/static/fuchsia-src/development/tracing/images/instant_event_perfetto.png "A view of an instant event from a trace using the Perfetto Viewer")

### Duration event

A duration event marks two points in time and can contain a name, category,
and optional arguments. Duration events can also nest within another duration
event and stack on top of one another.

At a minimum a duration trace has both a name and a category to differentiate
it:

> [!NOTE]
> **Note:** Duration events must **begin** and **end** as last in, first out.

### C

    TRACE_DURATION_BEGIN("trace_category", "example_duration");
    // Do some work
    TRACE_DURATION_END("trace_category", "example_duration");

### C++

    TRACE_DURATION_BEGIN("trace_category", "example_duration");
    // Do some work
    TRACE_DURATION_END("trace_category", "example_duration");

### Rust

    duration_begin!("trace_category", "example_duration");
    // Do some work
    duration_end!("trace_category", "example_duration");

Alternatively, you can define a duration event and automatically close it when
it goes out of scope using RAII (Resource acquisition is initialization) as follows::

### C

    {
      TRACE_DURATION("trace_category", "example_duration_raii");
      // Do some work
      TRACE_DURATION("trace_category", "nested duration", "argument_3", argument_3_value, "argument_4", argument_4_string);
      // nested_duration closes due to RAII
      // trace_duration_raii closes due to RAII
    }

### C++

    {
      TRACE_DURATION("trace_category", "example_duration_raii");
      // Do some work
      TRACE_DURATION("trace_category", "nested duration", "argument_3", argument_3_value, "argument_4", argument_4_string);
      // nested_duration closes due to RAII
      // trace_duration_raii closes due to RAII
    }

### Rust

    {
      duration!("trace_category", "example_duration_raii");
      // Do some work
      duration!("trace_category", "nested duration", argument_3 => argument_3_value, argument_4 => argument_4_string);
      // nested_duration closes due to RAII
      // trace_duration_raii closes due to RAII
    }

In Perfetto, a nested stack of durations looks as follows:

![A screenshot of the Perfetto trace viewer showing a timeline of events, with
the time from left to right. The top bar shows the text
"example_trace_provider.com 1617970". Below that, the timeline is split into two
sections, "initial-thread 1617972". Each of these has a bar showing the duration
of the event that is associated with each thread. Duration events with different
names are displayed with different colors: olive, green, blue, and dark green.
The duration events are stacked downwards, so the shorter durations are
contained within the larger duration above them.](https://fuchsia.dev/static/fuchsia-src/development/tracing/images/duration_event_perfetto.png "A view of a duration event from a trace using the Perfetto Viewer")

### Counter event

A counter event captures numeric samples that are typically represented in
Perfetto as a stacked area chart. When you use a counter event, you can use the
`id` to distinguish between multiple instances of counters that share the same
category and name within the system process. You can associate 1-15 numeric
arguments with an event, each of which is interpreted as a distinct time series.

This example shows a `counter_id` value and a data series passed to a counter
event:

> [!NOTE]
> **Note:** Counter `id`s must be unique for a given process, category, and name combination.

### C

    trace_counter_id_t counter_id = 555;
    uint32_t data = get_some_data();
    TRACE_COUNTER("trace_category", "trace_name", counter_id, "data_series", data);

### C++

    trace_counter_id_t counter_id = 555;
    uint32_t data = get_some_data();
    TRACE_COUNTER("trace_category", "trace_name", counter_id, "data_series", data);

### Rust

    let counter_id = 555;
    let data = get_some_data();
    counter!("trace_category", "trace_name", counter_id, "data_series" => data);

In Perfetto, a counter event looks as follows:

![A screenshot of the Perfetto trace viewer that shows the
`example_counter:somedataseries` counter event. To the right of the counter
event name there is a graph that rises over time, showing the counter increasing
in value.](https://fuchsia.dev/static/fuchsia-src/development/tracing/images/counter_event_perfetto.png "A view of a counter event from a trace using the Perfetto Viewer")

### Flow event

A flow event describes flow handoffs between threads and across processes. These
events must be enclosed in a duration event which represents where the flow
handoff occurs. Each flow event may also attach arguments. A flow begin
(`TRACE_FLOW_BEGIN` or `flow_begin`) event may be followed by a flow step
(`TRACE_FLOW_STEP` or `flow_step`) event.

> [!NOTE]
> **Note:** Flow events must be enclosed in a duration event. A flow event needs an enclosing duration event to serve as an anchor point for visualization in trace viewers (like Perfetto). If they are not enclosed, they will not be rendered.

> [!IMPORTANT]
> **Important:** Flow IDs are globally scoped in Perfetto.

Unlike some tracing systems where flow IDs are scoped to a flow name or
category, Perfetto tracks flow lines globally by their ID alone. If two
different active flows (even with different names or categories) share the
same ID concurrently, Perfetto will draw incorrect or ambiguous flow lines
connecting them.

To ensure correct flow visualization:
- **Use unique IDs** : In C/C++, use `TRACE_NONCE()` (unique within a
process) or `TRACE_RANDOM_ID()` (globally unique across
processes/components). In Rust, use `fuchsia_trace::Id::new()`.
Avoid using static numbers like `555`.
- **Do not reuse IDs concurrently** : If you must reuse an ID, ensure that
the previous flow using that ID has been completely ended (via
`TRACE_FLOW_END` or `flow_end!`) before beginning a new flow with that ID.

> [!NOTE]
> **Note:** Perfetto drops flow names and arguments.

Due to semantic differences in the way Perfetto represents flows natively,
the Perfetto trace processor and UI currently drop the flow names and any
arguments attached to flow events (such as those passed to
`TRACE_FLOW_BEGIN` or `TRACE_FLOW_STEP`). These names and arguments are
preserved in the FXT file but will not be visible in the Perfetto viewer.

**Best Practice** : If you need to associate diagnostic data with a flow step,
attach the arguments to the *enclosing duration event* instead of the flow
event itself. Enclosing duration events and their arguments are fully
rendered in Perfetto.

For example:

### C

    // Generate a unique flow ID
    trace_flow_id_t flow_id = TRACE_NONCE();

    // First duration where the flow begins
    {
      TRACE_DURATION("trace_category", "enclosing_duration_1");
      TRACE_FLOW_BEGIN("trace_category", "trace_flow_name", flow_id, "argument_1", argument_1_value);
    }

    // Optional intermediate duration where the flow steps
    {
      TRACE_DURATION("trace_category", "enclosing_duration_2");
      TRACE_FLOW_STEP("trace_category", "trace_flow_step_name", flow_id);
    }

    // Final duration where the flow ends
    {
      TRACE_DURATION("trace_category", "enclosing_duration_3");
      TRACE_FLOW_END("trace_category", "trace_flow_name", flow_id);
    }

### C++

    // Generate a unique flow ID
    trace_flow_id_t flow_id = TRACE_NONCE();

    // First duration where the flow begins
    {
      TRACE_DURATION("trace_category", "enclosing_duration_1");
      TRACE_FLOW_BEGIN("trace_category", "trace_flow_name", flow_id, "argument_1", argument_1_value);
    }

    // Optional intermediate duration where the flow steps
    {
      TRACE_DURATION("trace_category", "enclosing_duration_2");
      TRACE_FLOW_STEP("trace_category", "trace_flow_step_name", flow_id);
    }

    // Final duration where the flow ends
    {
      TRACE_DURATION("trace_category", "enclosing_duration_3");
      TRACE_FLOW_END("trace_category", "trace_flow_name", flow_id);
    }

### Rust

    // Generate a unique flow ID
    let flow_id = fuchsia_trace::Id::new();

    // First duration where the flow begins
    {
        duration!("trace_category", "enclosing_duration_1");
        flow_begin!("trace_category", "trace_flow_name", flow_id, "argument_1" => argument_1_value);
    }

    // Optional intermediate duration where the flow steps
    {
        duration!("trace_category", "enclosing_duration_2");
        flow_step!("trace_category", "trace_flow_step_name", flow_id);
    }

    // Final duration where the flow ends
    {
        duration!("trace_category", "enclosing_duration_3");
        flow_end!("trace_category", "trace_flow_name", flow_id);
    }

A flow event is represented as arrows in Perfetto, for example:

![A screenshot of the Perfetto trace viewer, showing a flow event of events on
different threads. Horizontal bars represent events, with their length
indicating duration. Each thread is connected with a curved arrow, which
indicates a sequence of events across these threads.](https://fuchsia.dev/static/fuchsia-src/development/tracing/images/flow_event_perfetto.png "A view of a flow event from a trace using the Perfetto Viewer")

### Async event

In a trace, instant and duration events are placed on the track of threads on
which they are produced. When working with multi-threaded async or thread pool
based code, events may be started and finished on different threads. Async
events allow specifying an `id` that links events across different threads
together and places these events on a single track.

An async begin (`TRACE_ASYNC_BEGIN` or `async_begin`) event may be followed by
async instant (`TRACE_ASYNC_INSTANT` or `async_instant`) events and must be
matched by an async end (`TRACE_ASYNC_END` or `async_end`) event with the same
category, name, and `id`.

Asynchronous events describe work which happens asynchronously and which may
span multiple threads. The `id` helps to correlate the progress of distinct
asynchronous operations which share the same category and name within the
same process. Asynchronous events within the same process that have matching
categories and ids are nested.

You can associate 0-15 arguments with an async event, each of which is used to
annotate the asynchronous operation with additional information. The arguments
that you provide to matching async begin, async instant, and async end events
are combined together in the trace; you do not need to repeat them.

### C

    trace_async_id_t async_id = 555;
    TRACE_ASYNC_BEGIN("trace_category", "trace_async_name", async_id, "argument_1", argument_1_value);
    TRACE_ASYNC_INSTANT("trace_category", "trace_async_instant_name", async_id);
    TRACE_ASYNC_END("trace_category", "trace_async_name", async_id);

### C++

    trace_async_id_t async_id = 555;
    TRACE_ASYNC_BEGIN("trace_category", "trace_async_name", async_id, "argument_1", argument_1_value);
    TRACE_ASYNC_INSTANT("trace_category", "trace_async_instant_name", async_id);
    TRACE_ASYNC_END("trace_category", "trace_async_name", async_id);

### Rust

    let async_id = 555;
    async_begin!(async_id, "trace_category", "trace_async_name", "argument_1" => argument_1_value);
    async_instant!(async_id, "trace_category", "trace_async_instant_name");
    async_end!(async_id, "trace_category", "trace_async_name");

In Perfetto, an async event is placed on its own named track and isn't placed
on the track of the thread that it was emitted from. An async event looks as
follows:

![A screenshot of the Perfetto trace viewer showing two async events:
`example_async` and `example_async2`. The `example_async` event displays a
`example_nested_async` below it. The screenshot also shows 2 blue arrows in the
`example_async` event and 2 blue arrows in the `example_async2` event which
indicate instant events.](https://fuchsia.dev/static/fuchsia-src/development/tracing/images/async_event_perfetto.png "A view of a flow event from a trace using the Perfetto Viewer")

### Custom Track event

In a trace, instant and duration events are placed on the track of the thread on
which they are produced. In some cases, you want to group related events (such as
state machine transitions, status changes, or power levels) on a dedicated, named
track associated with your component's process.

Custom Track events allow you to define a `Track` object once and then emit
instants and durations to that track. Under the hood, this is implemented using
virtual threads (`VThread`).

> [!NOTE]
> **Note:** This API is currently supported in **Rust** (starting from API level 31).

To use a custom track:

1. Create a `Track` object during component initialization.
2. Emit events to the track using `track_instant!`, `track_duration!`, `track_duration_begin!`, and `track_duration_end!`.

> [!NOTE]
> **Note:** This macro creates variables for `args` and `_scope` in the enclosing scope and relies on Rust's lifetime rules to drop the duration guard to calculate the duration. If you need to invoke `track_duration!` multiple times in the same function, you must wrap each invocation in its own nested lexical block `{ ... }` to have separate duration events emitted.

For example:

### Rust

    // 1. Create the track once (e.g., during component initialization)
    let my_track = trace::Track::new("My State Machine");

    // 2. Emit a scoped duration that automatically closes at the end of the block
    {
        track_duration!("trace_category", my_track, "Idle State");
        // Do some work...
    }

    // 3. Emit a transient instant event on the track
    track_instant!("trace_category", my_track, "Stimulus Received", "type" => "button_press");

    // 4. Manual duration begin/end (e.g., for non-lexical scopes)
    track_duration_begin!("trace_category", my_track, "Active State");
    // Do some work...
    track_duration_end!("trace_category", my_track, "Active State");

### Process-Wide Shared Tracks (Recommended for Reusable Code)

If your tracing calls occur inside functions or helper modules that are executed multiple times (such as request handlers, transaction steps, or download loops), creating a `Track` locally inside the function will generate a new virtual thread ID for every invocation. This causes the visualizer to render each invocation on a separate track.

To group all events onto the **same** visual track process-wide, you should declare a process-wide static track using `std::sync::LazyLock`:

### Rust

    // 1. Declare the track as a process-wide static using LazyLock
    static DOWNLOAD_TRACK: std::sync::LazyLock<trace::Track> = std::sync::LazyLock::new(|| {
        trace::Track::new("http-client-download-blob")
    });

    // 2. Reference the static track in your function
    async fn download_blob_impl(url: &str) {
        let track = &*DOWNLOAD_TRACK;

        // Scoped duration on the process-wide shared track
        track_duration!("trace_category", track, "http-client-download-blob", "url" => url);
    }

In Perfetto, a custom track is cleanly nested inside your component's process group, right alongside the physical threads. The track is consistently named after the `Track` object name (e.g., "My State Machine"), and the states appear as solid duration blocks, while instant events appear as small diamond arrows directly on the track.

![A screenshot of the Perfetto trace viewer showing a Custom Track named](https://fuchsia.dev/static/fuchsia-src/development/tracing/images/sample_track.png "A view of a Custom Track event from a trace using the Perfetto Viewer")

## Arguments

You can use the following types of events in a Fuchsia trace:

- Null arguments
- Numeric types
- String types
- Pointers
- KOID
- Booleans

### Null arguments

A null argument is just a name a no data.

For example:

### C

    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "SomeNullArg", TA_NULL());

### C++

    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "SomeNullArg", nullptr);

### Rust

    instant!("trace_category", "trace_name", Scope::Thread, "SomeNullArg" => ());

### Numeric types

A numeric type is any `int` or `float` data type.

For example:

### C

    // Standard int types
    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "Someuint32", TA_UINT32(2145));
    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "Someuint64", TA_UINT64(423621626134123415));
    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "Someint32", TA_INT32(-7));
    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "Someint64", TA_INT64(-234516543631231));
    // Doubles
    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "Somedouble", TA_DOUBLE(3.1415));

### C++

    // Standard int types
    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "Someuint32", 2145);
    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "Someuint64", 423621626134123415);
    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "Someint32", -7);
    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "Someint64", -234516543631231);
    // Doubles
    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "Somedouble", 3.1415);

### Rust

    // Standard int types
    instant!("trace_category", "trace_name", Scope::Thread, "Someuint32" => 2145);
    instant!("trace_category", "trace_name", Scope::Thread, "Someuint64" => 423621626134123415);
    instant!("trace_category", "trace_name", Scope::Thread, "Someint32" => -7);
    instant!("trace_category", "trace_name", Scope::Thread, "Someint64" => -234516543631231);
    // Doubles
    instant!("trace_category", "trace_name", Scope::Thread, "Somedouble" => 3.1415);

### String types

A string type is any `string` data type.

For example:

### C

    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "ping", "pong");

### C++

    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "ping", "pong");

### Rust

    instant!("trace_category", "trace_name", Scope::Thread, "ping" => "pong");

### Pointers

A pointer is formatted in hex in the Perfetto viewer. You can also specifically
specify the trace argument type when type deduction would otherwise resolve
to the wrong data type.

For example:

### C

    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "somepointer", &i, "someotherpointer", &i, TA_POINTER(0xABCD));

### C++

    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "somepointer", &i, "someotherpointer", &i, 0xABCD);

### Rust

    let x: u64 = 123;
    instant!("trace_category", "trace_name", Scope::Thread, "SomeOtherPointer" => &x as *const u64);

### KOID

A KOID is the id of a kernel object and have their own data type to distinguish
them from regular `u64` data types.

For example:

### C

    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "somekoid", TA_KOID(0x0012));

### C++

    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "somekoid", TA_KOID(0x0012));

### Rust

    let koid: zx::Koid = vmo.get_koid()?;
    instant!("trace_category", "trace_name", Scope::Thread, "somekoid" => koid);

### Booleans

A boolean displays as either `true` or `false`.

For example:

### C

    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "somebool", TA_BOOL(true));
    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "someotherbool", TA_BOOL(false));

### C++

    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "somebool", true);
    TRACE_INSTANT("trace_category", "trace_name", TRACE_SCOPE_THREAD, "someotherbool", false);

### Rust

    instant!("trace_category", "trace_name", Scope::Thread, "somebool" => true);
    instant!("trace_category", "trace_name", Scope::Thread, "someotherbool" => false);

[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/tracing/trace_events.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/tracing/trace_events.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/tracing/trace_events.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/tracing/trace_events.md "Edit the source code of this page")