KTRACE-PLAN(5) File Formats Manual KTRACE-PLAN(5)

ktrace-planinstructions for recording trace files

A ktrace plan file encodes how to record a trace file for analysis. It's a JSON file with a specific structure, described here. Fields marked in are required.

The short name of this plan, which cannot contain whitespace, uppercase letters, or underscores.
An integer version of the plan.
A string ID to file radars against for issues with the plan.
A string name to send emails for questions about the plan.
A Slack channel to discuss the plan.
A short, fewer-than-80-characters description of the plan.
A detailed description of the plan.
A nested object that describes how to set up tracing, with these fields:
A structure with the following keys that describes how to size kdebug's buffer.
A number between 0 and 0.5 that describes what fraction of the device's memory to use at a minimum.
The number of mebibytes to add to the buffer size for each CPU.
The filter description to apply to kdebug tracing for which events to include.
Exclude a set of events from the earlier filter, to keep the length of filters short.
Control whether coprocessor events are included in the trace.
An array of up to 31 actions to configure with kperf.
An array of samplers for this action, from the following list: ‘user_call_stack’, ‘kernel_call_stack’, ‘thread_info’, ‘thread_snapshot’, ‘thread_dispatch_info’, ‘thread_instructions_cycles’, ‘task_info’, ‘task_snapshot’, ‘task_memory_info’, ‘system_memory’.
An array of up to 8 kperf timers to run actions periodically.
The period of the timer, in microseconds.
The array index of the action when the timer period elapses.
The Profile Every Thread (PET) settings to apply to kperf, an object with these fields:
Either ‘original’ or ‘lightweight’.
The timer to act as the PET timer.
An array of at most one element to trigger kperf based on triggers:
The action to run when the filter matches.
A precise filter for matching events, describing at ktrace(1).
An object describing the lazy sampling of CPUs, with these fields:
The action to run when the threshold is reached.
The threshold in microseconds to wait before sampling the CPU again.
The same kind of field as ‘kperf_lazy_cpu’, except the threshold is applied to how long threads have waited before they're sampled again.
An array of provider objects with the following fields:
A string name to find the provider.
A table of key-values that are sent to the provider and act as options.
A boolean value specifying whether the provider can be omitted safely.
A dictionary from string layer name to layer object for the supported layers of the plan.
A brief description of the layer.
The same settings object as the top-level field of the same name, but only limited fields are supported.
An array of layers to add automatically, by name.

ktrace(5) and trace(1)

June 1, 2022 Darwin