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
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 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
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.
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_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.
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 TODO(fmayer): Add data source name for this.
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.
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.

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
TODO(primiano): add CPU cost for change this value.
proc_stats_cache_ttl_ms uint32 This is required to be either = 0 or a multiple of
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
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.
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.

At the time of writing, the config options are restricted to the periodic system-wide stack sampling use-case (|all_cpus| must be true).

Defined in perf_event_config.proto

Fields:

Field Type Description
all_cpus bool If true, sample events on all CPUs.
sampling_frequency uint32 Per-cpu sampling frequency (requested from the kernel). Not guaranteed to be honored as the kernel can throttle the sampling rate if it's too high
If unset, an implementation-defined default is used.
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.
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
This does not disclose KASLR, as only the function names are emitted.
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
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.
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.

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

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

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_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
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

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 The a 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

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

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. Debug builds 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
skip_dropbox bool If true, do not write the trace into dropbox (i.e. incident only)
Otherwise, write to both dropbox and incident.