Debian Codegraph @

opentelemetry/proto/profiles/v1development/profiles.proto

raw
1 // Copyright 2023, OpenTelemetry Authors
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 // This file includes work covered by the following copyright and permission notices:
16 //
17 // Copyright 2016 Google Inc. All Rights Reserved.
18 //
19 // Licensed under the Apache License, Version 2.0 (the "License");
20 // you may not use this file except in compliance with the License.
21 // You may obtain a copy of the License at
22 //
23 // http://www.apache.org/licenses/LICENSE-2.0
24 //
25 // Unless required by applicable law or agreed to in writing, software
26 // distributed under the License is distributed on an "AS IS" BASIS,
27 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
28 // See the License for the specific language governing permissions and
29 // limitations under the License.
30
31 syntax = "proto3";
32
33 package opentelemetry.proto.profiles.v1development;
34
35 import "opentelemetry/proto/common/v1/common.proto";
36 import "opentelemetry/proto/resource/v1/resource.proto";
37
38 option csharp_namespace = "OpenTelemetry.Proto.Profiles.V1Development";
39 option java_multiple_files = true;
40 option java_package = "io.opentelemetry.proto.profiles.v1development";
41 option java_outer_classname = "ProfilesProto";
42 option go_package = "go.opentelemetry.io/proto/otlp/profiles/v1development";
43
44 // Relationships Diagram
45 //
46 // ┌──────────────────┐ LEGEND
47 // │ ProfilesData │ ─────┐
48 // └──────────────────┘ │ ─────▶ embedded
49 // │ │
50 // │ 1-n │ ─────▷ referenced by index
51 // ▼ ▼
52 // ┌──────────────────┐ ┌────────────────────┐
53 // │ ResourceProfiles │ │ ProfilesDictionary │
54 // └──────────────────┘ └────────────────────┘
55 // │
56 // │ 1-n
57 // ▼
58 // ┌──────────────────┐
59 // │ ScopeProfiles │
60 // └──────────────────┘
61 // │
62 // │ 1-n
63 // ▼
64 // ┌──────────────────┐
65 // │ Profile │
66 // └──────────────────┘
67 // │ n-1
68 // │ 1-n ┌───────────────────────────────────────┐
69 // ▼ │ ▽
70 // ┌──────────────────┐ 1-n ┌─────────────────┐ ┌──────────┐
71 // │ Sample │ ──────▷ │ KeyValueAndUnit │ │ Link │
72 // └──────────────────┘ └─────────────────┘ └──────────┘
73 // │ △ △
74 // │ n-1 │ │ 1-n
75 // ▽ │ │
76 // ┌──────────────────┐ │ │
77 // │ Stack │ │ │
78 // └──────────────────┘ │ │
79 // │ 1-n │ │
80 // │ 1-n ┌────────────────┘ │
81 // ▽ │ │
82 // ┌──────────────────┐ n-1 ┌─────────────┐
83 // │ Location │ ──────▷ │ Mapping │
84 // └──────────────────┘ └─────────────┘
85 // │
86 // │ 1-n
87 // ▼
88 // ┌──────────────────┐
89 // │ Line │
90 // └──────────────────┘
91 // │
92 // │ 1-1
93 // ▽
94 // ┌──────────────────┐
95 // │ Function │
96 // └──────────────────┘
97 //
98
99 // ProfilesDictionary represents the profiles data shared across the
100 // entire message being sent.
101 //
102 // Note that all fields in this message MUST have a zero value encoded as the first element.
103 // This allows for _index fields pointing into the dictionary to use a 0 pointer value
104 // to indicate 'null' / 'not set'. Unless otherwise defined, a 'zero value' message value
105 // is one with all default field values, so as to minimize wire encoded size.
106 message ProfilesDictionary {
107 // Mappings from address ranges to the image/binary/library mapped
108 // into that address range referenced by locations via Location.mapping_index.
109 repeated Mapping mapping_table = 1;
110
111 // Locations referenced by samples via Stack.location_indices.
112 repeated Location location_table = 2;
113
114 // Functions referenced by locations via Line.function_index.
115 repeated Function function_table = 3;
116
117 // Links referenced by samples via Sample.link_index.
118 repeated Link link_table = 4;
119
120 // A common table for strings referenced by various messages.
121 // string_table[0] must always be "".
122 repeated string string_table = 5;
123
124 // A common table for attributes referenced by various messages.
125 // It is a collection of key/value pairs. Note, global attributes
126 // like server name can be set using the resource API. Examples of attributes:
127 //
128 // "/http/user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36"
129 // "/http/server_latency": 300
130 // "abc.com/myattribute": true
131 // "abc.com/score": 10.239
132 //
133 // The attribute values SHOULD NOT contain empty values.
134 // The attribute values SHOULD NOT contain bytes values.
135 // The attribute values SHOULD NOT contain array values different than array of string values, bool values, int values,
136 // double values.
137 // The attribute values SHOULD NOT contain kvlist values.
138 // The behavior of software that receives attributes containing such values can be unpredictable.
139 // These restrictions can change in a minor release.
140 // The restrictions take origin from the OpenTelemetry specification:
141 // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute.
142 repeated KeyValueAndUnit attribute_table = 6;
143
144 // Stacks referenced by samples via Sample.stack_index.
145 repeated Stack stack_table = 7;
146 }
147
148 // ProfilesData represents the profiles data that can be stored in persistent storage,
149 // OR can be embedded by other protocols that transfer OTLP profiles data but do not
150 // implement the OTLP protocol.
151 //
152 // The main difference between this message and collector protocol is that
153 // in this message there will not be any "control" or "metadata" specific to
154 // OTLP protocol.
155 //
156 // When new fields are added into this message, the OTLP request MUST be updated
157 // as well.
158 message ProfilesData {
159 // An array of ResourceProfiles.
160 // For data coming from an SDK profiler, this array will typically contain one
161 // element. Host-level profilers will usually create one ResourceProfile per
162 // container, as well as one additional ResourceProfile grouping all samples
163 // from non-containerized processes.
164 // Other resource groupings are possible as well and clarified via
165 // Resource.attributes and semantic conventions.
166 // Tools that visualize profiles should prefer displaying
167 // resources_profiles[0].scope_profiles[0].profiles[0] by default.
168 repeated ResourceProfiles resource_profiles = 1;
169
170 // One instance of ProfilesDictionary
171 ProfilesDictionary dictionary = 2;
172 }
173
174
175 // A collection of ScopeProfiles from a Resource.
176 message ResourceProfiles {
177 reserved 1000;
178
179 // The resource for the profiles in this message.
180 // If this field is not set then no resource info is known.
181 opentelemetry.proto.resource.v1.Resource resource = 1;
182
183 // A list of ScopeProfiles that originate from a resource.
184 repeated ScopeProfiles scope_profiles = 2;
185
186 // The Schema URL, if known. This is the identifier of the Schema that the resource data
187 // is recorded in. Notably, the last part of the URL path is the version number of the
188 // schema: http[s]://server[:port]/path/<version>. To learn more about Schema URL see
189 // https://opentelemetry.io/docs/specs/otel/schemas/#schema-url
190 // This schema_url applies to the data in the "resource" field. It does not apply
191 // to the data in the "scope_profiles" field which have their own schema_url field.
192 string schema_url = 3;
193 }
194
195 // A collection of Profiles produced by an InstrumentationScope.
196 message ScopeProfiles {
197 // The instrumentation scope information for the profiles in this message.
198 // Semantically when InstrumentationScope isn't set, it is equivalent with
199 // an empty instrumentation scope name (unknown).
200 opentelemetry.proto.common.v1.InstrumentationScope scope = 1;
201
202 // A list of Profiles that originate from an instrumentation scope.
203 repeated Profile profiles = 2;
204
205 // The Schema URL, if known. This is the identifier of the Schema that the profile data
206 // is recorded in. Notably, the last part of the URL path is the version number of the
207 // schema: http[s]://server[:port]/path/<version>. To learn more about Schema URL see
208 // https://opentelemetry.io/docs/specs/otel/schemas/#schema-url
209 // This schema_url applies to all profiles in the "profiles" field.
210 string schema_url = 3;
211 }
212
213 // Profile is a common stacktrace profile format.
214 //
215 // Measurements represented with this format should follow the
216 // following conventions:
217 //
218 // - Consumers should treat unset optional fields as if they had been
219 // set with their default value.
220 //
221 // - When possible, measurements should be stored in "unsampled" form
222 // that is most useful to humans. There should be enough
223 // information present to determine the original sampled values.
224 //
225 // - The profile is represented as a set of samples, where each sample
226 // references a stack trace which is a list of locations, each belonging
227 // to a mapping.
228 // - There is a N->1 relationship from Stack.location_indices entries to
229 // locations. For every Stack.location_indices entry there must be a
230 // unique Location with that index.
231 // - There is an optional N->1 relationship from locations to
232 // mappings. For every nonzero Location.mapping_id there must be a
233 // unique Mapping with that index.
234
235 // Represents a complete profile, including sample types, samples, mappings to
236 // binaries, stacks, locations, functions, string table, and additional
237 // metadata. It modifies and annotates pprof Profile with OpenTelemetry
238 // specific fields.
239 //
240 // Note that whilst fields in this message retain the name and field id from pprof in most cases
241 // for ease of understanding data migration, it is not intended that pprof:Profile and
242 // OpenTelemetry:Profile encoding be wire compatible.
243 message Profile {
244 // The type and unit of all Sample.values in this profile.
245 // For a cpu or off-cpu profile this might be:
246 // ["cpu","nanoseconds"] or ["off_cpu","nanoseconds"]
247 // For a heap profile, this might be:
248 // ["allocated_objects","count"] or ["allocated_space","bytes"],
249 ValueType sample_type = 1;
250 // The set of samples recorded in this profile.
251 repeated Sample sample = 2;
252
253 // The following fields 3-12 are informational, do not affect
254 // interpretation of results.
255
256 // Time of collection (UTC) represented as nanoseconds past the epoch.
257 fixed64 time_unix_nano = 3;
258 // Duration of the profile, if a duration makes sense.
259 uint64 duration_nano = 4;
260 // The kind of events between sampled occurrences.
261 // e.g [ "cpu","cycles" ] or [ "heap","bytes" ]
262 ValueType period_type = 5;
263 // The number of events between sampled occurrences.
264 int64 period = 6;
265 // Free-form text associated with the profile. The text is displayed as is
266 // to the user by the tools that read profiles (e.g. by pprof). This field
267 // should not be used to store any machine-readable information, it is only
268 // for human-friendly content. The profile must stay functional if this field
269 // is cleaned.
270 repeated int32 comment_strindices = 7; // Indices into ProfilesDictionary.string_table.
271
272 // A globally unique identifier for a profile. The ID is a 16-byte array. An ID with
273 // all zeroes is considered invalid. It may be used for deduplication and signal
274 // correlation purposes. It is acceptable to treat two profiles with different values
275 // in this field as not equal, even if they represented the same object at an earlier
276 // time.
277 // This field is optional; an ID may be assigned to an ID-less profile in a later step.
278 bytes profile_id = 8;
279
280 // dropped_attributes_count is the number of attributes that were discarded. Attributes
281 // can be discarded because their keys are too long or because there are too many
282 // attributes. If this value is 0, then no attributes were dropped.
283 uint32 dropped_attributes_count = 9;
284
285 // Specifies format of the original payload. Common values are defined in semantic conventions. [required if original_payload is present]
286 string original_payload_format = 10;
287
288 // Original payload can be stored in this field. This can be useful for users who want to get the original payload.
289 // Formats such as JFR are highly extensible and can contain more information than what is defined in this spec.
290 // Inclusion of original payload should be configurable by the user. Default behavior should be to not include the original payload.
291 // If the original payload is in pprof format, it SHOULD not be included in this field.
292 // The field is optional, however if it is present then equivalent converted data should be populated in other fields
293 // of this message as far as is practicable.
294 bytes original_payload = 11;
295
296 // References to attributes in attribute_table. [optional]
297 repeated int32 attribute_indices = 12;
298 }
299
300 // A pointer from a profile Sample to a trace Span.
301 // Connects a profile sample to a trace span, identified by unique trace and span IDs.
302 message Link {
303 // A unique identifier of a trace that this linked span is part of. The ID is a
304 // 16-byte array.
305 bytes trace_id = 1;
306
307 // A unique identifier for the linked span. The ID is an 8-byte array.
308 bytes span_id = 2;
309 }
310
311 // Specifies the method of aggregating metric values, either DELTA (change since last report)
312 // or CUMULATIVE (total since a fixed start time).
313 enum AggregationTemporality {
314 /* UNSPECIFIED is the default AggregationTemporality, it MUST not be used. */
315 AGGREGATION_TEMPORALITY_UNSPECIFIED = 0;
316
317 /** DELTA is an AggregationTemporality for a profiler which reports
318 changes since last report time. Successive metrics contain aggregation of
319 values from continuous and non-overlapping intervals.
320
321 The values for a DELTA metric are based only on the time interval
322 associated with one measurement cycle. There is no dependency on
323 previous measurements like is the case for CUMULATIVE metrics.
324
325 For example, consider a system measuring the number of requests that
326 it receives and reports the sum of these requests every second as a
327 DELTA metric:
328
329 1. The system starts receiving at time=t_0.
330 2. A request is received, the system measures 1 request.
331 3. A request is received, the system measures 1 request.
332 4. A request is received, the system measures 1 request.
333 5. The 1 second collection cycle ends. A metric is exported for the
334 number of requests received over the interval of time t_0 to
335 t_0+1 with a value of 3.
336 6. A request is received, the system measures 1 request.
337 7. A request is received, the system measures 1 request.
338 8. The 1 second collection cycle ends. A metric is exported for the
339 number of requests received over the interval of time t_0+1 to
340 t_0+2 with a value of 2. */
341 AGGREGATION_TEMPORALITY_DELTA = 1;
342
343 /** CUMULATIVE is an AggregationTemporality for a profiler which
344 reports changes since a fixed start time. This means that current values
345 of a CUMULATIVE metric depend on all previous measurements since the
346 start time. Because of this, the sender is required to retain this state
347 in some form. If this state is lost or invalidated, the CUMULATIVE metric
348 values MUST be reset and a new fixed start time following the last
349 reported measurement time sent MUST be used.
350
351 For example, consider a system measuring the number of requests that
352 it receives and reports the sum of these requests every second as a
353 CUMULATIVE metric:
354
355 1. The system starts receiving at time=t_0.
356 2. A request is received, the system measures 1 request.
357 3. A request is received, the system measures 1 request.
358 4. A request is received, the system measures 1 request.
359 5. The 1 second collection cycle ends. A metric is exported for the
360 number of requests received over the interval of time t_0 to
361 t_0+1 with a value of 3.
362 6. A request is received, the system measures 1 request.
363 7. A request is received, the system measures 1 request.
364 8. The 1 second collection cycle ends. A metric is exported for the
365 number of requests received over the interval of time t_0 to
366 t_0+2 with a value of 5.
367 9. The system experiences a fault and loses state.
368 10. The system recovers and resumes receiving at time=t_1.
369 11. A request is received, the system measures 1 request.
370 12. The 1 second collection cycle ends. A metric is exported for the
371 number of requests received over the interval of time t_1 to
372 t_1+1 with a value of 1.
373
374 Note: Even though, when reporting changes since last report time, using
375 CUMULATIVE is valid, it is not recommended. */
376 AGGREGATION_TEMPORALITY_CUMULATIVE = 2;
377 }
378
379 // ValueType describes the type and units of a value, with an optional aggregation temporality.
380 message ValueType {
381 int32 type_strindex = 1; // Index into ProfilesDictionary.string_table.
382 int32 unit_strindex = 2; // Index into ProfilesDictionary.string_table.
383
384 AggregationTemporality aggregation_temporality = 3;
385 }
386
387 // Each Sample records values encountered in some program context. The program
388 // context is typically a stack trace, perhaps augmented with auxiliary
389 // information like the thread-id, some indicator of a higher level request
390 // being handled etc.
391 //
392 // A Sample MUST have have at least one values or timestamps_unix_nano entry. If
393 // both fields are populated, they MUST contain the same number of elements, and
394 // the elements at the same index MUST refer to the same event.
395 //
396 // Examples of different ways of representing a sample with the total value of 10:
397 //
398 // Report of a stacktrace at 10 timestamps (consumers must assume the value is 1 for each point):
399 // values: []
400 // timestamps_unix_nano: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
401 //
402 // Report of a stacktrace with an aggregated value without timestamps:
403 // values: [10]
404 // timestamps_unix_nano: []
405 //
406 // Report of a stacktrace at 4 timestamps where each point records a specific value:
407 // values: [2, 2, 3, 3]
408 // timestamps_unix_nano: [1, 2, 3, 4]
409 message Sample {
410 // Reference to stack in ProfilesDictionary.stack_table.
411 int32 stack_index = 1;
412 // The type and unit of each value is defined by Profile.sample_type.
413 repeated int64 values = 2;
414 // References to attributes in ProfilesDictionary.attribute_table. [optional]
415 repeated int32 attribute_indices = 3;
416
417 // Reference to link in ProfilesDictionary.link_table. [optional]
418 // It can be unset / set to 0 if no link exists, as link_table[0] is always a 'null' default value.
419 int32 link_index = 4;
420
421 // Timestamps associated with Sample represented in nanoseconds. These
422 // timestamps should fall within the Profile's time range.
423 repeated fixed64 timestamps_unix_nano = 5;
424 }
425
426 // Describes the mapping of a binary in memory, including its address range,
427 // file offset, and metadata like build ID
428 message Mapping {
429 // Address at which the binary (or DLL) is loaded into memory.
430 uint64 memory_start = 1;
431 // The limit of the address range occupied by this mapping.
432 uint64 memory_limit = 2;
433 // Offset in the binary that corresponds to the first mapped address.
434 uint64 file_offset = 3;
435 // The object this entry is loaded from. This can be a filename on
436 // disk for the main binary and shared libraries, or virtual
437 // abstractions like "[vdso]".
438 int32 filename_strindex = 4; // Index into ProfilesDictionary.string_table.
439 // References to attributes in ProfilesDictionary.attribute_table. [optional]
440 repeated int32 attribute_indices = 5;
441 }
442
443 // A Stack represents a stack trace as a list of locations.
444 message Stack {
445 // References to locations in ProfilesDictionary.location_table.
446 // The first location is the leaf frame.
447 repeated int32 location_indices = 1;
448 }
449
450 // Describes function and line table debug information.
451 message Location {
452 // Reference to mapping in ProfilesDictionary.mapping_table.
453 // It can be unset / set to 0 if the mapping is unknown or not applicable for
454 // this profile type, as mapping_table[0] is always a 'null' default mapping.
455 int32 mapping_index = 1;
456 // The instruction address for this location, if available. It
457 // should be within [Mapping.memory_start...Mapping.memory_limit]
458 // for the corresponding mapping. A non-leaf address may be in the
459 // middle of a call instruction. It is up to display tools to find
460 // the beginning of the instruction if necessary.
461 uint64 address = 2;
462 // Multiple line indicates this location has inlined functions,
463 // where the last entry represents the caller into which the
464 // preceding entries were inlined.
465 //
466 // E.g., if memcpy() is inlined into printf:
467 // line[0].function_name == "memcpy"
468 // line[1].function_name == "printf"
469 repeated Line line = 3;
470 // References to attributes in ProfilesDictionary.attribute_table. [optional]
471 repeated int32 attribute_indices = 4;
472 }
473
474 // Details a specific line in a source code, linked to a function.
475 message Line {
476 // Reference to function in ProfilesDictionary.function_table.
477 int32 function_index = 1;
478 // Line number in source code. 0 means unset.
479 int64 line = 2;
480 // Column number in source code. 0 means unset.
481 int64 column = 3;
482 }
483
484 // Describes a function, including its human-readable name, system name,
485 // source file, and starting line number in the source.
486 message Function {
487 // Function name. Empty string if not available.
488 int32 name_strindex = 1;
489 // Function name, as identified by the system. For instance,
490 // it can be a C++ mangled name. Empty string if not available.
491 int32 system_name_strindex = 2;
492 // Source file containing the function. Empty string if not available.
493 int32 filename_strindex = 3;
494 // Line number in source file. 0 means unset.
495 int64 start_line = 4;
496 }
497
498 // A custom 'dictionary native' style of encoding attributes which is more convenient
499 // for profiles than opentelemetry.proto.common.v1.KeyValue
500 // Specifically, uses the string table for keys and allows optional unit information.
501 message KeyValueAndUnit {
502 int32 key_strindex = 1;
503 opentelemetry.proto.common.v1.AnyValue value = 2;
504 int32 unit_strindex = 3; // zero indicates implicit (by semconv) or non-defined unit.
505 }