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