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 | |
| statsd_logging | StatsdLogging | Android-only. Not for general use. If specified, sets the logging to statsd of guardrails and checkpoints in the tracing service. perfetto_cmd sets this to enabled (if not explicitly set in the config) when specifying --upload. |
| 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 | |
| trace_filter | TraceFilter | |
| android_report_config | AndroidReportConfig | |
| cmd_trace_start_delay | CmdTraceStartDelay |
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. |
| session_initiator | SessionInitiator | Set by the service to indicate which user initiated this trace. 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. |
DataSourceConfig.SessionInitiator
Defined in data_source_config.proto
Enum values:
| Name | Value | Description |
|---|---|---|
| SESSION_INITIATOR_UNSPECIFIED | 0 | |
| SESSION_INITIATOR_TRUSTED_SYSTEM | 1 | This trace was initiated from a trusted system app has DUMP and USAGE_STATS permission. This system app is expected to not expose the trace to the user of the device. This is determined by checking the UID initiating the trace. |
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. |
| throttle_rss_stat | bool | When this boolean is true AND the ftrace_events contains "kmem/rss_stat", this option causes traced_probes to enable the "kmem/rss_stat_throttled" event instad if present, and fall back to "kmem/rss_stat" if not present. The historical context for this is the following: - Up to Android S (12), the rss_stat was internally throttled in its kernel implementation. - A change introduced in the kernels after S has introduced a new "rss_stat_throttled" making the original "rss_stat" event unthrottled (hence very spammy). - Not all Android T/13 devices will receive a new kernel though, hence we need to deal with both cases. For more context: go/rss-stat-throttled. does nothing. |
| disable_generic_events | bool | If true, avoid enabling events that aren't statically known by traced_probes. Otherwise, the default is to emit such events as GenericFtraceEvent protos. Prefer to keep this flag at its default. This was added for Android tracing, where atrace categories and/or atrace HAL requested events can expand to events that aren't of interest to the tracing user. Introduced in: Android T. |
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. |
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[] | |
| devfreq_period_ms | uint32 | Polls /sys/devfreq/*/curfreq every X ms, if non-zero. This is required to be > 10ms to avoid excessive CPU usage. This option can be used to record unchanging values. Updates from frequency changes can come from ftrace/set_clock_rate. |
| cpufreq_period_ms | uint32 | Polls /sys/devices/system/cpu/cpu*/cpufreq/cpuinfo_cur_freq every X ms. This is required to be > 10ms to avoid excessive CPU usage. |
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. N.B. This must be explicitly set to a non-zero value for all heaps (with this field or with heap_sampling_intervals), otherwise the producer will not start. |
| 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. |
| target_installed_by | string[] | Only profile target if it was installed by one of the packages given. Special values are: * @system: installed on the system partition * @product: installed on the product partition * @null: sideloaded Supported on Android 12+. |
| heaps | string[] | Which heaps to sample, e.g. "libc.malloc". If left empty, only samples "malloc". Introduced in Android 12. |
| exclude_heaps | string[] | Which heaps not to sample, e.g. "libc.malloc". This is useful when used in combination with all_heaps; 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 values must be non-zero or the producer will not start. |
| 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 managed app heap graph snapshots.
Defined in java_hprof_config.proto
Fields:
| Field | Type | Description |
|---|---|---|
| process_cmdline | string[] | Command line allowlist, matched against the /proc/ On Android T+ (13+), this field can specify a single wildcard (), and the profiler will attempt to match it in two possible ways: if the pattern starts with a '/', then it is matched against the first segment of the cmdline (i.e. argv0). For example "/bin/e*" would match "/bin/echo". * otherwise the pattern is matched against the part of argv0 corresponding to the binary name (this is unrelated to /proc/pid/exe). For example "echo" would match "/bin/echo". On Android S (12) and below, both this pattern and /proc/pid/cmdline get normalized prior to an exact string comparison. 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. Implementation note: in either case, at most 511 characters of cmdline are considered. |
| pid | uint64[] | For watermark based triggering or local debugging. |
| target_installed_by | string[] | Only profile target if it was installed by one of the packages given. Special values are: * @system: installed on the system partition * @product: installed on the product partition * @null: sideloaded Supported on Android 12+. |
| 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. |
| scan_pids_only_on_start | bool | If true, scans all the processes to find process_cmdline and filter by min_anonymous_memory_kb only at data source start. Default on Android S-.If false, rescans all the processes to find on every dump. Default on Android T+. |
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. |
| collect_energy_estimation_breakdown | bool | Provides a breakdown of energy estimation for various subsystem (e.g. GPU). Available from Android S. |
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 | PerfEvents.Timebase | What event to sample on, and how often. Defined in common/perf_events.proto. |
| 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_enqueued_footprint_kb | uint64 | Drop samples if the heap memory held by the samples in the unwinder queue is above the given limit. This counts the memory across all concurrent data sources (not just this one's), and there is no fairness guarantee - the whole quota might be used up by a concurrent source. |
| 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/ 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. |
| target_installed_by | string[] | If set, only profile target if it was installed by a package with one of these names. Special values: * "@system": installed on the system partition * "@product": installed on the product partition * "@null": sideloaded Supported on Android 12+. |
| all_cpus | bool | Note: legacy configs had to set all_cpus to true to pass parsing.We rely on this to detect such configs. |
| sampling_frequency | uint32 | |
| kernel_frames | bool | |
| target_pid | int32[] | |
| target_cmdline | string[] | |
| exclude_pid | int32[] | |
| exclude_cmdline | string[] | |
| additional_cmdline_count | uint32 |
PerfEvents.Timebase
What event to sample on, and how often. Commented from the perspective of
its use in PerfEventConfig.
Defined in perf_events.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 | |
| raw_event | RawEvent | |
| timestamp_clock | PerfClock | If set, samples will be timestamped with the given clock. If unset, the clock is chosen by the implementation. For software events, prefer PERF_CLOCK_BOOTTIME. However it cannot be used for hardware events (due to interrupt safety), for which the recommendation is to use one of the monotonic clocks. |
| name | string | Optional arbitrary name for the event, to identify it in the parsed trace. Does not affect the profiling itself. If unset, the trace parser will choose a suitable name. |
PerfEvents.Counter
Builtin counter names from the uapi header. Commented with their perf tool aliases. finite), and generally make this list as extensive as possible. Excluding things like dynamic PMUs since those don't fit into a static enum.
Defined in perf_events.proto
Enum values:
| Name | Value | Description |
|---|---|---|
| UNKNOWN_COUNTER | 0 | |
| SW_CPU_CLOCK | 1 | cpu-clock |
| SW_PAGE_FAULTS | 2 | page-faults, faults |
| SW_TASK_CLOCK | 3 | task-clock |
| SW_CONTEXT_SWITCHES | 4 | context-switches, cs |
| SW_CPU_MIGRATIONS | 5 | cpu-migrations, migrations |
| SW_PAGE_FAULTS_MIN | 6 | minor-faults |
| SW_PAGE_FAULTS_MAJ | 7 | major-faults |
| SW_ALIGNMENT_FAULTS | 8 | alignment-faults |
| SW_EMULATION_FAULTS | 9 | emulation-faults |
| SW_DUMMY | 20 | dummy |
| HW_CPU_CYCLES | 10 | cpu-cycles, cycles |
| HW_INSTRUCTIONS | 11 | instructions |
| HW_CACHE_REFERENCES | 12 | cache-references |
| HW_CACHE_MISSES | 13 | cache-misses |
| HW_BRANCH_INSTRUCTIONS | 14 | branch-instructions, branches |
| HW_BRANCH_MISSES | 15 | branch-misses |
| HW_BUS_CYCLES | 16 | bus-cycles |
| HW_STALLED_CYCLES_FRONTEND | 17 | stalled-cycles-frontend, idle-cycles-frontend |
| HW_STALLED_CYCLES_BACKEND | 18 | stalled-cycles-backend, idle-cycles-backend |
| HW_REF_CPU_CYCLES | 19 | ref-cycles |
PerfEvents.Tracepoint
Defined in perf_events.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 |
PerfEvents.RawEvent
Syscall-level description of the event, propagated to the perf_event_attr struct. Primarily for local use-cases, since the event availability and encoding is hardware-specific.
Defined in perf_events.proto
Fields:
| Field | Type | Description |
|---|---|---|
| type | uint32 | |
| config | uint64 | |
| config1 | uint64 | |
| config2 | uint64 |
PerfEvents.PerfClock
Subset of clocks that is supported by perf timestamping. CLOCK_TAI is excluded since it's not expected to be used in practice, but would require additions to the trace clock synchronisation logic.
Defined in perf_events.proto
Enum values:
| Name | Value | Description |
|---|---|---|
| UNKNOWN_PERF_CLOCK | 0 | |
| PERF_CLOCK_REALTIME | 1 | |
| PERF_CLOCK_MONOTONIC | 2 | |
| PERF_CLOCK_MONOTONIC_RAW | 3 | |
| PERF_CLOCK_BOOTTIME | 4 |
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/ On Android T+ (13+), this field can specify a single wildcard (), and the profiler will attempt to match it in two possible ways: if the pattern starts with a '/', then it is matched against the first segment of the cmdline (i.e. argv0). For example "/bin/e*" would match "/bin/echo". * otherwise the pattern is matched against the part of argv0 corresponding to the binary name (this is unrelated to /proc/pid/exe). For example "echo" would match "/bin/echo". On Android S (12) and below, both this pattern and /proc/pid/cmdline get normalized prior to an exact string comparison. 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. Implementation note: in either case, at most 511 characters of cmdline are considered. |
| exclude_pid | int32[] | List of excluded pids. |
| exclude_cmdline | string[] | List of excluded cmdlines. See description of target_cmdline for how this is handled. |
| 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: [] |
| disable_incremental_timestamps | bool | Default: false (i.e. enabled by default) |
| timestamp_unit_multiplier | uint64 | Allows to specify a custom unit different than the default (ns). Also affects thread timestamps if enable_thread_time_sampling = true. A multiplier of 1000 means that a timestamp = 3 should be interpreted as 3000 ns = 3 us. Default: 1 (if unset, it should be read as 1). |
| filter_debug_annotations | bool | Default: false (i.e. debug_annotations is NOT filtered out by default) When true, any debug annotations provided as arguments to the TRACE_EVENT macros are not written into the trace. Typed arguments will still be emitted even if set to true. |
| enable_thread_time_sampling | bool | Default : false (i.e. disabled) When true, the SDK samples and emits the current thread time counter value for each event on the current thread's track. This value represents the total CPU time consumed by that thread since its creation. Note that if a thread is not scheduled by OS for some duration, that time won't be included in thread_time. Learn more : "CLOCK_THREAD_CPUTIME_ID" flag at https://linux.die.net/man/3/clock_gettime |
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. |
| prefer_suspend_clock_for_snapshot | bool | Hints to the service that a suspend-aware (i.e. counting time in suspend) clock should be used for periodic snapshots of service-emitted events. This means, if a snapshot should have happened during suspend, it will happen immediately after the device resumes. Choosing a clock like this is done on best-effort basis; not all platforms (e.g. Windows) expose a clock which can be used for periodic tasks counting suspend. If such a clock is not available, the service falls back to the best-available alternative. Introduced in Android S. crashes in S. |
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.
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. On R-, this override only affected userdebug builds. Since S, it also affects user builds. |
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 the trace into an incident. This field is read by perfetto_cmd, rather than the tracing service. This field must be set when passing the --upload flag to perfetto_cmd.
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_incidentd | bool | If true, then skips saving the trace to incidentd. This flag is useful in testing (e.g. Perfetto-statsd integration tests) or when we explicitly don't want traces to go to incidentd even when they usually would (e.g. configs deployed using statsd but only used for inclusion in bugreports using bugreport_score).The motivation for having this flag, instead of just not setting incident_report_config, is prevent accidents where incident_report_config is omitted by mistake. |
| skip_dropbox | bool | If true, do not write the trace into dropbox (i.e. incident only). Otherwise, write to both dropbox and incident. |
TraceConfig.StatsdLogging
Defined in trace_config.proto
Enum values:
| Name | Value | Description |
|---|---|---|
| STATSD_LOGGING_UNSPECIFIED | 0 | |
| STATSD_LOGGING_ENABLED | 1 | |
| STATSD_LOGGING_DISABLED | 2 |
TraceConfig.TraceFilter
When set applies a post-filter to the trace contents using the filter
provided. The filter is applied at ReadBuffers() time and works both in the
case of IPC readback and write_into_file. This filter can be generated
using tools/proto_filter -s schema.proto -F filter_out.bytes or
-T filter_out.escaped_string (for .pbtx). See go/trace-filtering for
design.
Introduced in Android S, but it was broken (b/195065199). Reintroduced in Android T with a different field number.
Defined in trace_config.proto
Fields:
| Field | Type | Description |
|---|---|---|
| bytecode | bytes |
TraceConfig.AndroidReportConfig
Android-only. Not for general use. If set, reports the trace to the Android framework. This field is read by perfetto_cmd, rather than the tracing service. This field must be set when passing the --upload flag to perfetto_cmd.
Defined in trace_config.proto
Fields:
| Field | Type | Description |
|---|---|---|
| reporter_service_package | string | |
| reporter_service_class | string | |
| skip_report | bool | If true, then skips reporting the trace to Android framework. This flag is useful in testing (e.g. Perfetto-statsd integration tests) or when we explicitly don't want to report traces to the framework even when they usually would (e.g. configs deployed using statsd but only used for inclusion in bugreports using bugreport_score).The motivation for having this flag, instead of just not setting framework_report_config, is prevent accidents where framework_report_config is omitted by mistake. |
| use_pipe_in_framework_for_testing | bool | If true, will direct the Android framework to read the data in trace file and pass it to the reporter class over a pipe instead of passing the file descriptor directly. This flag is needed because the Android test framework does not currently support priv-app helper apps (in terms of SELinux) and we really don't want to add an allow rule for untrusted_app to receive trace fds. Because of this, we instead will direct the framework to create a new pipe and pass this to the reporter process instead. As the pipe is created by the framework, we won't have any problems with SELinux (system_server is already allowed to pass pipe fds, even to untrusted apps). As the name suggests this option MUST only be used for testing. Note that the framework will reject (and drop) files which are too large both for simplicity and to be minimize the amount of data we pass to a non-priv app (note that the framework will still check manifest permissions even though SELinux permissions are worked around). |
TraceConfig.CmdTraceStartDelay
If set, delays the start of tracing by a random duration. The duration is chosen from a uniform distribution between the specified minimum and maximum. Note: this delay is implemented by perfetto_cmd not by traced so will not work if you communicate with traced directly over the consumer API. Introduced in Android T.
Defined in trace_config.proto
Fields:
| Field | Type | Description |
|---|---|---|
| min_delay_ms | uint32 | |
| max_delay_ms | uint32 |