Recording a kernel trace

The kernel traces various actions by writing records to an internal buffer, which can later be retrieved, printed, and viewed.

Kernel trace format

The kernel trace format uses FXT

Controlling what to trace

Control of what to trace is provided by a 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. The default is 0xfff, which traces everything.

What to trace can also be controlled by the ktrace command-line utility, described below.

Trace buffer size

The size of the trace buffer is fixed at boot time and is controlled by the ktrace.bufsize kernel command-line parameter. Its value is the buffer size in megabytes. The default is 32MB.

ktrace command-line utility

Kernel tracing may be controlled with the ktrace command-line utility.

$ ktrace --help
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>

  --help  - Duh.

Viewing kernel trace

Traces can be uploaded to to be viewed. Alternatively, the host tool trace2json can be used to export a trace to a more readable json output.


First collect the trace on the target:

$ ktrace start 0xfff
... do something ...
$ ktrace stop
$ ktrace save /tmp/save.ktrace

Then copy the file to the development host, and export it:

host$ out/default/host-tools/netcp :/tmp/save.ktrace save.fxt
host$ fx trace2json < save.fxt > save.json

The output can be quite voluminous, thus it's recommended to send it to a file and then view it in your editor or whatever.

Use with Fuchsia Tracing

Fuchsia's tracing system supports collecting kernel trace records through the ktrace_provider trace provider. For documentation of Fuchsia's tracing system see the documentation in Fuchsia tracing system.

More information

More information on ktrace can be found in the full list of kernel command line parameters.