ktrace(5) File Formats Manual ktrace(5)

ktrace — Darwin kernel trace file format

#include <ktrace_file.h>

ktrace files are the native format of Darwin's kernel trace system, which collects data about what a Darwin system is doing. ktrace is a binary file format made up of individual chunks, each containing their type and size. A chunk can be found in either the header or body of a ktrace file. Header chunks are guaranteed to be available at the beginning of the file and are written before body chunks. When parsing a ktrace file, unrecognized chunks should be skipped and chunks should not be required to be found in any order, aside from header chunks coming before body chunks.

Tools should not attempt to parse ktrace files directly, and should instead use the ktrace_file interface found in libktrace.

Individual chunks in a ktrace file have a 16-byte header:

size name
4 tag
2 major version
2 minor version
8 data size

The data contained in a chunk follows its header. Different ktrace file writers are given different ranges of s. Tags that have been allocated are declared in <ktrace_chunk.h>. The major and minor version correspond to the version of data found in a single chunk. The is intended to be updated when a breaking change in the format of a chunk's data occurs. The should be updated if old parsers can still read the data, but there may be extra information that will be missed. The is the number of bytes of data that follows the chunk header in the file.

Chunk headers must be aligned to 8 bytes, so if the data size is not a multiple of 8, additional padding bytes will be added to the end of the data before the next chunk header.

All ktrace files start with a header structure:

size name
4 magic number
2 major version
2 minor version
8 header size
4 timebase numerator
4 timebase denominator
8 timestamp
8 walltime seconds
4 walltime microseconds
4 minutes west of GMT
4 DST time enabled
4 flags

The latest version of trace files, V3, have the magic number 0x55aa0300. The version fields serve the same purpose as for individual chunks. The header size field is the size of the entire header, excluding the first 16 bytes. It includes the sizes of all header chunks and their chunk headers. Header chunks, if there are any, start directly after this structure, followed by normal chunks. A typical file might look like this:

size name
64 header structure
16 header chunk header
32 header chunk data
16 header chunk header
14 header chunk data
2 padding
16 normal chunk header
128 normal chunk data
16 normal chunk header
252 normal chunk data
4 optional padding

fs_usage(1) and ktrace(1)

February 10, 2020 Darwin