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 |
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 | 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. |
| 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. "malloc". If left empty, only samples "malloc". 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. |
| idle_allocations | bool | Gather information on how many bytes of allocations are on non-referenced pages. The way to use this generally is: 1. Start profile of app 2. Start app 3. Trigger a dump by sending SIGUSR1 to heapprofd 4. Do operations 5. End profile You can then find the allocations that were not used for the operations you did in step 4. |
| 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 |
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. |
| 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/ |
| 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/ 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. |