ktrace-plan —
instructions 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
bold are
required.
- name
- The short name of this plan, which cannot contain whitespace, uppercase
letters, or underscores.
- version
- An integer version of the plan.
- radar_component_id
- A string ID to file radars against for issues with the plan.
- od_group_name
- A string name to send emails for questions about the plan.
- slack_channel
- A Slack channel to discuss the plan.
- synopsis
- A short, fewer-than-80-characters description of the plan.
- documentation
- A detailed description of the plan.
- settings
- A nested object that describes how to set up tracing, with these fields:
- kdebug_buffer_size
- A structure with the following keys that describes how to size
kdebug's buffer.
- base_memory_fraction
- A number between 0 and 0.5 that describes what fraction of the
device's memory to use at a minimum.
- per_cpu_memory_mib
- The number of mebibytes to add to the buffer size for each
CPU.
- kdebug_filter
- The filter description to apply to kdebug tracing for which events to
include.
- kdebug_filter_exclude
- Exclude a set of events from the earlier filter, to keep the length of
filters short.
- kdebug_coprocessor_tracing
- Control whether coprocessor events are included in the trace.
- kperf_actions
- An array of up to 31 actions to configure with kperf.
- samplers
- 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’.
- kperf_timers
- An array of up to 8 kperf timers to run actions periodically.
- period_microseconds
- The period of the timer, in microseconds.
- action_index
- The array index of the action when the timer period elapses.
- kperf_pet
- The Profile Every Thread (PET) settings to apply to kperf, an object
with these fields:
- mode
- Either ‘
original’ or
‘lightweight’.
- timer_index
- The timer to act as the PET timer.
- kperf_kdebug_triggers
- An array of at most one element to trigger kperf based on triggers:
- action_index
- The action to run when the filter matches.
- precise_filter
- A precise filter for matching events, describing at
ktrace(1).
- kperf_lazy_cpu
- An object describing the lazy sampling of CPUs, with these fields:
- action_index
- The action to run when the threshold is reached.
- threshold_microseconds
- The threshold in microseconds to wait before sampling the CPU
again.
- kperf_lazy_wait
- 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.
- providers
- An array of provider objects with the following fields:
- name
- A string name to find the provider.
- options
- A table of key-values that are sent to the provider and act as
options.
- required
- A boolean value specifying whether the provider can be omitted
safely.
- layers
- A dictionary from string layer name to layer object for the supported
layers of the plan.
- synopsis
- A brief description of the layer.
- settings
- The same settings object as the top-level field of the same name, but
only limited fields are supported.
- default_layers
- An array of layers to add automatically, by name.