TraceConfig

The overall config that is used when starting a new tracing session through ProducerPort::StartTracing(). It contains the general config for the logging buffer(s) and the configs for all the data source being enabled.

Defined in trace_config.proto

Fields:

Field	Type	Description
buffers	BufferConfig[]
data_sources	DataSource[]
builtin_data_sources	BuiltinDataSource
duration_ms	uint32	If specified, the trace will be stopped `duration_ms` after starting. This does not count the time the system is suspended, so we will run for duration_ms of system activity, not wall time. However in case of traces with triggers, see TriggerConfig.trigger_timeout_ms instead.
enable_extra_guardrails	bool	This is set when --dropbox is passed to the Perfetto command line client and enables guardrails that limit resource usage for traces requested by statsd.
lockdown_mode	LockdownModeOperation	Reject producers that are not running under the same UID as the tracing service.
producers	ProducerConfig[]
statsd_metadata	StatsdMetadata	Statsd-specific metadata.
write_into_file	bool	When true && `output_path` is empty, the EnableTracing() request must provide a file descriptor. The service will then periodically read packets out of the trace buffer and store it into the passed file. If `output_path` is not empty no fd should be passed, the service will create a new file and write into that (see comment below).
output_path	string	This must point to a non-existing file. If the file exists the service will NOT overwrite and will fail instead as a security precaution. On Android, when this is used with the system traced, the path must be within /data/misc/perfetto-traces/ or the trace will fail. This option has been introduced in Android R. Before R write_into_file can be used only with the "pass a file descriptor over IPC" mode.
file_write_period_ms	uint32	Optional. If non-zero tunes the write period. A min value of 100ms is enforced (i.e. smaller values are ignored).
max_file_size_bytes	uint64	Optional. When non zero the periodic write stops once at most X bytes have been written into the file. Tracing is disabled when this limit is reached, even if `duration_ms` has not been reached yet.
guardrail_overrides	GuardrailOverrides
deferred_start	bool	When true, data sources are not started until an explicit call to StartTracing() on the consumer port. This is to support early initialization and fast trace triggering. This can be used only when the Consumer explicitly triggers the StartTracing() method. This should not be used in a remote trace config via statsd, doing so will result in a hung trace session.
flush_period_ms	uint32	When set, it periodically issues a Flush() to all data source, forcing them to commit their data into the tracing service. This can be used for quasi-real-time streaming mode and to guarantee some partial ordering of events in the trace in windows of X ms.
flush_timeout_ms	uint32	Wait for this long for producers to acknowledge flush requests. Default 5s.
data_source_stop_timeout_ms	uint32	Wait for this long for producers to acknowledge stop requests. Default 5s.
notify_traceur	bool	Android-only. If set, sends an intent to the Traceur system app when the trace ends to notify it about the trace readiness.
bugreport_score	int32	Android-only. If set to a value > 0, marks the trace session as a candidate for being attached to a bugreport. This field effectively acts as a z-index for bugreports. When Android's dumpstate runs perfetto --save-for-bugreport, traced will pick the tracing session with the highest score (score <= 0 is ignored), will steal its contents, save the trace into a known path and stop prematurely. This field was introduced in Android S.
trigger_config	TriggerConfig
activate_triggers	string[]	When this is non-empty the perfetto command line tool will ignore the rest of this TraceConfig and instead connect to the perfetto service as a producer and send these triggers, potentially stopping or starting traces that were previous configured to use a TriggerConfig.
incremental_state_config	IncrementalStateConfig
allow_user_build_tracing	bool	Additional guardrail used by the Perfetto command line client. On user builds when --dropbox is set perfetto will refuse to trace unless this is also set. Added in Q.
unique_session_name	string	If set the tracing service will ensure there is at most one tracing session with this key.
compression_type	CompressionType
incident_report_config	IncidentReportConfig
trace_uuid_msb	int64	An identifier clients can use to tie this trace to other logging. Alternative encoding of trace_uuid as two int64s.
trace_uuid_lsb	int64

TraceConfig.BufferConfig

Defined in trace_config.proto

Fields:

Field	Type	Description
size_kb	uint32
fill_policy	FillPolicy

TraceConfig.BufferConfig.FillPolicy

Defined in trace_config.proto

Enum values:

Name	Value	Description
UNSPECIFIED	0
RING_BUFFER	1	Default behavior. The buffer operates as a conventional ring buffer. If the writer is faster than the reader (or if the reader reads only after tracing is stopped) newly written packets will overwrite old packets.
DISCARD	2	Behaves like RING_BUFFER as long as there is space in the buffer or the reader catches up with the writer. As soon as the writer hits an unread chunk, it stops accepting new data in the buffer.

TraceConfig.DataSource

Defined in trace_config.proto

Fields:

Field	Type	Description
config	protos.DataSourceConfig	Filters and data-source specific config. It contains also the unique name of the data source, the one passed in the DataSourceDescriptor when they register on the service.
producer_name_filter	string[]	Optional. If multiple producers (~processes) expose the same data source and either `producer_name_filter` or `producer_name_regex_filter` is set, the data source is enabled only for producers whose names match any of the filters. `producer_name_filter` has to be an exact match, while `producer_name_regex_filter` is a regular expression. This allows to enable a data source only for specific processes. The "repeated" fields have OR semantics: specifying a filter ["foo", "bar"] will enable data sources on both "foo" and "bar" (if they exist).
producer_name_regex_filter	string[]

DataSourceConfig

The configuration that is passed to each data source when starting tracing.

Defined in data_source_config.proto

Fields:

