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
32syntax = "proto3";
33
34package perftools.profiles;
35
36option java_package = "com.google.perftools.profiles";
37option java_outer_classname = "ProfileProto";
38
39message 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.
88message 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.
97message 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
113message 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
121message 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.
147message 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
171message 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
178message 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