blob: d00d7c5460fc1273f39e0ac74a1648d6f75e4a62 [file] [log] [blame] [view]
# 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](/docs/concepts/tracing/README.md).