1// Copyright 2016 Google Inc. All Rights Reserved.
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
39syntax = "proto3";
40
41package perftools.profiles;
42
43option java_package = "com.google.perftools.profiles";
44option java_outer_classname = "ProfileProto";
45
46message Profile {
47 // A description of the samples associated with each Sample.value.
48 // For a cpu profile this might be:
49 // [["cpu","nanoseconds"]] or [["wall","seconds"]] or [["syscall","count"]]
50 // For a heap profile, this might be:
51 // [["allocations","count"], ["space","bytes"]],
52 // If one of the values represents the number of events represented
53 // by the sample, by convention it should be at index 0 and use
54 // sample_type.unit == "count".
55 repeated ValueType sample_type = 1;
56 // The set of samples recorded in this profile.
57 repeated Sample sample = 2;
58 // Mapping from address ranges to the image/binary/library mapped
59 // into that address range. mapping[0] will be the main binary.
60 repeated Mapping mapping = 3;
61 // Locations referenced by samples.
62 repeated Location location = 4;
63 // Functions referenced by locations.
64 repeated Function function = 5;
65 // A common table for strings referenced by various messages.
66 // string_table[0] must always be "".
67 repeated string string_table = 6;
68 // frames with Function.function_name fully matching the following
69 // regexp will be dropped from the samples, along with their successors.
70 int64 drop_frames = 7; // Index into string table.
71 // frames with Function.function_name fully matching the following
72 // regexp will be kept, even if it matches drop_frames.
73 int64 keep_frames = 8; // Index into string table.
74
75 // The following fields are informational, do not affect
76 // interpretation of results.
77
78 // Time of collection (UTC) represented as nanoseconds past the epoch.
79 int64 time_nanos = 9;
80 // Duration of the profile, if a duration makes sense.
81 int64 duration_nanos = 10;
82 // The kind of events between sampled occurrences.
83 // e.g [ "cpu","cycles" ] or [ "heap","bytes" ]
84 ValueType period_type = 11;
85 // The number of events between sampled occurrences.
86 int64 period = 12;
87 // Free-form text associated with the profile. The text is displayed as is
88 // to the user by the tools that read profiles (e.g. by pprof). This field
89 // should not be used to store any machine-readable information, it is only
90 // for human-friendly content. The profile must stay functional if this field
91 // is cleaned.
92 repeated int64 comment = 13; // Indices into string table.
93 // Index into the string table of the type of the preferred sample
94 // value. If unset, clients should default to the last sample value.
95 int64 default_sample_type = 14;
96}
97
98// ValueType describes the semantics and measurement units of a value.
99message ValueType {
100 int64 type = 1; // Index into string table.
101 int64 unit = 2; // Index into string table.
102}
103
104// Each Sample records values encountered in some program
105// context. The program context is typically a stack trace, perhaps
106// augmented with auxiliary information like the thread-id, some
107// indicator of a higher level request being handled etc.
108message Sample {
109 // The ids recorded here correspond to a Profile.location.id.
110 // The leaf is at location_id[0].
111 repeated uint64 location_id = 1;
112 // The type and unit of each value is defined by the corresponding
113 // entry in Profile.sample_type. All samples must have the same
114 // number of values, the same as the length of Profile.sample_type.
115 // When aggregating multiple samples into a single sample, the
116 // result has a list of values that is the element-wise sum of the
117 // lists of the originals.
118 repeated int64 value = 2;
119 // label includes additional context for this sample. It can include
120 // things like a thread id, allocation size, etc.
121 //
122 // NOTE: While possible, having multiple values for the same label key is
123 // strongly discouraged and should never be used. Most tools (e.g. pprof) do
124 // not have good (or any) support for multi-value labels. And an even more
125 // discouraged case is having a string label and a numeric label of the same
126 // name on a sample. Again, possible to express, but should not be used.
127 repeated Label label = 3;
128}
129
130message Label {
131 // Index into string table. An annotation for a sample (e.g.
132 // "allocation_size") with an associated value.
133 // Keys with "pprof::" prefix are reserved for internal use by pprof.
134 int64 key = 1;
135
136 // At most one of the following must be present
137 int64 str = 2; // Index into string table
138 int64 num = 3;
139
140 // Should only be present when num is present.
141 // Specifies the units of num.
142 // Use arbitrary string (for example, "requests") as a custom count unit.
143 // If no unit is specified, consumer may apply heuristic to deduce the unit.
144 // Consumers may also interpret units like "bytes" and "kilobytes" as memory
145 // units and units like "seconds" and "nanoseconds" as time units,
146 // and apply appropriate unit conversions to these.
147 int64 num_unit = 4; // Index into string table
148}
149
150message Mapping {
151 // Unique nonzero id for the mapping.
152 uint64 id = 1;
153 // Address at which the binary (or DLL) is loaded into memory.
154 uint64 memory_start = 2;
155 // The limit of the address range occupied by this mapping.
156 uint64 memory_limit = 3;
157 // Offset in the binary that corresponds to the first mapped address.
158 uint64 file_offset = 4;
159 // The object this entry is loaded from. This can be a filename on
160 // disk for the main binary and shared libraries, or virtual
161 // abstractions like "[vdso]".
162 int64 filename = 5; // Index into string table
163 // A string that uniquely identifies a particular program version
164 // with high probability. E.g., for binaries generated by GNU tools,
165 // it could be the contents of the .note.gnu.build-id field.
166 int64 build_id = 6; // Index into string table
167
168 // The following fields indicate the resolution of symbolic info.
169 bool has_functions = 7;
170 bool has_filenames = 8;
171 bool has_line_numbers = 9;
172 bool has_inline_frames = 10;
173}
174
175// Describes function and line table debug information.
176message Location {
177 // Unique nonzero id for the location. A profile could use
178 // instruction addresses or any integer sequence as ids.
179 uint64 id = 1;
180 // The id of the corresponding profile.Mapping for this location.
181 // It can be unset if the mapping is unknown or not applicable for
182 // this profile type.
183 uint64 mapping_id = 2;
184 // The instruction address for this location, if available. It
185 // should be within [Mapping.memory_start...Mapping.memory_limit]
186 // for the corresponding mapping. A non-leaf address may be in the
187 // middle of a call instruction. It is up to display tools to find
188 // the beginning of the instruction if necessary.
189 uint64 address = 3;
190 // Multiple line indicates this location has inlined functions,
191 // where the last entry represents the caller into which the
192 // preceding entries were inlined.
193 //
194 // E.g., if memcpy() is inlined into printf:
195 // line[0].function_name == "memcpy"
196 // line[1].function_name == "printf"
197 repeated Line line = 4;
198 // Provides an indication that multiple symbols map to this location's
199 // address, for example due to identical code folding by the linker. In that
200 // case the line information above represents one of the multiple
201 // symbols. This field must be recomputed when the symbolization state of the
202 // profile changes.
203 bool is_folded = 5;
204}
205
206message Line {
207 // The id of the corresponding profile.Function for this line.
208 uint64 function_id = 1;
209 // Line number in source code.
210 int64 line = 2;
211 // Column number in source code.
212 int64 column = 3;
213}
214
215message Function {
216 // Unique nonzero id for the function.
217 uint64 id = 1;
218 // Name of the function, in human-readable form if available.
219 int64 name = 2; // Index into string table
220 // Name of the function, as identified by the system.
221 // For instance, it can be a C++ mangled name.
222 int64 system_name = 3; // Index into string table
223 // Source file containing the function.
224 int64 filename = 4; // Index into string table
225 // Line number in source file.
226 int64 start_line = 5;
227}
View as plain text