1 // Copyright (C) 2018 The Android Open Source Project 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 // Profile is a common stacktrace profile format. 16 // 17 // Measurements represented with this format should follow the 18 // following conventions: 19 // 20 // - Consumers should treat unset optional fields as if they had been 21 // set with their default value. 22 // 23 // - When possible, measurements should be stored in "unsampled" form 24 // that is most useful to humans. There should be enough 25 // information present to determine the original sampled values. 26 // 27 // - On-disk, the serialized proto must be gzip-compressed. 28 // 29 // - The profile is represented as a set of samples, where each sample 30 // references a sequence of locations, and where each location belongs 31 // to a mapping. 32 // - There is a N->1 relationship from sample.location_id entries to 33 // locations. For every sample.location_id entry there must be a 34 // unique Location with that id. 35 // - There is an optional N->1 relationship from locations to 36 // mappings. For every nonzero Location.mapping_id there must be a 37 // unique Mapping with that id. 38 39 syntax = "proto3"; 40 41 package perftools.profiles; 42 43 option java_package = "com.google.perftools.profiles"; 44 option java_outer_classname = "ProfileProto"; 45 46 // Perfetto Changes =========================================================== 47 // 1. Add optimize_for = LITE_RUNTIME 48 option optimize_for = LITE_RUNTIME; 49 // ============================================================================ 50 51 message Profile { 52 // A description of the samples associated with each Sample.value. 53 // For a cpu profile this might be: 54 // [["cpu","nanoseconds"]] or [["wall","seconds"]] or [["syscall","count"]] 55 // For a heap profile, this might be: 56 // [["allocations","count"], ["space","bytes"]], 57 // If one of the values represents the number of events represented 58 // by the sample, by convention it should be at index 0 and use 59 // sample_type.unit == "count". 60 repeated ValueType sample_type = 1; 61 // The set of samples recorded in this profile. 62 repeated Sample sample = 2; 63 // Mapping from address ranges to the image/binary/library mapped 64 // into that address range. mapping[0] will be the main binary. 65 repeated Mapping mapping = 3; 66 // Useful program location 67 repeated Location location = 4; 68 // Functions referenced by locations 69 repeated Function function = 5; 70 // A common table for strings referenced by various messages. 71 // string_table[0] must always be "". 72 repeated string string_table = 6; 73 // frames with Function.function_name fully matching the following 74 // regexp will be dropped from the samples, along with their successors. 75 int64 drop_frames = 7; // Index into string table. 76 // frames with Function.function_name fully matching the following 77 // regexp will be kept, even if it matches drop_functions. 78 int64 keep_frames = 8; // Index into string table. 79 80 // The following fields are informational, do not affect 81 // interpretation of results. 82 83 // Time of collection (UTC) represented as nanoseconds past the epoch. 84 int64 time_nanos = 9; 85 // Duration of the profile, if a duration makes sense. 86 int64 duration_nanos = 10; 87 // The kind of events between sampled ocurrences. 88 // e.g [ "cpu","cycles" ] or [ "heap","bytes" ] 89 ValueType period_type = 11; 90 // The number of events between sampled occurrences. 91 int64 period = 12; 92 // Freeform text associated to the profile. 93 repeated int64 comment = 13; // Indices into string table. 94 // Index into the string table of the type of the preferred sample 95 // value. If unset, clients should default to the last sample value. 96 int64 default_sample_type = 14; 97 } 98 99 // ValueType describes the semantics and measurement units of a value. 100 message ValueType { 101 int64 type = 1; // Index into string table. 102 int64 unit = 2; // Index into string table. 103 } 104 105 // Each Sample records values encountered in some program 106 // context. The program context is typically a stack trace, perhaps 107 // augmented with auxiliary information like the thread-id, some 108 // indicator of a higher level request being handled etc. 109 message Sample { 110 // The ids recorded here correspond to a Profile.location.id. 111 // The leaf is at location_id[0]. 112 repeated uint64 location_id = 1; 113 // The type and unit of each value is defined by the corresponding 114 // entry in Profile.sample_type. All samples must have the same 115 // number of values, the same as the length of Profile.sample_type. 116 // When aggregating multiple samples into a single sample, the 117 // result has a list of values that is the elemntwise sum of the 118 // lists of the originals. 119 repeated int64 value = 2; 120 // label includes additional context for this sample. It can include 121 // things like a thread id, allocation size, etc 122 repeated Label label = 3; 123 } 124 125 message Label { 126 int64 key = 1; // Index into string table 127 128 // At most one of the following must be present 129 int64 str = 2; // Index into string table 130 int64 num = 3; 131 132 // Should only be present when num is present. 133 // Specifies the units of num. 134 // Use arbitrary string (for example, "requests") as a custom count unit. 135 // If no unit is specified, consumer may apply heuristic to deduce the unit. 136 // Consumers may also interpret units like "bytes" and "kilobytes" as memory 137 // units and units like "seconds" and "nanoseconds" as time units, 138 // and apply appropriate unit conversions to these. 139 int64 num_unit = 4; // Index into string table 140 } 141 142 message Mapping { 143 // Unique nonzero id for the mapping. 144 uint64 id = 1; 145 // Address at which the binary (or DLL) is loaded into memory. 146 uint64 memory_start = 2; 147 // The limit of the address range occupied by this mapping. 148 uint64 memory_limit = 3; 149 // Offset in the binary that corresponds to the first mapped address. 150 uint64 file_offset = 4; 151 // The object this entry is loaded from. This can be a filename on 152 // disk for the main binary and shared libraries, or virtual 153 // abstractions like "[vdso]". 154 int64 filename = 5; // Index into string table 155 // A string that uniquely identifies a particular program version 156 // with high probability. E.g., for binaries generated by GNU tools, 157 // it could be the contents of the .note.gnu.build-id field. 158 int64 build_id = 6; // Index into string table 159 160 // The following fields indicate the resolution of symbolic info. 161 bool has_functions = 7; 162 bool has_filenames = 8; 163 bool has_line_numbers = 9; 164 bool has_inline_frames = 10; 165 } 166 167 // Describes function and line table debug information. 168 message Location { 169 // Unique nonzero id for the location. A profile could use 170 // instruction addresses or any integer sequence as ids. 171 uint64 id = 1; 172 // The id of the corresponding profile.Mapping for this location. 173 // It can be unset if the mapping is unknown or not applicable for 174 // this profile type. 175 uint64 mapping_id = 2; 176 // The instruction address for this location, if available. It 177 // should be within [Mapping.memory_start...Mapping.memory_limit] 178 // for the corresponding mapping. A non-leaf address may be in the 179 // middle of a call instruction. It is up to display tools to find 180 // the beginning of the instruction if necessary. 181 uint64 address = 3; 182 // Multiple line indicates this location has inlined functions, 183 // where the last entry represents the caller into which the 184 // preceding entries were inlined. 185 // 186 // E.g., if memcpy() is inlined into printf: 187 // line[0].function_name == "memcpy" 188 // line[1].function_name == "printf" 189 repeated Line line = 4; 190 // Provides an indication that multiple symbols map to this location's 191 // address, for example due to identical code folding by the linker. In that 192 // case the line information above represents one of the multiple 193 // symbols. This field must be recomputed when the symbolization state of the 194 // profile changes. 195 bool is_folded = 5; 196 } 197 198 message Line { 199 // The id of the corresponding profile.Function for this line. 200 uint64 function_id = 1; 201 // Line number in source code. 202 int64 line = 2; 203 } 204 205 message Function { 206 // Unique nonzero id for the function. 207 uint64 id = 1; 208 // Name of the function, in human-readable form if available. 209 int64 name = 2; // Index into string table 210 // Name of the function, as identified by the system. 211 // For instance, it can be a C++ mangled name. 212 int64 system_name = 3; // Index into string table 213 // Source file containing the function. 214 int64 filename = 4; // Index into string table 215 // Line number in source file. 216 int64 start_line = 5; 217 } 218
