1/* 2 * Copyright (C) 2019 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17syntax = "proto2"; 18 19import "protos/perfetto/common/perf_events.proto"; 20 21package perfetto.protos; 22 23// Configuration for the traced_perf profiler. 24// 25// Example config for basic cpu profiling: 26// perf_event_config { 27// timebase { 28// frequency: 80 29// } 30// callstack_sampling { 31// scope { 32// target_cmdline: "surfaceflinger" 33// target_cmdline: "system_server" 34// } 35// kernel_frames: true 36// } 37// } 38// 39// Next id: 19 40message PerfEventConfig { 41 // What event to sample on, and how often. 42 // Defined in common/perf_events.proto. 43 optional PerfEvents.Timebase timebase = 15; 44 45 // If set, the profiler will sample userspace processes' callstacks at the 46 // interval specified by the |timebase|. 47 // If unset, the profiler will record only the event counts. 48 optional CallstackSampling callstack_sampling = 16; 49 50 // 51 // Kernel <-> userspace ring buffer options: 52 // 53 54 // How often the per-cpu ring buffers are read by the producer. 55 // If unset, an implementation-defined default is used. 56 optional uint32 ring_buffer_read_period_ms = 8; 57 58 // Size (in 4k pages) of each per-cpu ring buffer that is filled by the 59 // kernel. If set, must be a power of two. 60 // If unset, an implementation-defined default is used. 61 optional uint32 ring_buffer_pages = 3; 62 63 // 64 // Daemon's resource usage limits: 65 // 66 67 // Drop samples if the heap memory held by the samples in the unwinder queue 68 // is above the given limit. This counts the memory across all concurrent data 69 // sources (not just this one's), and there is no fairness guarantee - the 70 // whole quota might be used up by a concurrent source. 71 optional uint64 max_enqueued_footprint_kb = 17; 72 73 // Stop the data source if traced_perf's combined {RssAnon + Swap} memory 74 // footprint exceeds this value. 75 optional uint32 max_daemon_memory_kb = 13; 76 77 // 78 // Uncommon options: 79 // 80 81 // Timeout for the remote /proc/<pid>/{maps,mem} file descriptors for a 82 // sampled process. This is primarily for Android, where this lookup is 83 // asynchronous. As long as the producer is waiting, the associated samples 84 // will be kept enqueued (putting pressure on the capacity of the shared 85 // unwinding queue). Once a lookup for a process expires, all associated 86 // samples are discarded. However, if the lookup still succeeds after the 87 // timeout, future samples will be handled normally. 88 // If unset, an implementation-defined default is used. 89 optional uint32 remote_descriptor_timeout_ms = 9; 90 91 // Optional period for clearing state cached by the unwinder. This is a heavy 92 // operation that is only necessary for traces that target a wide set of 93 // processes, and require the memory footprint to be reset periodically. 94 // If unset, the cached state will not be cleared. 95 optional uint32 unwind_state_clear_period_ms = 10; 96 97 // If set, only profile target if it was installed by a package with one of 98 // these names. Special values: 99 // * "@system": installed on the system partition 100 // * "@product": installed on the product partition 101 // * "@null": sideloaded 102 // Supported on Android 12+. 103 repeated string target_installed_by = 18; 104 105 // 106 // Deprecated (superseded by options above): 107 // 108 // Do not set *any* of these fields in new configs. 109 // 110 111 // Note: legacy configs had to set |all_cpus| to true to pass parsing. 112 // We rely on this to detect such configs. 113 optional bool all_cpus = 1; 114 optional uint32 sampling_frequency = 2; 115 optional bool kernel_frames = 12; 116 repeated int32 target_pid = 4; 117 repeated string target_cmdline = 5; 118 repeated int32 exclude_pid = 6; 119 repeated string exclude_cmdline = 7; 120 optional uint32 additional_cmdline_count = 11; 121 // previously |tracepoint| 122 reserved 14; 123 124 // 125 // Sub-messages (nested for generated code namespacing). 126 // 127 128 message CallstackSampling { 129 // Defines a set of processes for which samples are retained/skipped. If 130 // unset, all userspace samples are kept, but beware that it will be very 131 // heavy on the stack unwinder, which might start dropping samples due to 132 // overload. 133 optional Scope scope = 1; 134 135 // If true, callstacks will include the kernel-space frames. Such frames can 136 // be identified by a magical "kernel" string as their mapping name. 137 // Requires traced_perf to be running as root, or kptr_restrict to have been 138 // manually unrestricted. On Android, the platform should do the right thing 139 // on debug builds. 140 // This does *not* disclose KASLR, as only the function names are emitted. 141 optional bool kernel_frames = 2; 142 } 143 144 message Scope { 145 // Process ID (TGID) allowlist. If this list is not empty, only matching 146 // samples will be retained. If multiple allow/deny-lists are 147 // specified by the config, then all of them are evaluated for each sampled 148 // process. 149 repeated int32 target_pid = 1; 150 151 // Command line allowlist, matched against the /proc/<pid>/cmdline (not the 152 // comm string). The semantics of this field were changed since its original 153 // introduction. 154 // 155 // On Android T+ (13+), this field can specify a single wildcard (*), and 156 // the profiler will attempt to match it in two possible ways: 157 // * if the pattern starts with a '/', then it is matched against the first 158 // segment of the cmdline (i.e. argv0). For example "/bin/e*" would match 159 // "/bin/echo". 160 // * otherwise the pattern is matched against the part of argv0 161 // corresponding to the binary name (this is unrelated to /proc/pid/exe). 162 // For example "echo" would match "/bin/echo". 163 // 164 // On Android S (12) and below, both this pattern and /proc/pid/cmdline get 165 // normalized prior to an exact string comparison. Normalization is as 166 // follows: (1) trim everything beyond the first null or "@" byte; (2) if 167 // the string contains forward slashes, trim everything up to and including 168 // the last one. 169 // 170 // Implementation note: in either case, at most 511 characters of cmdline 171 // are considered. 172 repeated string target_cmdline = 2; 173 174 // List of excluded pids. 175 repeated int32 exclude_pid = 3; 176 177 // List of excluded cmdlines. See description of |target_cmdline| for how 178 // this is handled. 179 repeated string exclude_cmdline = 4; 180 181 // Number of additional command lines to sample. Only those which are 182 // neither explicitly included nor excluded will be considered. Processes 183 // are accepted on a first come, first served basis. 184 optional uint32 additional_cmdline_count = 5; 185 } 186} 187