> [!CAUTION]
> **Caution:** In most cases you should use `ffx trace` to record traces, see [Record traces for performance analysis](https://fuchsia.dev/docs/development/tools/ffx/workflows/record-traces). However, this guide is useful if you don't have access to the `ffx` tool such as when you want to do a kernel trace in bringup builds.

The kernel writes records to an internal buffer to capture traces of various
actions. These traces can then be retrieved, printed, and viewed in a tool such
as [Perfetto](https://ui.perfetto.dev/).

## Kernel trace format

The kernel trace format uses [FXT](https://fuchsia.dev/docs/reference/tracing/trace-format).

## Trace buffer size

The size of the trace buffer is fixed at boot time and is controlled by
the [`ktrace.bufsize`](https://fuchsia.dev/docs/gen/boot-options#ktracebufsizeuint32_t) kernel command-line parameter. Its value is the
buffer size in megabytes. The default is 32MB.

## Control what to trace

You can control what to trace through the kernel command-line parameter
`ktrace.grpmask`. The value is specified as `0xNNN` and is a bitmask of tracing
groups to enable. See the **KTRACE*GRP*** values in
`system/ulib/zircon-internal/include/lib/zircon-internal/ktrace.h`. By default,
the value is `0xfff` which traces everything.

You can also dynamically control what to trace with the `ktrace` command-line
utility.

## `ktrace` command-line utility

You can control kernel tracing with the `ktrace` command-line utility.

> [!NOTE]
> **Note:** For more information about `ktrace`, see [Zircon Kernel Command Line Options](https://fuchsia.dev/docs/reference/kernel/kernel_cmdline).

Use `ktrace --help` to see all of the available commands:

```bash
ktrace --help
```

You should see an output like:

    Usage: ktrace [options] <control>
    Where <control> is one of:
      start <group_mask>  - start tracing
      stop                - stop tracing
      rewind              - rewind trace buffer
      written             - print bytes written to trace buffer
        Note: This value doesn't reset on "rewind". Instead, the rewind
        takes effect on the next "start".
      save <path>         - save contents of trace buffer to <path>

    Options:
      --help  - Duh.

## View a kernel trace

You can view a trace with [`ui.perfetto.dev`](https://ui.perfetto.dev/). Before you can view a trace, you
need to capture a trace.

1. Start the trace on the target:

   ```bash
   ktrace start 0xfff
   ... do something ...
   ```
2. Stop the trace:

   ```bash
   ktrace stop
   ```
3. Save the trace to `/tmp/save.ktrace`:

   ```bash
   ktrace save /tmp/save.ktrace
   ```
4. Use `fx cp` to copy the file to your development host:

       fx cp --to-host /tmp/save.ktrace save.fxt

5. View the trace file in [`ui.perfetto.dev`](https://ui.perfetto.dev/).

## Use with Fuchsia Tracing

Fuchsia's tracing system supports collecting kernel trace records through the
`ktrace_provider` trace provider. For more information about Fuchsia's tracing
system, see [Fuchsia tracing system](https://fuchsia.dev/docs/concepts/kernel/tracing-system).
[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/tracing/advanced/recording-a-kernel-trace.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/tracing/advanced/recording-a-kernel-trace.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/tracing/advanced/recording-a-kernel-trace.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/tracing/advanced/recording-a-kernel-trace.md "Edit the source code of this page")