Struct FtraceConfig

pub struct FtraceConfig {

    pub ftrace_events: Vec<String>,
    pub atrace_categories: Vec<String>,
    pub atrace_apps: Vec<String>,
    pub atrace_categories_prefer_sdk: Vec<String>,
    pub buffer_size_kb: Option<u32>,
    pub drain_period_ms: Option<u32>,
    pub drain_buffer_percent: Option<u32>,
    pub compact_sched: Option<CompactSchedConfig>,
    pub print_filter: Option<PrintFilter>,
    pub symbolize_ksyms: Option<bool>,
    pub ksyms_mem_policy: Option<i32>,
    pub initialize_ksyms_synchronously_for_testing: Option<bool>,
    pub throttle_rss_stat: Option<bool>,
    pub disable_generic_events: Option<bool>,
    pub syscall_events: Vec<String>,
    pub enable_function_graph: Option<bool>,
    pub function_filters: Vec<String>,
    pub function_graph_roots: Vec<String>,
    pub preserve_ftrace_buffer: Option<bool>,
    pub use_monotonic_raw_clock: Option<bool>,
    pub instance_name: Option<String>,
    pub buffer_size_lower_bound: Option<bool>,
}

Next id: 30

Fields

ftrace_events: Vec<String>

Ftrace events to record, example: “sched/sched_switch”.

atrace_categories: Vec<String>

Android-specific event categories:

atrace_apps: Vec<String>

atrace_categories_prefer_sdk: Vec<String>

Some processes can emit data through atrace or through the perfetto SDK via the “track_event” data source. For these categories, the SDK will be preferred, if possible, for this config.

buffer_size_kb: Option<u32>

Size of each per-cpu kernel ftrace ring buffer. Not guaranteed if there are multiple concurrent tracing sessions, as the buffers cannot be resized without pausing recording in the kernel.

drain_period_ms: Option<u32>

If set, specifies how often the tracing daemon reads from the kernel ring buffer. Not guaranteed if there are multiple concurrent tracing sessions. Leave unset unless you’re fine-tuning a local config.

drain_buffer_percent: Option<u32>

If set, the tracing daemon will read kernel ring buffers as soon as they’re filled past this percentage of occupancy. In other words, a value of 50 means that a read pass is triggered as soon as any per-cpu buffer is half-full. Not guaranteed if there are multiple concurrent tracing sessions. Currently does nothing on Linux kernels below v6.9. Introduced in: perfetto v48.

compact_sched: Option<CompactSchedConfig>

print_filter: Option<PrintFilter>

symbolize_ksyms: Option<bool>

Enables symbol name resolution against /proc/kallsyms. It requires that either traced_probes is running as root or that kptr_restrict has been manually lowered. It does not disclose KASLR, symbol addresses are mangled.

ksyms_mem_policy: Option<i32>

initialize_ksyms_synchronously_for_testing: Option<bool>

👎Deprecated

By default the kernel symbolizer is lazily initialized on a deferred task to reduce ftrace’s time-to-start-recording. Unfortunately that makes ksyms integration tests hard. This flag forces the kernel symbolizer to be initialized synchronously on the data source start and hence avoiding timing races in tests. DEPRECATED in v28 / Android U. This is now the default behavior, setting it to true is a no-op.

throttle_rss_stat: Option<bool>

When this boolean is true AND the ftrace_events contains “kmem/rss_stat”, this option causes traced_probes to enable the “kmem/rss_stat_throttled” event instead if present, and fall back to “kmem/rss_stat” if not present. The historical context for this is the following:

• Up to Android S (12), the rss_stat was internally throttled in its kernel implementation.
• A change introduced in the kernels after S has introduced a new “rss_stat_throttled” making the original “rss_stat” event unthrottled (hence very spammy).
• Not all Android T/13 devices will receive a new kernel though, hence we need to deal with both cases. For more context: go/rss-stat-throttled.

