Kernel tracing

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

Kernel trace format

The kernel trace format is pretty simple. See files ktrace.h and ktrace-def.h in system/ulib/zircon-internal/include/lib/zircon-internal for a description.

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>

Options:
  --help  - Duh.

Pretty-printing a kernel trace

The host tool ktrace-dump can be used to pretty-print a kernel trace.

Example:

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

host$ out/default.zircon/tools/netcp :/tmp/save.ktrace save.ktrace
host$ out/default.zircon/tools/ktrace-dump save.ktrace > save.dump

The pretty-printed 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.