Field	Type	Description
name	string	Data source unique name, e.g., "linux.ftrace". This must match the name passed by the data source when it registers (see RegisterDataSource()).
target_buffer	uint32	The index of the logging buffer where TracePacket(s) will be stored. This field doesn't make a major difference for the Producer(s). The final logging buffers, in fact, are completely owned by the Service. We just ask the Producer to copy this number into the chunk headers it emits, so that the Service can quickly identify the buffer where to move the chunks into without expensive lookups on its fastpath.
trace_duration_ms	uint32	Set by the service to indicate the duration of the trace. DO NOT SET in consumer as this will be overridden by the service.
stop_timeout_ms	uint32	Set by the service to indicate how long it waits after StopDataSource. DO NOT SET in consumer as this will be overridden by the service.
enable_extra_guardrails	bool	Set by the service to indicate whether this tracing session has extra guardrails. DO NOT SET in consumer as this will be overridden by the service.
tracing_session_id	uint64	Set by the service to indicate which tracing session the data source belongs to. The intended use case for this is checking if two data sources, one of which produces metadata for the other one, belong to the same trace session and hence should be linked together. This field was introduced in Aug 2018 after Android P. DO NOT SET in consumer as this will be overridden by the service.
ftrace_config	FtraceConfig	Data source name: linux.ftrace
inode_file_config	InodeFileConfig	Data source name: linux.inode_file_map
process_stats_config	ProcessStatsConfig	Data source name: linux.process_stats
sys_stats_config	SysStatsConfig	Data source name: linux.sys_stats
heapprofd_config	HeapprofdConfig	Data source name: android.heapprofd Introduced in Android 10.
java_hprof_config	JavaHprofConfig	Data source name: android.java_hprof Introduced in Android 11.
android_power_config	AndroidPowerConfig	Data source name: android.power
android_log_config	AndroidLogConfig	Data source name: android.log
gpu_counter_config	GpuCounterConfig
packages_list_config	PackagesListConfig	Data source name: android.packages_list
perf_event_config	PerfEventConfig	Data source name: linux.perf
vulkan_memory_config	VulkanMemoryConfig	Data source name: vulkan.memory_tracker
track_event_config	TrackEventConfig	Data source name: track_event
android_polled_state_config	AndroidPolledStateConfig	Data source name: android.polled_state
chrome_config	ChromeConfig	Chrome is special as it doesn't use the perfetto IPC layer. We want to avoid proto serialization and de-serialization there because that would just add extra hops on top of the Mojo ser/des. Instead we auto-generate a C++ class for it so it can pass around plain C++ objets.
interceptor_config	InterceptorConfig	If an interceptor is specified here, packets for this data source will be rerouted to the interceptor instead of the main trace buffer. This can be used, for example, to write trace data into ETW or for logging trace points to the console. Note that interceptors are only supported by data sources registered through the Perfetto SDK API. Data sources that don't use that API (e.g., traced_probes) may not support interception.
legacy_config	string	This is a fallback mechanism to send a free-form text config to the producer. In theory this should never be needed. All the code that is part of the platform (i.e. traced service) is supposed to not truncate the trace config proto and propagate unknown fields. However, if anything in the pipeline (client or backend) ends up breaking this forward compat plan, this field will become the escape hatch to allow future data sources to get some meaningful configuration.
for_testing	TestConfig	This field is only used for testing.

FtraceConfig

Defined in ftrace_config.proto

Fields:

Field	Type	Description
ftrace_events	string[]
atrace_categories	string[]
atrace_apps	string[]
buffer_size_kb	uint32	Per-CPU* buffer size.
drain_period_ms	uint32
compact_sched	CompactSchedConfig
symbolize_ksyms	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.
initialize_ksyms_synchronously_for_testing	bool	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.

FtraceConfig.CompactSchedConfig

Configuration for compact encoding of scheduler events. When enabled (and recording the relevant ftrace events), specific high-volume events are encoded in a denser format than normal.

Defined in ftrace_config.proto

Fields:

Field	Type	Description
enabled	bool	If true, and sched_switch or sched_waking ftrace events are enabled, record those events in the compact format.

InodeFileConfig

Defined in inode_file_config.proto

Fields:

Field	Type	Description
scan_interval_ms	uint32	How long to pause between batches.
scan_delay_ms	uint32	How long to wait before the first scan in order to accumulate inodes.
scan_batch_size	uint32	How many inodes to scan in one batch.
do_not_scan	bool	Do not scan for inodes not found in the static map.
scan_mount_points	string[]	If non-empty, only scan inodes corresponding to block devices named in this list.
mount_point_mapping	MountPointMappingEntry[]	When encountering an inode belonging to a block device corresponding to one of the mount points in this map, scan its scan_roots instead.

InodeFileConfig.MountPointMappingEntry

Defined in inode_file_config.proto

Fields:

Field	Type	Description
mountpoint	string
scan_roots	string[]

ProcessStatsConfig

Defined in process_stats_config.proto

Fields:

Field	Type	Description
quirks	Quirks[]
scan_all_processes_on_start	bool	If enabled all processes will be scanned and dumped when the trace starts.
record_thread_names	bool	If enabled thread names are also recoded (this is redundant if sched_switch is enabled).
proc_stats_poll_ms	uint32	If > 0 samples counters (see process_stats.proto) from /proc/pid/status and oom_score_adj every X ms. This is required to be > 100ms to avoid excessive CPU usage.
proc_stats_cache_ttl_ms	uint32	This is required to be either = 0 or a multiple of `proc_stats_poll_ms` (default: `proc_stats_poll_ms`). If = 0, will be set to `proc_stats_poll_ms`. Non-multiples will be rounded down to the nearest multiple.
record_thread_time_in_state	bool	Whether to record /proc/tid/time_in_state.
thread_time_in_state_cache_size	uint32	Size of the cache for thread time_in_state cpu freq values. If not specificed, the default is used.

ProcessStatsConfig.Quirks

Defined in process_stats_config.proto

Enum values:

Name	Value	Description
QUIRKS_UNSPECIFIED	0
DISABLE_INITIAL_DUMP	1	This has been deprecated and ignored as per 2018-05-01. Full scan at startup is now disabled by default and can be re-enabled using the `scan_all_processes_on_start` arg.
DISABLE_ON_DEMAND	2

SysStatsConfig