disable_generic_events: Option<bool>

If true, avoid enabling events that aren’t statically known by traced_probes. Otherwise, the default is to emit such events as GenericFtraceEvent protos. Prefer to keep this flag at its default. This was added for Android tracing, where atrace categories and/or atrace HAL requested events can expand to events that aren’t of interest to the tracing user. Introduced in: Android T.

syscall_events: Vec<String>

The subset of syscalls to record. To record all syscalls, leave this unset and add “ftrace_events: raw_syscalls/sys_{enter,exit}” to the config.

• before perfetto v43, requires the config to also enable raw_syscalls/sys_{enter,exit}.
• perfetto v43+ does the right thing if you set only this field. Example: [“sys_read”, “sys_open”]. Introduced in: Android U.

enable_function_graph: Option<bool>

If true, enable the “function_graph” kernel tracer that emits events whenever a kernel function is entered and exited (funcgraph_entry/funcgraph_exit). Notes on use:

• Requires |symbolize_ksyms| for function name resolution.
• Use |function_filters| or |function_graph_roots| to constrain the traced set of functions, otherwise the event bandwidth will be too high for practical use.
• The data source might be rejected if there is already a concurrent ftrace data source that does not use function graph itself, as we do not support switching kernel tracers mid-trace.
• Requires a kernel compiled with CONFIG_FUNCTION_GRAPH_TRACER. This is enabled if “cat /sys/kernel/tracing/available_tracers” includes “function_graph”. Android:
• Available only on debuggable builds.
• Introduced in: Android U.

function_filters: Vec<String>

Constrains the set of functions traced when |enable_function_graph| is true. Supports globs, e.g. “sched*”. You can specify multiple filters, in which case all matching functions will be traced. See kernel documentation on ftrace “set_ftrace_filter” file for more details. Android:

• Available only on debuggable builds.
• Introduced in: Android U.

function_graph_roots: Vec<String>

If |enable_function_graph| is true, trace this set of functions and all of its callees. Supports globs. Can be set together with |function_filters|, in which case only callees matching the filter will be traced. If setting both, you most likely want all roots to also be included in |function_filters|. Android:

• Available only on debuggable builds.
• Introduced in: Android U.

preserve_ftrace_buffer: Option<bool>

If true, does not clear ftrace buffers before the start of the program. This makes sense only if this is the first ftrace data source instance created after the daemon has been started. Can be useful for gathering boot traces, if ftrace has been separately configured (e.g. via kernel commandline).

use_monotonic_raw_clock: Option<bool>

If true, overrides the default timestamp clock and uses a raw hardware based monotonic clock for getting timestamps.

• Introduced in: Android U.

instance_name: Option<String>

If |instance_name| is not empty, then attempt to use that tracefs instance for event recording. Normally, this means /sys/kernel/tracing/instances/$instance_name.

The name “hyp” is reserved.

The instance must already exist, the tracing daemon will not create it for you as it typically doesn’t have such permissions. Only a subset of features is guaranteed to work with non-default instances, at the time of writing:

• ftrace_events
• buffer_size_kb

buffer_size_lower_bound: Option<bool>

If true, |buffer_size_kb| is interpreted as a lower bound, allowing the implementation to choose a bigger buffer size.

Most configs for perfetto v43+ should simply leave both fields unset.

If you need a config compatible with a range of perfetto builds and you used to set a non-default buffer_size_kb, consider setting both fields. Example: buffer_size_kb: 4096 buffer_size_lower_bound: true On older builds, the per-cpu buffers will be exactly 4 MB. On v43+, buffers will be at least 4 MB. In both cases, neither is guaranteed if there are other concurrent perfetto ftrace sessions, as the buffers cannot be resized without pausing the recording in the kernel. Introduced in: perfetto v43.

Implementations

impl FtraceConfig

pub fn buffer_size_kb(&self) -> u32

