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  //
98  // Deprecated (superseded by options above):
99  //
100  // Do not set *any* of these fields in new configs.
101  //
102
103  // Note: legacy configs had to set |all_cpus| to true to pass parsing.
104  // We rely on this to detect such configs.
105  optional bool all_cpus = 1;
106  optional uint32 sampling_frequency = 2;
107  optional bool kernel_frames = 12;
108  repeated int32 target_pid = 4;
109  repeated string target_cmdline = 5;
110
111  // Only profile target if it was installed by one of the packages given.
112  // Special values are:
113  // * @system: installed on the system partition
114  // * @product: installed on the product partition
115  // * @null: sideloaded
116  // Supported on Android 12+.
117  repeated string target_installed_by = 18;
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
152    // /proc/<pid>/cmdline (not the comm string), with both sides being
153    // "normalized". Normalization is as follows: (1) trim everything beyond the
154    // first null or "@" byte; (2) if the string contains forward slashes, trim
155    // everything up to and including the last one.
156    repeated string target_cmdline = 2;
157
158    // List of excluded pids.
159    repeated int32 exclude_pid = 3;
160
161    // List of excluded cmdlines. Normalized in the same way as
162    // |target_cmdline|.
163    repeated string exclude_cmdline = 4;
164
165    // Number of additional command lines to sample. Only those which are
166    // neither explicitly included nor excluded will be considered. Processes
167    // are accepted on a first come, first served basis.
168    optional uint32 additional_cmdline_count = 5;
169  }
170}
171