This file defines the configuration for the Linux /proc poller data source, which injects counters in the trace. Counters that are needed in the trace must be explicitly listed in the _counters fields. This is to avoid spamming the trace with all counters at all times. The sampling rate is configurable. All polling rates (_period_ms) need to be integer multiples of each other. OK: [10ms, 10ms, 10ms], [10ms, 20ms, 10ms], [10ms, 20ms, 60ms] Not OK: [10ms, 10ms, 11ms], [10ms, 15ms, 20ms]

Defined in sys_stats_config.proto

Fields:

Field	Type	Description
meminfo_period_ms	uint32	Polls /proc/meminfo every X ms, if non-zero. This is required to be > 10ms to avoid excessive CPU usage. Cost: 0.3 ms [read] + 0.07 ms [parse + trace injection]
meminfo_counters	MeminfoCounters[]	If empty all known counters are reported. Otherwise, only the counters specified below are reported.
vmstat_period_ms	uint32	Polls /proc/vmstat every X ms, if non-zero. This is required to be > 10ms to avoid excessive CPU usage. Cost: 0.2 ms [read] + 0.3 ms [parse + trace injection]
vmstat_counters	VmstatCounters[]
stat_period_ms	uint32	Pols /proc/stat every X ms, if non-zero. This is required to be > 10ms to avoid excessive CPU usage. Cost: 4.1 ms [read] + 1.9 ms [parse + trace injection]
stat_counters	StatCounters[]

MeminfoCounters

Counter definitions for Linux's /proc/meminfo.

Defined in sys_stats_counters.proto

Enum values:

Name	Value	Description
MEMINFO_UNSPECIFIED	0
MEMINFO_MEM_TOTAL	1
MEMINFO_MEM_FREE	2
MEMINFO_MEM_AVAILABLE	3
MEMINFO_BUFFERS	4
MEMINFO_CACHED	5
MEMINFO_SWAP_CACHED	6
MEMINFO_ACTIVE	7
MEMINFO_INACTIVE	8
MEMINFO_ACTIVE_ANON	9
MEMINFO_INACTIVE_ANON	10
MEMINFO_ACTIVE_FILE	11
MEMINFO_INACTIVE_FILE	12
MEMINFO_UNEVICTABLE	13
MEMINFO_MLOCKED	14
MEMINFO_SWAP_TOTAL	15
MEMINFO_SWAP_FREE	16
MEMINFO_DIRTY	17
MEMINFO_WRITEBACK	18
MEMINFO_ANON_PAGES	19
MEMINFO_MAPPED	20
MEMINFO_SHMEM	21
MEMINFO_SLAB	22
MEMINFO_SLAB_RECLAIMABLE	23
MEMINFO_SLAB_UNRECLAIMABLE	24
MEMINFO_KERNEL_STACK	25
MEMINFO_PAGE_TABLES	26
MEMINFO_COMMIT_LIMIT	27
MEMINFO_COMMITED_AS	28
MEMINFO_VMALLOC_TOTAL	29
MEMINFO_VMALLOC_USED	30
MEMINFO_VMALLOC_CHUNK	31
MEMINFO_CMA_TOTAL	32
MEMINFO_CMA_FREE	33

VmstatCounters

Counter definitions for Linux's /proc/vmstat.

Defined in sys_stats_counters.proto

Enum values:

Name	Value	Description
VMSTAT_UNSPECIFIED	0
VMSTAT_NR_FREE_PAGES	1
VMSTAT_NR_ALLOC_BATCH	2
VMSTAT_NR_INACTIVE_ANON	3
VMSTAT_NR_ACTIVE_ANON	4
VMSTAT_NR_INACTIVE_FILE	5
VMSTAT_NR_ACTIVE_FILE	6
VMSTAT_NR_UNEVICTABLE	7
VMSTAT_NR_MLOCK	8
VMSTAT_NR_ANON_PAGES	9
VMSTAT_NR_MAPPED	10
VMSTAT_NR_FILE_PAGES	11
VMSTAT_NR_DIRTY	12
VMSTAT_NR_WRITEBACK	13
VMSTAT_NR_SLAB_RECLAIMABLE	14
VMSTAT_NR_SLAB_UNRECLAIMABLE	15
VMSTAT_NR_PAGE_TABLE_PAGES	16
VMSTAT_NR_KERNEL_STACK	17
VMSTAT_NR_OVERHEAD	18
VMSTAT_NR_UNSTABLE	19
VMSTAT_NR_BOUNCE	20
VMSTAT_NR_VMSCAN_WRITE	21
VMSTAT_NR_VMSCAN_IMMEDIATE_RECLAIM	22
VMSTAT_NR_WRITEBACK_TEMP	23
VMSTAT_NR_ISOLATED_ANON	24
VMSTAT_NR_ISOLATED_FILE	25
VMSTAT_NR_SHMEM	26
VMSTAT_NR_DIRTIED	27
VMSTAT_NR_WRITTEN	28
VMSTAT_NR_PAGES_SCANNED	29
VMSTAT_WORKINGSET_REFAULT	30
VMSTAT_WORKINGSET_ACTIVATE	31
VMSTAT_WORKINGSET_NODERECLAIM	32
VMSTAT_NR_ANON_TRANSPARENT_HUGEPAGES	33
VMSTAT_NR_FREE_CMA	34
VMSTAT_NR_SWAPCACHE	35
VMSTAT_NR_DIRTY_THRESHOLD	36
VMSTAT_NR_DIRTY_BACKGROUND_THRESHOLD	37
VMSTAT_PGPGIN	38
VMSTAT_PGPGOUT	39
VMSTAT_PGPGOUTCLEAN	40
VMSTAT_PSWPIN	41
VMSTAT_PSWPOUT	42
VMSTAT_PGALLOC_DMA	43
VMSTAT_PGALLOC_NORMAL	44
VMSTAT_PGALLOC_MOVABLE	45
VMSTAT_PGFREE	46
VMSTAT_PGACTIVATE	47
VMSTAT_PGDEACTIVATE	48
VMSTAT_PGFAULT	49
VMSTAT_PGMAJFAULT	50
VMSTAT_PGREFILL_DMA	51
VMSTAT_PGREFILL_NORMAL	52
VMSTAT_PGREFILL_MOVABLE	53
VMSTAT_PGSTEAL_KSWAPD_DMA	54
VMSTAT_PGSTEAL_KSWAPD_NORMAL	55
VMSTAT_PGSTEAL_KSWAPD_MOVABLE	56
VMSTAT_PGSTEAL_DIRECT_DMA	57
VMSTAT_PGSTEAL_DIRECT_NORMAL	58
VMSTAT_PGSTEAL_DIRECT_MOVABLE	59
VMSTAT_PGSCAN_KSWAPD_DMA	60
VMSTAT_PGSCAN_KSWAPD_NORMAL	61
VMSTAT_PGSCAN_KSWAPD_MOVABLE	62
VMSTAT_PGSCAN_DIRECT_DMA	63
VMSTAT_PGSCAN_DIRECT_NORMAL	64
VMSTAT_PGSCAN_DIRECT_MOVABLE	65
VMSTAT_PGSCAN_DIRECT_THROTTLE	66
VMSTAT_PGINODESTEAL	67
VMSTAT_SLABS_SCANNED	68
VMSTAT_KSWAPD_INODESTEAL	69
VMSTAT_KSWAPD_LOW_WMARK_HIT_QUICKLY	70
VMSTAT_KSWAPD_HIGH_WMARK_HIT_QUICKLY	71
VMSTAT_PAGEOUTRUN	72
VMSTAT_ALLOCSTALL	73
VMSTAT_PGROTATED	74
VMSTAT_DROP_PAGECACHE	75
VMSTAT_DROP_SLAB	76
VMSTAT_PGMIGRATE_SUCCESS	77
VMSTAT_PGMIGRATE_FAIL	78
VMSTAT_COMPACT_MIGRATE_SCANNED	79
VMSTAT_COMPACT_FREE_SCANNED	80
VMSTAT_COMPACT_ISOLATED	81
VMSTAT_COMPACT_STALL	82
VMSTAT_COMPACT_FAIL	83
VMSTAT_COMPACT_SUCCESS	84
VMSTAT_COMPACT_DAEMON_WAKE	85
VMSTAT_UNEVICTABLE_PGS_CULLED	86
VMSTAT_UNEVICTABLE_PGS_SCANNED	87
VMSTAT_UNEVICTABLE_PGS_RESCUED	88
VMSTAT_UNEVICTABLE_PGS_MLOCKED	89
VMSTAT_UNEVICTABLE_PGS_MUNLOCKED	90
VMSTAT_UNEVICTABLE_PGS_CLEARED	91
VMSTAT_UNEVICTABLE_PGS_STRANDED	92
VMSTAT_NR_ZSPAGES	93
VMSTAT_NR_ION_HEAP	94
VMSTAT_NR_GPU_HEAP	95
VMSTAT_ALLOCSTALL_DMA	96
VMSTAT_ALLOCSTALL_MOVABLE	97
VMSTAT_ALLOCSTALL_NORMAL	98
VMSTAT_COMPACT_DAEMON_FREE_SCANNED	99
VMSTAT_COMPACT_DAEMON_MIGRATE_SCANNED	100
VMSTAT_NR_FASTRPC	101
VMSTAT_NR_INDIRECTLY_RECLAIMABLE	102
VMSTAT_NR_ION_HEAP_POOL	103
VMSTAT_NR_KERNEL_MISC_RECLAIMABLE	104
VMSTAT_NR_SHADOW_CALL_STACK_BYTES	105
VMSTAT_NR_SHMEM_HUGEPAGES	106
VMSTAT_NR_SHMEM_PMDMAPPED	107
VMSTAT_NR_UNRECLAIMABLE_PAGES	108
VMSTAT_NR_ZONE_ACTIVE_ANON	109
VMSTAT_NR_ZONE_ACTIVE_FILE	110
VMSTAT_NR_ZONE_INACTIVE_ANON	111
VMSTAT_NR_ZONE_INACTIVE_FILE	112
VMSTAT_NR_ZONE_UNEVICTABLE	113
VMSTAT_NR_ZONE_WRITE_PENDING	114
VMSTAT_OOM_KILL	115
VMSTAT_PGLAZYFREE	116
VMSTAT_PGLAZYFREED	117
VMSTAT_PGREFILL	118
VMSTAT_PGSCAN_DIRECT	119
VMSTAT_PGSCAN_KSWAPD	120
VMSTAT_PGSKIP_DMA	121
VMSTAT_PGSKIP_MOVABLE	122
VMSTAT_PGSKIP_NORMAL	123
VMSTAT_PGSTEAL_DIRECT	124
VMSTAT_PGSTEAL_KSWAPD	125
VMSTAT_SWAP_RA	126
VMSTAT_SWAP_RA_HIT	127
VMSTAT_WORKINGSET_RESTORE	128

SysStatsConfig.StatCounters

Defined in sys_stats_config.proto

Enum values:

Name	Value	Description
STAT_UNSPECIFIED	0
STAT_CPU_TIMES	1
STAT_IRQ_COUNTS	2
STAT_SOFTIRQ_COUNTS	3
STAT_FORK_COUNT	4

HeapprofdConfig

Configuration for go/heapprofd.

Defined in heapprofd_config.proto

Fields:

Field	Type	Description
sampling_interval_bytes	uint64	Sampling rate for all heaps not specified via heap_sampling_intervals. These are: * All heaps if heap_sampling_intervals is empty. * Those profiled due to all_heaps and not named in heaps if heap_sampling_intervals is not empty. * The implicit libc.malloc heap if heaps is empty. Set to 1 for perfect accuracy. Otherwise, sample every sample_interval_bytes on average. See https://perfetto.dev/docs/data-sources/native-heap-profiler#sampling-interval for more details. BUGS Before Android 12, setting this to 0 would crash the target process.
adaptive_sampling_shmem_threshold	uint64	If less than the given numbers of bytes are left free in the shared memory buffer, increase sampling interval by a factor of two. Adaptive sampling is disabled when set to 0.
adaptive_sampling_max_sampling_interval_bytes	uint64	Stop doubling the sampling_interval once the sampling interval has reached this value.
process_cmdline	string[]	E.g. surfaceflinger, com.android.phone This input is normalized in the following way: if it contains slashes, everything up to the last slash is discarded. If it contains "@", everything after the first @ is discared. E.g. /system/bin/surfaceflinger@1.0 normalizes to surfaceflinger. This transformation is also applied to the processes' command lines when matching.
pid	uint64[]	For watermark based triggering or local debugging.
heaps	string[]	Which heaps to sample, e.g. "libc.malloc". If left empty, only samples "malloc". Introduced in Android 12.
stream_allocations	bool
heap_sampling_intervals	uint64[]	If given, needs to be the same length as heaps and gives the sampling interval for the respective entry in heaps. Otherwise, sampling_interval_bytes is used. It is recommended to set sampling_interval_bytes to a reasonable default value when using this, as a value of 0 for sampling_interval_bytes will crash the target process before Android 12. Introduced in Android 12.
all_heaps	bool	Sample all heaps registered by target process. Introduced in Android 12.
all	bool	Profile all processes eligible for profiling on the system. See https://perfetto.dev/docs/data-sources/native-heap-profiler#heapprofd-targets for which processes are eligible. On unmodified userdebug builds, this will lead to system crashes. Zygote will crash when trying to launch a new process as it will have an unexpected open socket to heapprofd. heapprofd will likely be overloaded by the amount of data for low sampling intervals.
min_anonymous_memory_kb	uint32	Do not profile processes whose anon RSS + swap < given value. Introduced in Android 11.
max_heapprofd_memory_kb	uint32	Stop profile if heapprofd memory usage goes beyond the given value. Introduced in Android 11.
max_heapprofd_cpu_secs	uint64	Stop profile if heapprofd CPU time since start of this data-source goes beyond given value. Introduced in Android 11.
skip_symbol_prefix	string[]	Do not emit function names for mappings starting with this prefix. E.g. /system to not emit symbols for any system libraries.
continuous_dump_config	ContinuousDumpConfig	Dump at a predefined interval.
shmem_size_bytes	uint64	Size of the shared memory buffer between the profiled processes and heapprofd. Defaults to 8 MiB. If larger than 500 MiB, truncated to 500 MiB. Needs to be: * at least 8192, * a power of two, * a multiple of 4096.
block_client	bool	When the shmem buffer is full, block the client instead of ending the trace. Use with caution as this will significantly slow down the target process.
block_client_timeout_us	uint32	If set, stop the trace session after blocking the client for this timeout. Needs to be larger than 100 us, otherwise no retries are done. Introduced in Android 11.
no_startup	bool	Do not profile processes from startup, only match already running processes. Can not be set at the same time as no_running. Introduced in Android 11.
no_running	bool	Do not profile running processes. Only match processes on startup. Can not be set at the same time as no_startup. Introduced in Android 11.
dump_at_max	bool	Cause heapprofd to emit a single dump at the end, showing the memory usage at the point in time when the sampled heap usage of the process was at its maximum. This causes ProfilePacket.HeapSample.self_max to be set, and self_allocated and self_freed to not be set. Introduced in Android 11.
disable_fork_teardown	bool	Escape hatch if the session is being torn down because of a forked child that shares memory space, but is not correctly identified as a vforked child. Introduced in Android 11.
disable_vfork_detection	bool	We try to automatically detect when a target applicatation vforks but then does a memory allocation (or free). This auto-detection can be disabled with this. Introduced in Android 11.

HeapprofdConfig.ContinuousDumpConfig

Defined in heapprofd_config.proto

Fields:

Field	Type	Description
dump_phase_ms	uint32	ms to wait before first dump.
dump_interval_ms	uint32	ms to wait between following dumps.

JavaHprofConfig

Configuration for go/heapprofd.

Defined in java_hprof_config.proto

Fields:

Field	Type	Description
process_cmdline	string[]	This input is normalized in the following way: if it contains slashes, everything up to the last slash is discarded. If it contains "@", everything after the first @ is discared. E.g. /system/bin/surfaceflinger@1.0 normalizes to surfaceflinger. This transformation is also applied to the processes' command lines when matching.
pid	uint64[]	For watermark based triggering or local debugging.
continuous_dump_config	ContinuousDumpConfig	Dump at a predefined interval.
min_anonymous_memory_kb	uint32	Do not profile processes whose anon RSS + swap < given value.
dump_smaps	bool	Include the process' /proc/self/smaps. This only shows maps that: * start with /system * start with /vendor * start with /data/app * contain "extracted in memory from Y", where Y matches any of the above
ignored_types	string[]	Exclude objects of the following types from the profile. This can be useful if lots of uninteresting objects, e.g. "sun.misc.Cleaner".

JavaHprofConfig.ContinuousDumpConfig

If dump_interval_ms != 0, the following configuration is used.

Defined in java_hprof_config.proto

Fields:

Field	Type	Description
dump_phase_ms	uint32	ms to wait before first continuous dump. A dump is always created at the beginning of the trace.
dump_interval_ms	uint32	ms to wait between following dumps.

AndroidPowerConfig

Defined in android_power_config.proto

Fields:

Field	Type	Description
battery_poll_ms	uint32
battery_counters	BatteryCounters[]
collect_power_rails	bool	Where available enables per-power-rail measurements.

AndroidPowerConfig.BatteryCounters

Defined in android_power_config.proto

Enum values:

Name	Value	Description
BATTERY_COUNTER_UNSPECIFIED	0
BATTERY_COUNTER_CHARGE	1	Coulomb counter.
BATTERY_COUNTER_CAPACITY_PERCENT	2	Charge (%).
BATTERY_COUNTER_CURRENT	3	Instantaneous current.
BATTERY_COUNTER_CURRENT_AVG	4	Avg current.

AndroidLogConfig