Returns the value of buffer_size_kb, or the default value if buffer_size_kb is unset.

pub fn drain_period_ms(&self) -> u32

Returns the value of drain_period_ms, or the default value if drain_period_ms is unset.

pub fn symbolize_ksyms(&self) -> bool

Returns the value of symbolize_ksyms, or the default value if symbolize_ksyms is unset.

pub fn initialize_ksyms_synchronously_for_testing(&self) -> bool

Returns the value of initialize_ksyms_synchronously_for_testing, or the default value if initialize_ksyms_synchronously_for_testing is unset.

pub fn throttle_rss_stat(&self) -> bool

Returns the value of throttle_rss_stat, or the default value if throttle_rss_stat is unset.

pub fn disable_generic_events(&self) -> bool

Returns the value of disable_generic_events, or the default value if disable_generic_events is unset.

pub fn ksyms_mem_policy(&self) -> KsymsMemPolicy

Returns the enum value of ksyms_mem_policy, or the default if the field is unset or set to an invalid enum value.

pub fn set_ksyms_mem_policy(&mut self, value: KsymsMemPolicy)

Sets ksyms_mem_policy to the provided enum value.

pub fn enable_function_graph(&self) -> bool

Returns the value of enable_function_graph, or the default value if enable_function_graph is unset.

pub fn preserve_ftrace_buffer(&self) -> bool

Returns the value of preserve_ftrace_buffer, or the default value if preserve_ftrace_buffer is unset.

pub fn use_monotonic_raw_clock(&self) -> bool

Returns the value of use_monotonic_raw_clock, or the default value if use_monotonic_raw_clock is unset.

pub fn instance_name(&self) -> &str

Returns the value of instance_name, or the default value if instance_name is unset.

pub fn buffer_size_lower_bound(&self) -> bool

Returns the value of buffer_size_lower_bound, or the default value if buffer_size_lower_bound is unset.

pub fn drain_buffer_percent(&self) -> u32

Returns the value of drain_buffer_percent, or the default value if drain_buffer_percent is unset.

Trait Implementations

impl Clone for FtraceConfig

fn clone(&self) -> FtraceConfig

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FtraceConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for FtraceConfig

fn default() -> Self

Returns the “default value” for a type.

impl Message for FtraceConfig

fn encoded_len(&self) -> usize

Returns the encoded length of the message without a length delimiter.

fn clear(&mut self)

Clears the message, resetting all fields to their default.

fn encode<B>(&self, buf: &mut B) -> Result<(), EncodeError>

where B: BufMut, Self: Sized,

Encodes the message to a buffer.

fn encode_to_vec(&self) -> Vec<u8>

where Self: Sized,

Encodes the message to a newly allocated buffer.

fn encode_length_delimited<B>(&self, buf: &mut B) -> Result<(), EncodeError>

where B: BufMut, Self: Sized,

Encodes the message with a length-delimiter to a buffer.

fn encode_length_delimited_to_vec(&self) -> Vec<u8>

where Self: Sized,

Encodes the message with a length-delimiter to a newly allocated buffer.

fn decode<B>(buf: B) -> Result<Self, DecodeError>

where B: Buf, Self: Default,

Decodes an instance of the message from a buffer.

fn decode_length_delimited<B>(buf: B) -> Result<Self, DecodeError>

where B: Buf, Self: Default,

Decodes a length-delimited instance of the message from the buffer.

fn merge<B>(&mut self, buf: B) -> Result<(), DecodeError>

where B: Buf, Self: Sized,

Decodes an instance of the message from a buffer, and merges it into self.

fn merge_length_delimited<B>(&mut self, buf: B) -> Result<(), DecodeError>

where B: Buf, Self: Sized,

Decodes a length-delimited instance of the message from buffer, and merges it into self.

impl PartialEq for FtraceConfig

fn eq(&self, other: &FtraceConfig) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for FtraceConfig