This page describes how to record and visualize a trace on a Fuchsia
device with the [Fuchsia tracing system](https://fuchsia.dev/docs/concepts/kernel/tracing-system).

## Prerequisites

> [!IMPORTANT]
> **Important:** Tracing is only enabled for `core` and `eng` build types in Fuchsia images. Make sure that the Fuchsia image you use is of `core` or `eng` build type. In other words, if you're to build a Fuchsia image from the Fuchsia source checkout or download a Fuchsia prebuilt image, make sure that the image's build type is **not** `user` or `userdebug`.

Many existing Fuchsia components are already registered as trace providers, whose
trace data often provide a sufficient overview of the system. For this reason,
if you only need to record a general trace (for instance, to include details
in a bug report), you may proceed to the sections below. However, if you want
to collect additional, customized trace events from a specific component, you need
to complete the following tasks first:

- [Register your component as a trace provider](https://fuchsia.dev/docs/development/tracing/tutorial/register-a-trace-provider)
- [Add tracing in your component's code](https://fuchsia.dev/docs/development/tracing/tutorial/add-tracing-in-code)

## Record a trace

To record a trace on a Fuchsia device from your host machine,
run the following command:

    ffx trace start --duration <SECONDS>

This command starts a trace with the default settings, capturing
a general overview of the target device.

The trace continues for the specified duration (or until the `ENTER` key
is pressed if a duration is not specified). When the trace is finished, the
trace data is automatically saved to the `trace.fxt` file in the
current directory (or `trace.fxt.zst` if the `--compressed` flag is used;
you can also specify a custom filename using the `--output` flag;
for example, `ffx trace start --output <FILE_PATH>`). To visualize the trace
results stored in this file, see the [Visualize a trace](https://fuchsia.dev/fuchsia-src/development/tracing/tutorial/record-and-visualize-a-trace#visualize-a-trace)
section below.

> [!NOTE]
> **Note:** For more details on the `ffx trace` commands and options, see [Record traces for performance analysis](https://fuchsia.dev/docs/development/tools/ffx/workflows/record-traces).

## Visualize a trace

[Fuchsia trace format](https://fuchsia.dev/docs/reference/tracing/trace-format) (`.fxt`) is Fuchsia's
binary format that directly encodes the original trace data. To
visualize an `.fxt` (or `.fxt.zst` compressed) trace file, you can use the
[Perfetto viewer](https://ui.perfetto.dev).

You can visualize trace results using either of the following methods:

- **Upload to GCS:** Pass the `--upload` flag when recording (for example, `ffx trace start --upload`). Upon trace completion, the trace is uploaded to Google Cloud Storage (GCS) and a direct link to the Perfetto Trace Viewer is displayed in the output.
- **Open a local file manually:**
  1. Visit the [Perfetto viewer](https://ui.perfetto.dev) site on a web browser.
  2. Click **Open trace file** on the navigation bar.
  3. Select your `.fxt` or `.fxt.zst` file from the host machine.

This viewer also allows you to query the trace data using SQL. For practical
query recipes and automated triage tools, see
[Analyze traces with PerfettoSQL and fx perf-analyze](https://fuchsia.dev/docs/development/tracing/analyze-traces-with-sql).

## Categories

Categories allow you to control which events you want to see. For example:

- Trace with all the default categories as well as "cat":

      ffx trace start --categories '#default,cat'

- Trace with no defaults, only scheduler and thread/process data:

      ffx trace start --categories "kernel:sched,kernel:meta"

### Useful categories

#### kernel:sched + kernel:meta

High granularity overview of what is running on each CPU

![kernel:sched information](https://fuchsia.dev/static/fuchsia-src/development/tracing/tutorial/images/sched.png "A view of the scheduler data in the Perfetto Viewer")

#### kernel:ipc

Emit an event for each FIDL call and connect them with flows

![kernel:ipc information](https://fuchsia.dev/static/fuchsia-src/development/tracing/tutorial/images/ipc.png "A view of the ipc data in the Perfetto Viewer")

#### kernel:syscall

Emit an event for every syscall system wide

![gfx information](https://fuchsia.dev/static/fuchsia-src/development/tracing/tutorial/images/syscall.png "A view of syscall events in the Perfetto Viewer")

#### gfx

View frame timing breakdowns

![gfx information](https://fuchsia.dev/static/fuchsia-src/development/tracing/tutorial/images/gfx.png "A view of events emitted each frame in the Perfetto Viewer")
[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/tracing/tutorial/record-and-visualize-a-trace.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/tracing/tutorial/record-and-visualize-a-trace.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/tracing/tutorial/record-and-visualize-a-trace.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/tracing/tutorial/record-and-visualize-a-trace.md "Edit the source code of this page")