Defined in android_log_config.proto

Fields:

Field	Type	Description
log_ids	AndroidLogId[]
min_prio	AndroidLogPriority	If set ignores all log messages whose prio is < the given value.
filter_tags	string[]	If non-empty ignores all log messages whose tag doesn't match one of the specified values.

AndroidLogId

Values from NDK's android/log.h.

Defined in android_log_constants.proto

Enum values:

Name	Value	Description
LID_DEFAULT	0	MAIN.
LID_RADIO	1
LID_EVENTS	2
LID_SYSTEM	3
LID_CRASH	4
LID_STATS	5
LID_SECURITY	6
LID_KERNEL	7

AndroidLogPriority

Defined in android_log_constants.proto

Enum values:

Name	Value	Description
PRIO_UNSPECIFIED	0
PRIO_UNUSED	1	_DEFAULT, but should never be seen in logs.
PRIO_VERBOSE	2
PRIO_DEBUG	3
PRIO_INFO	4
PRIO_WARN	5
PRIO_ERROR	6
PRIO_FATAL	7

GpuCounterConfig

Defined in gpu_counter_config.proto

Fields:

Field	Type	Description
counter_period_ns	uint64	Desired sampling interval for counters.
counter_ids	uint32[]	List of counters to be sampled. Counter IDs correspond to the ones described in GpuCounterSpec in the data source descriptor.
instrumented_sampling	bool	Sample counters by instrumenting command buffers.
fix_gpu_clock	bool	Fix gpu clock rate during trace session.

PackagesListConfig

Data source that lists details (such as version code) about packages on an Android device.

Defined in packages_list_config.proto

Fields:

Field	Type	Description
package_name_filter	string[]	If not empty, emit info about only the following list of package names (exact match, no regex). Otherwise, emit info about all packages.

PerfEventConfig

Configuration for the traced_perf profiler.

Example config for basic cpu profiling: perf_event_config { timebase { frequency: 80 } callstack_sampling { scope { target_cmdline: "surfaceflinger" target_cmdline: "system_server" } kernel_frames: true } }

Defined in perf_event_config.proto

Fields:

Field	Type	Description
timebase	Timebase	What event to sample on, and how often.
callstack_sampling	CallstackSampling	If set, the profiler will sample userspace processes' callstacks at the interval specified by the `timebase`. If unset, the profiler will record only the event counts.
ring_buffer_read_period_ms	uint32	How often the per-cpu ring buffers are read by the producer. If unset, an implementation-defined default is used.
ring_buffer_pages	uint32	Size (in 4k pages) of each per-cpu ring buffer that is filled by the kernel. If set, must be a power of two. If unset, an implementation-defined default is used.
max_daemon_memory_kb	uint32	Stop the data source if traced_perf's combined {RssAnon + Swap} memory footprint exceeds this value.
remote_descriptor_timeout_ms	uint32	Timeout for the remote /proc//{maps,mem} file descriptors for a sampled process. This is primarily for Android, where this lookup is asynchronous. As long as the producer is waiting, the associated samples will be kept enqueued (putting pressure on the capacity of the shared unwinding queue). Once a lookup for a process expires, all associated samples are discarded. However, if the lookup still succeeds after the timeout, future samples will be handled normally. If unset, an implementation-defined default is used.
unwind_state_clear_period_ms	uint32	Optional period for clearing state cached by the unwinder. This is a heavy operation that is only necessary for traces that target a wide set of processes, and require the memory footprint to be reset periodically. If unset, the cached state will not be cleared.
all_cpus	bool	Note: legacy configs had to set `all_cpus` to true to pass parsing. We might start relying on this for compatibility detection in the future.
sampling_frequency	uint32
kernel_frames	bool
target_pid	int32[]
target_cmdline	string[]
exclude_pid	int32[]
exclude_cmdline	string[]
additional_cmdline_count	uint32
tracepoint	Tracepoint

PerfEventConfig.Timebase

Defined in perf_event_config.proto

Fields:

Field	Type	Description
frequency	uint64	Per-cpu sampling frequency in Hz, as requested from the kernel. Not the same as 1/period. Details: the actual sampling will still be based on a period, but the kernel will dynamically adjust it based on the observed event rate, to approximate this frequency. Works best with steady-rate events like timers.
period	uint64	Per-cpu sampling will occur every `period` counts of `event`. Prefer `frequency` by default, as it's easier to oversample with a fixed period.
counter	Counter
tracepoint	Tracepoint

PerfEventConfig.Counter

Defined in perf_event_config.proto

Enum values:

Name	Value	Description
UNKNOWN_COUNTER	0
SW_CPU_CLOCK	1	software:
SW_PAGE_FAULTS	2
HW_CPU_CYCLES	10	hardware:
HW_INSTRUCTIONS	11

PerfEventConfig.Tracepoint

Defined in perf_event_config.proto

Fields:

Field	Type	Description
name	string	Group and name for the tracepoint, acceptable forms: * "sched/sched_switch" * "sched:sched_switch"
filter	string	Optional field-level filter for the tracepoint. Only events matching this filter will be counted (and therefore contribute to the sampling period). Example: "prev_pid >= 42 && next_pid == 0". For full syntax, see kernel documentation on "Event filtering": https://www.kernel.org/doc/Documentation/trace/events.txt

PerfEventConfig.CallstackSampling

Defined in perf_event_config.proto

Fields:

Field	Type	Description
scope	Scope	Defines a set of processes for which samples are retained/skipped. If unset, all userspace samples are kept, but beware that it will be very heavy on the stack unwinder, which might start dropping samples due to overload.
kernel_frames	bool	If true, callstacks will include the kernel-space frames. Such frames can be identified by a magical "kernel" string as their mapping name. Requires traced_perf to be running as root, or kptr_restrict to have been manually unrestricted. On Android, the platform should do the right thing on debug builds. This does not disclose KASLR, as only the function names are emitted.

PerfEventConfig.Scope

Defined in perf_event_config.proto

Fields:

Field	Type	Description
target_pid	int32[]	Process ID (TGID) allowlist. If this list is not empty, only matching samples will be retained. If multiple allow/deny-lists are specified by the config, then all of them are evaluated for each sampled process.
target_cmdline	string[]	Command line allowlist, matched against the /proc//cmdline (not the comm string), with both sides being "normalized". Normalization is as follows: (1) trim everything beyond the first null or "@" byte; (2) if the string contains forward slashes, trim everything up to and including the last one.
exclude_pid	int32[]	List of excluded pids.
exclude_cmdline	string[]	List of excluded cmdlines. Normalized in the same way as `target_cmdline`.
additional_cmdline_count	uint32	Number of additional command lines to sample. Only those which are neither explicitly included nor excluded will be considered. Processes are accepted on a first come, first served basis.

VulkanMemoryConfig

Defined in vulkan_memory_config.proto

Fields:

Field	Type	Description
track_driver_memory_usage	bool	Tracking driver memory usage events
track_device_memory_usage	bool	Tracking device memory usage events

TrackEventConfig

Defined in track_event_config.proto

Fields:

Field	Type	Description
disabled_categories	string[]	Default: []
enabled_categories	string[]	Default: []
disabled_tags	string[]	Default: [“slow”, “debug”]
enabled_tags	string[]	Default: []

AndroidPolledStateConfig

Data source that polls for display state.

Defined in android_polled_state_config.proto

Fields:

Field	Type	Description
poll_ms	uint32	Frequency of polling. If absent the state will be recorded once, at the start of the trace. This is required to be > 100ms to avoid excessive CPU usage.

ChromeConfig

Defined in chrome_config.proto

Fields:

Field	Type	Description
trace_config	string
privacy_filtering_enabled	bool	When enabled, the data source should only fill in fields in the output that are not potentially privacy sensitive.
convert_to_legacy_json	bool	Instead of emitting binary protobuf, convert the trace data to the legacy JSON format. Note that the trace data will still be returned as a series of TracePackets, but the embedded data will be JSON instead of serialized protobuf.
client_priority	ClientPriority
json_agent_label_filter	string	Applicable only when using legacy JSON format. If `json_agent_label_filter` is not empty, only data pertaining to the specified tracing agent label (e.g. "traceEvents") will be returned.

ChromeConfig.ClientPriority

Priority of the tracing session client. A higher priority session may preempt a lower priority one in configurations where concurrent sessions aren't supported.

Defined in chrome_config.proto

Enum values:

Name	Value	Description
UNKNOWN	0
BACKGROUND	1
USER_INITIATED	2

InterceptorConfig

Configuration for trace packet interception. Used for diverting trace data to non-Perfetto sources (e.g., logging to the console, ETW) when using the Perfetto SDK.

Defined in interceptor_config.proto

Fields:

Field	Type	Description
name	string	Matches the name given to RegisterInterceptor().
console_config	ConsoleConfig

ConsoleConfig

Defined in console_config.proto

Fields:

Field	Type	Description
output	Output
enable_colors	bool

ConsoleConfig.Output

Defined in console_config.proto

Enum values:

Name	Value	Description
OUTPUT_UNSPECIFIED	0
OUTPUT_STDOUT	1
OUTPUT_STDERR	2

TestConfig

The configuration for a fake producer used in tests.

Defined in test_config.proto

Fields:

Field	Type	Description
message_count	uint32	The number of messages the fake producer should send.
max_messages_per_second	uint32	The maximum number of messages which should be sent each second. The actual obserced speed may be lower if the producer is unable to work fast enough. If this is zero or unset, the producer will send as fast as possible.
seed	uint32	The seed value for a simple multiplicative congruential pseudo-random number sequence.
message_size	uint32	The size of each message in bytes. Should be greater than or equal 5 to account for the number of bytes needed to encode the random number and a null byte for the string.
send_batch_on_register	bool	Whether the producer should send a event batch when the data source is is initially registered.
dummy_fields	DummyFields

TestConfig.DummyFields

Defined in test_config.proto

Fields:

Field	Type	Description
field_uint32	uint32
field_int32	int32
field_uint64	uint64
field_int64	int64
field_fixed64	fixed64
field_sfixed64	sfixed64
field_fixed32	fixed32
field_sfixed32	sfixed32
field_double	double
field_float	float
field_sint64	sint64
field_sint32	sint32
field_string	string
field_bytes	bytes

TraceConfig.BuiltinDataSource

Config for disabling builtin data sources in the tracing service.

Defined in trace_config.proto

Fields:

Field	Type	Description
disable_clock_snapshotting	bool	Disable emitting clock timestamps into the trace.
disable_trace_config	bool	Disable echoing the original trace config in the trace.
disable_system_info	bool	Disable emitting system info (build fingerprint, cpuinfo, etc).
disable_service_events	bool	Disable emitting events for data-source state changes (e.g. the marker for all data sources having ACKed the start of the trace).
primary_trace_clock	BuiltinClock	The authoritative clock domain for the trace. Defaults to BOOTTIME. See also ClockSnapshot's primary_trace_clock. The configured value is written into the trace as part of the ClockSnapshots emitted by the service. Trace processor will attempt to translate packet/event timestamps from various data sources (and their chosen clock domains) to this domain during import. Added in Android R.
snapshot_interval_ms	uint32	Time interval in between snapshotting of sync markers, clock snapshots, stats, and other periodic service-emitted events. Note that the service only keeps track of the first and the most recent snapshot until ReadBuffers() is called.

BuiltinClock

Defined in builtin_clock.proto

Enum values:

Name	Value	Description
BUILTIN_CLOCK_UNKNOWN	0
BUILTIN_CLOCK_REALTIME	1
BUILTIN_CLOCK_REALTIME_COARSE	2
BUILTIN_CLOCK_MONOTONIC	3
BUILTIN_CLOCK_MONOTONIC_COARSE	4
BUILTIN_CLOCK_MONOTONIC_RAW	5
BUILTIN_CLOCK_BOOTTIME	6
BUILTIN_CLOCK_MAX_ID	63

TraceConfig.LockdownModeOperation

Defined in trace_config.proto

Enum values:

Name	Value	Description
LOCKDOWN_UNCHANGED	0
LOCKDOWN_CLEAR	1
LOCKDOWN_SET	2

TraceConfig.ProducerConfig

Defined in trace_config.proto

Fields:

Field	Type	Description
producer_name	string	Identifies the producer for which this config is for.
shm_size_kb	uint32	Specifies the preferred size of the shared memory buffer. If the size is larger than the max size, the max will be used. If it is smaller than the page size or doesn't fit pages evenly into it, it will fall back to the size specified by the producer or finally the default shared memory size.
page_size_kb	uint32	Specifies the preferred size of each page in the shared memory buffer. Must be an integer multiple of 4K.

TraceConfig.StatsdMetadata

Contains statsd-specific metadata about an alert associated with the trace.

Defined in trace_config.proto

Fields:

Field	Type	Description
triggering_alert_id	int64	The identifier of the alert which triggered this trace.
triggering_config_uid	int32	The uid which registered the triggering configuration with statsd.
triggering_config_id	int64	The identifier of the config which triggered the alert.
triggering_subscription_id	int64	The identifier of the subscription which triggered this trace.

TraceConfig.GuardrailOverrides

Contains flags which override the default values of the guardrails inside Perfetto. These values are only affect userdebug builds.

Defined in trace_config.proto

Fields:

Field	Type	Description
max_upload_per_day_bytes	uint64	Override the default limit (in bytes) for uploading data to server within a 24 hour period.

TraceConfig.TriggerConfig

Triggers allow producers to start or stop the tracing session when an event occurs.

For example if we are tracing probabilistically, most traces will be uninteresting. Triggers allow us to keep only the interesting ones such as those traces during which the device temperature reached a certain threshold. In this case the producer can activate a trigger to keep (STOP_TRACING) the trace, otherwise it can also begin a trace (START_TRACING) because it knows something is about to happen.

Defined in trace_config.proto

Fields:

Field	Type	Description
trigger_mode	TriggerMode
triggers	Trigger[]	A list of triggers which are related to this configuration. If ANY trigger is seen then an action will be performed based on `trigger_mode`.
trigger_timeout_ms	uint32	Required and must be positive if a TriggerConfig is specified. This is how long this TraceConfig should wait for a trigger to arrive. After this period of time if no trigger is seen the TracingSession will be cleaned up.

TraceConfig.TriggerConfig.TriggerMode

Defined in trace_config.proto

Enum values:

Name	Value	Description
UNSPECIFIED	0
START_TRACING	1	When this mode is chosen, data sources are not started until one of the `triggers` are received. This supports early initialization and fast starting of the tracing system. On triggering, the session will then record for `stop_delay_ms`. However if no trigger is seen after `trigger_timeout_ms` the session will be stopped and no data will be returned.
STOP_TRACING	2	When this mode is chosen, the session will be started via the normal EnableTracing() & StartTracing(). If no trigger is ever seen the session will be stopped after `trigger_timeout_ms` and no data will be returned. However if triggered the trace will stop after `stop_delay_ms` and any data in the buffer will be returned to the consumer.

TraceConfig.TriggerConfig.Trigger

Defined in trace_config.proto

Fields:

Field	Type	Description
name	string	The producer must specify this name to activate the trigger.
producer_name_regex	string	An std::regex that will match the producer that can activate this trigger. This is optional. If unset any producers can activate this trigger.
stop_delay_ms	uint32	After a trigger is received either in START_TRACING or STOP_TRACING mode then the trace will end `stop_delay_ms` after triggering.
max_per_24_h	uint32	Limits the number of traces this trigger can start/stop in a rolling 24 hour window. If this field is unset or zero, no limit is applied and activiation of this trigger always starts/stops the trace.
skip_probability	double	A value between 0 and 1 which encodes the probability of skipping a trigger with this name. This is useful for reducing the probability of high-frequency triggers from dominating trace finaization. If this field is unset or zero, the trigger will never be skipped. If this field is greater than or equal to 1, this trigger will always be skipped i.e. it will be as if this trigger was never included in the first place. This probability check is applied before any other limits. For example, if `max_per_24_h` is also set, first we will check if the probability bar is met and only then will we check the `max_per_24_h` limit.

TraceConfig.IncrementalStateConfig

Configuration for trace contents that reference earlier trace data. For example, a data source might intern strings, and emit packets containing {interned id : string} pairs. Future packets from that data source can then use the interned ids instead of duplicating the raw string contents. The trace parser will then need to use that interning table to fully interpret the rest of the trace.

Defined in trace_config.proto

Fields:

Field	Type	Description
clear_period_ms	uint32	If nonzero, notify eligible data sources to clear their incremental state periodically, with the given period. The notification is sent only to data sources that have `handles_incremental_state_clear` set in their DataSourceDescriptor. The notification requests that the data source stops referring to past trace contents. This is particularly useful when tracing in ring buffer mode, where it is not exceptional to overwrite old trace data. Warning: this time-based global clearing is likely to be removed in the future, to be replaced with a smarter way of sending the notifications only when necessary.

TraceConfig.CompressionType

Compress trace with the given method. Best effort.

Defined in trace_config.proto

Enum values:

Name	Value	Description
COMPRESSION_TYPE_UNSPECIFIED	0
COMPRESSION_TYPE_DEFLATE	1

TraceConfig.IncidentReportConfig

Android-only. Not for general use. If set, saves a Dropbox trace into an incident. This field is read by perfetto_cmd, rather than the tracing service. All fields are mandatory.

Defined in trace_config.proto

Fields:

Field	Type	Description
destination_package	string
destination_class	string
privacy_level	int32	Level of filtering in the requested incident. See `Destination` in frameworks/base/core/proto/android/privacy.proto.
skip_dropbox	bool	If true, do not write the trace into dropbox (i.e. incident only). Otherwise, write to both dropbox and incident.