Debian Codegraph @

opentelemetry/proto/metrics/v1/metrics.proto

raw
1 // Copyright 2019, 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 syntax = "proto3";
16
17 package opentelemetry.proto.metrics.v1;
18
19 import "opentelemetry/proto/common/v1/common.proto";
20 import "opentelemetry/proto/resource/v1/resource.proto";
21
22 option csharp_namespace = "OpenTelemetry.Proto.Metrics.V1";
23 option java_multiple_files = true;
24 option java_package = "io.opentelemetry.proto.metrics.v1";
25 option java_outer_classname = "MetricsProto";
26 option go_package = "go.opentelemetry.io/proto/otlp/metrics/v1";
27
28 // MetricsData represents the metrics data that can be stored in a persistent
29 // storage, OR can be embedded by other protocols that transfer OTLP metrics
30 // data but do not implement the OTLP protocol.
31 //
32 // MetricsData
33 // └─── ResourceMetrics
34 // ├── Resource
35 // ├── SchemaURL
36 // └── ScopeMetrics
37 // ├── Scope
38 // ├── SchemaURL
39 // └── Metric
40 // ├── Name
41 // ├── Description
42 // ├── Unit
43 // └── data
44 // ├── Gauge
45 // ├── Sum
46 // ├── Histogram
47 // ├── ExponentialHistogram
48 // └── Summary
49 //
50 // The main difference between this message and collector protocol is that
51 // in this message there will not be any "control" or "metadata" specific to
52 // OTLP protocol.
53 //
54 // When new fields are added into this message, the OTLP request MUST be updated
55 // as well.
56 message MetricsData {
57 // An array of ResourceMetrics.
58 // For data coming from a single resource this array will typically contain
59 // one element. Intermediary nodes that receive data from multiple origins
60 // typically batch the data before forwarding further and in that case this
61 // array will contain multiple elements.
62 repeated ResourceMetrics resource_metrics = 1;
63 }
64
65 // A collection of ScopeMetrics from a Resource.
66 message ResourceMetrics {
67 reserved 1000;
68
69 // The resource for the metrics in this message.
70 // If this field is not set then no resource info is known.
71 opentelemetry.proto.resource.v1.Resource resource = 1;
72
73 // A list of metrics that originate from a resource.
74 repeated ScopeMetrics scope_metrics = 2;
75
76 // The Schema URL, if known. This is the identifier of the Schema that the resource data
77 // is recorded in. Notably, the last part of the URL path is the version number of the
78 // schema: http[s]://server[:port]/path/<version>. To learn more about Schema URL see
79 // https://opentelemetry.io/docs/specs/otel/schemas/#schema-url
80 // This schema_url applies to the data in the "resource" field. It does not apply
81 // to the data in the "scope_metrics" field which have their own schema_url field.
82 string schema_url = 3;
83 }
84
85 // A collection of Metrics produced by an Scope.
86 message ScopeMetrics {
87 // The instrumentation scope information for the metrics in this message.
88 // Semantically when InstrumentationScope isn't set, it is equivalent with
89 // an empty instrumentation scope name (unknown).
90 opentelemetry.proto.common.v1.InstrumentationScope scope = 1;
91
92 // A list of metrics that originate from an instrumentation library.
93 repeated Metric metrics = 2;
94
95 // The Schema URL, if known. This is the identifier of the Schema that the metric data
96 // is recorded in. Notably, the last part of the URL path is the version number of the
97 // schema: http[s]://server[:port]/path/<version>. To learn more about Schema URL see
98 // https://opentelemetry.io/docs/specs/otel/schemas/#schema-url
99 // This schema_url applies to all metrics in the "metrics" field.
100 string schema_url = 3;
101 }
102
103 // Defines a Metric which has one or more timeseries. The following is a
104 // brief summary of the Metric data model. For more details, see:
105 //
106 // https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/data-model.md
107 //
108 // The data model and relation between entities is shown in the
109 // diagram below. Here, "DataPoint" is the term used to refer to any
110 // one of the specific data point value types, and "points" is the term used
111 // to refer to any one of the lists of points contained in the Metric.
112 //
113 // - Metric is composed of a metadata and data.
114 // - Metadata part contains a name, description, unit.
115 // - Data is one of the possible types (Sum, Gauge, Histogram, Summary).
116 // - DataPoint contains timestamps, attributes, and one of the possible value type
117 // fields.
118 //
119 // Metric
120 // +------------+
121 // |name |
122 // |description |
123 // |unit | +------------------------------------+
124 // |data |---> |Gauge, Sum, Histogram, Summary, ... |
125 // +------------+ +------------------------------------+
126 //
127 // Data [One of Gauge, Sum, Histogram, Summary, ...]
128 // +-----------+
129 // |... | // Metadata about the Data.
130 // |points |--+
131 // +-----------+ |
132 // | +---------------------------+
133 // | |DataPoint 1 |
134 // v |+------+------+ +------+ |
135 // +-----+ ||label |label |...|label | |
136 // | 1 |-->||value1|value2|...|valueN| |
137 // +-----+ |+------+------+ +------+ |
138 // | . | |+-----+ |
139 // | . | ||value| |
140 // | . | |+-----+ |
141 // | . | +---------------------------+
142 // | . | .
143 // | . | .
144 // | . | .
145 // | . | +---------------------------+
146 // | . | |DataPoint M |
147 // +-----+ |+------+------+ +------+ |
148 // | M |-->||label |label |...|label | |
149 // +-----+ ||value1|value2|...|valueN| |
150 // |+------+------+ +------+ |
151 // |+-----+ |
152 // ||value| |
153 // |+-----+ |
154 // +---------------------------+
155 //
156 // Each distinct type of DataPoint represents the output of a specific
157 // aggregation function, the result of applying the DataPoint's
158 // associated function of to one or more measurements.
159 //
160 // All DataPoint types have three common fields:
161 // - Attributes includes key-value pairs associated with the data point
162 // - TimeUnixNano is required, set to the end time of the aggregation
163 // - StartTimeUnixNano is optional, but strongly encouraged for DataPoints
164 // having an AggregationTemporality field, as discussed below.
165 //
166 // Both TimeUnixNano and StartTimeUnixNano values are expressed as
167 // UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
168 //
169 // # TimeUnixNano
170 //
171 // This field is required, having consistent interpretation across
172 // DataPoint types. TimeUnixNano is the moment corresponding to when
173 // the data point's aggregate value was captured.
174 //
175 // Data points with the 0 value for TimeUnixNano SHOULD be rejected
176 // by consumers.
177 //
178 // # StartTimeUnixNano
179 //
180 // StartTimeUnixNano in general allows detecting when a sequence of
181 // observations is unbroken. This field indicates to consumers the
182 // start time for points with cumulative and delta
183 // AggregationTemporality, and it should be included whenever possible
184 // to support correct rate calculation. Although it may be omitted
185 // when the start time is truly unknown, setting StartTimeUnixNano is
186 // strongly encouraged.
187 message Metric {
188 reserved 4, 6, 8;
189
190 // name of the metric.
191 string name = 1;
192
193 // description of the metric, which can be used in documentation.
194 string description = 2;
195
196 // unit in which the metric value is reported. Follows the format
197 // described by https://unitsofmeasure.org/ucum.html.
198 string unit = 3;
199
200 // Data determines the aggregation type (if any) of the metric, what is the
201 // reported value type for the data points, as well as the relatationship to
202 // the time interval over which they are reported.
203 oneof data {
204 Gauge gauge = 5;
205 Sum sum = 7;
206 Histogram histogram = 9;
207 ExponentialHistogram exponential_histogram = 10;
208 Summary summary = 11;
209 }
210
211 // Additional metadata attributes that describe the metric. [Optional].
212 // Attributes are non-identifying.
213 // Consumers SHOULD NOT need to be aware of these attributes.
214 // These attributes MAY be used to encode information allowing
215 // for lossless roundtrip translation to / from another data model.
216 // Attribute keys MUST be unique (it is not allowed to have more than one
217 // attribute with the same key).
218 repeated opentelemetry.proto.common.v1.KeyValue metadata = 12;
219 }
220
221 // Gauge represents the type of a scalar metric that always exports the
222 // "current value" for every data point. It should be used for an "unknown"
223 // aggregation.
224 //
225 // A Gauge does not support different aggregation temporalities. Given the
226 // aggregation is unknown, points cannot be combined using the same
227 // aggregation, regardless of aggregation temporalities. Therefore,
228 // AggregationTemporality is not included. Consequently, this also means
229 // "StartTimeUnixNano" is ignored for all data points.
230 message Gauge {
231 repeated NumberDataPoint data_points = 1;
232 }
233
234 // Sum represents the type of a scalar metric that is calculated as a sum of all
235 // reported measurements over a time interval.
236 message Sum {
237 repeated NumberDataPoint data_points = 1;
238
239 // aggregation_temporality describes if the aggregator reports delta changes
240 // since last report time, or cumulative changes since a fixed start time.
241 AggregationTemporality aggregation_temporality = 2;
242
243 // If "true" means that the sum is monotonic.
244 bool is_monotonic = 3;
245 }
246
247 // Histogram represents the type of a metric that is calculated by aggregating
248 // as a Histogram of all reported measurements over a time interval.
249 message Histogram {
250 repeated HistogramDataPoint data_points = 1;
251
252 // aggregation_temporality describes if the aggregator reports delta changes
253 // since last report time, or cumulative changes since a fixed start time.
254 AggregationTemporality aggregation_temporality = 2;
255 }
256
257 // ExponentialHistogram represents the type of a metric that is calculated by aggregating
258 // as a ExponentialHistogram of all reported double measurements over a time interval.
259 message ExponentialHistogram {
260 repeated ExponentialHistogramDataPoint data_points = 1;
261
262 // aggregation_temporality describes if the aggregator reports delta changes
263 // since last report time, or cumulative changes since a fixed start time.
264 AggregationTemporality aggregation_temporality = 2;
265 }
266
267 // Summary metric data are used to convey quantile summaries,
268 // a Prometheus (see: https://prometheus.io/docs/concepts/metric_types/#summary)
269 // and OpenMetrics (see: https://github.com/prometheus/OpenMetrics/blob/4dbf6075567ab43296eed941037c12951faafb92/protos/prometheus.proto#L45)
270 // data type. These data points cannot always be merged in a meaningful way.
271 // While they can be useful in some applications, histogram data points are
272 // recommended for new applications.
273 // Summary metrics do not have an aggregation temporality field. This is
274 // because the count and sum fields of a SummaryDataPoint are assumed to be
275 // cumulative values.
276 message Summary {
277 repeated SummaryDataPoint data_points = 1;
278 }
279
280 // AggregationTemporality defines how a metric aggregator reports aggregated
281 // values. It describes how those values relate to the time interval over
282 // which they are aggregated.
283 enum AggregationTemporality {
284 // UNSPECIFIED is the default AggregationTemporality, it MUST not be used.
285 AGGREGATION_TEMPORALITY_UNSPECIFIED = 0;
286
287 // DELTA is an AggregationTemporality for a metric aggregator which reports
288 // changes since last report time. Successive metrics contain aggregation of
289 // values from continuous and non-overlapping intervals.
290 //
291 // The values for a DELTA metric are based only on the time interval
292 // associated with one measurement cycle. There is no dependency on
293 // previous measurements like is the case for CUMULATIVE metrics.
294 //
295 // For example, consider a system measuring the number of requests that
296 // it receives and reports the sum of these requests every second as a
297 // DELTA metric:
298 //
299 // 1. The system starts receiving at time=t_0.
300 // 2. A request is received, the system measures 1 request.
301 // 3. A request is received, the system measures 1 request.
302 // 4. A request is received, the system measures 1 request.
303 // 5. The 1 second collection cycle ends. A metric is exported for the
304 // number of requests received over the interval of time t_0 to
305 // t_0+1 with a value of 3.
306 // 6. A request is received, the system measures 1 request.
307 // 7. A request is received, the system measures 1 request.
308 // 8. The 1 second collection cycle ends. A metric is exported for the
309 // number of requests received over the interval of time t_0+1 to
310 // t_0+2 with a value of 2.
311 AGGREGATION_TEMPORALITY_DELTA = 1;
312
313 // CUMULATIVE is an AggregationTemporality for a metric aggregator which
314 // reports changes since a fixed start time. This means that current values
315 // of a CUMULATIVE metric depend on all previous measurements since the
316 // start time. Because of this, the sender is required to retain this state
317 // in some form. If this state is lost or invalidated, the CUMULATIVE metric
318 // values MUST be reset and a new fixed start time following the last
319 // reported measurement time sent MUST be used.
320 //
321 // For example, consider a system measuring the number of requests that
322 // it receives and reports the sum of these requests every second as a
323 // CUMULATIVE metric:
324 //
325 // 1. The system starts receiving at time=t_0.
326 // 2. A request is received, the system measures 1 request.
327 // 3. A request is received, the system measures 1 request.
328 // 4. A request is received, the system measures 1 request.
329 // 5. The 1 second collection cycle ends. A metric is exported for the
330 // number of requests received over the interval of time t_0 to
331 // t_0+1 with a value of 3.
332 // 6. A request is received, the system measures 1 request.
333 // 7. A request is received, the system measures 1 request.
334 // 8. The 1 second collection cycle ends. A metric is exported for the
335 // number of requests received over the interval of time t_0 to
336 // t_0+2 with a value of 5.
337 // 9. The system experiences a fault and loses state.
338 // 10. The system recovers and resumes receiving at time=t_1.
339 // 11. A request is received, the system measures 1 request.
340 // 12. The 1 second collection cycle ends. A metric is exported for the
341 // number of requests received over the interval of time t_1 to
342 // t_0+1 with a value of 1.
343 //
344 // Note: Even though, when reporting changes since last report time, using
345 // CUMULATIVE is valid, it is not recommended. This may cause problems for
346 // systems that do not use start_time to determine when the aggregation
347 // value was reset (e.g. Prometheus).
348 AGGREGATION_TEMPORALITY_CUMULATIVE = 2;
349 }
350
351 // DataPointFlags is defined as a protobuf 'uint32' type and is to be used as a
352 // bit-field representing 32 distinct boolean flags. Each flag defined in this
353 // enum is a bit-mask. To test the presence of a single flag in the flags of
354 // a data point, for example, use an expression like:
355 //
356 // (point.flags & DATA_POINT_FLAGS_NO_RECORDED_VALUE_MASK) == DATA_POINT_FLAGS_NO_RECORDED_VALUE_MASK
357 //
358 enum DataPointFlags {
359 // The zero value for the enum. Should not be used for comparisons.
360 // Instead use bitwise "and" with the appropriate mask as shown above.
361 DATA_POINT_FLAGS_DO_NOT_USE = 0;
362
363 // This DataPoint is valid but has no recorded value. This value
364 // SHOULD be used to reflect explicitly missing data in a series, as
365 // for an equivalent to the Prometheus "staleness marker".
366 DATA_POINT_FLAGS_NO_RECORDED_VALUE_MASK = 1;
367
368 // Bits 2-31 are reserved for future use.
369 }
370
371 // NumberDataPoint is a single data point in a timeseries that describes the
372 // time-varying scalar value of a metric.
373 message NumberDataPoint {
374 reserved 1;
375
376 // The set of key/value pairs that uniquely identify the timeseries from
377 // where this point belongs. The list may be empty (may contain 0 elements).
378 // Attribute keys MUST be unique (it is not allowed to have more than one
379 // attribute with the same key).
380 //
381 // The attribute values SHOULD NOT contain empty values.
382 // The attribute values SHOULD NOT contain bytes values.
383 // The attribute values SHOULD NOT contain array values different than array of string values, bool values, int values,
384 // double values.
385 // The attribute values SHOULD NOT contain kvlist values.
386 // The behavior of software that receives attributes containing such values can be unpredictable.
387 // These restrictions can change in a minor release.
388 // The restrictions take origin from the OpenTelemetry specification:
389 // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute.
390 repeated opentelemetry.proto.common.v1.KeyValue attributes = 7;
391
392 // StartTimeUnixNano is optional but strongly encouraged, see the
393 // the detailed comments above Metric.
394 //
395 // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
396 // 1970.
397 fixed64 start_time_unix_nano = 2;
398
399 // TimeUnixNano is required, see the detailed comments above Metric.
400 //
401 // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
402 // 1970.
403 fixed64 time_unix_nano = 3;
404
405 // The value itself. A point is considered invalid when one of the recognized
406 // value fields is not present inside this oneof.
407 oneof value {
408 double as_double = 4;
409 sfixed64 as_int = 6;
410 }
411
412 // (Optional) List of exemplars collected from
413 // measurements that were used to form the data point
414 repeated Exemplar exemplars = 5;
415
416 // Flags that apply to this specific data point. See DataPointFlags
417 // for the available flags and their meaning.
418 uint32 flags = 8;
419 }
420
421 // HistogramDataPoint is a single data point in a timeseries that describes the
422 // time-varying values of a Histogram. A Histogram contains summary statistics
423 // for a population of values, it may optionally contain the distribution of
424 // those values across a set of buckets.
425 //
426 // If the histogram contains the distribution of values, then both
427 // "explicit_bounds" and "bucket counts" fields must be defined.
428 // If the histogram does not contain the distribution of values, then both
429 // "explicit_bounds" and "bucket_counts" must be omitted and only "count" and
430 // "sum" are known.
431 message HistogramDataPoint {
432 reserved 1;
433
434 // The set of key/value pairs that uniquely identify the timeseries from
435 // where this point belongs. The list may be empty (may contain 0 elements).
436 // Attribute keys MUST be unique (it is not allowed to have more than one
437 // attribute with the same key).
438 //
439 // The attribute values SHOULD NOT contain empty values.
440 // The attribute values SHOULD NOT contain bytes values.
441 // The attribute values SHOULD NOT contain array values different than array of string values, bool values, int values,
442 // double values.
443 // The attribute values SHOULD NOT contain kvlist values.
444 // The behavior of software that receives attributes containing such values can be unpredictable.
445 // These restrictions can change in a minor release.
446 // The restrictions take origin from the OpenTelemetry specification:
447 // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute.
448 repeated opentelemetry.proto.common.v1.KeyValue attributes = 9;
449
450 // StartTimeUnixNano is optional but strongly encouraged, see the
451 // the detailed comments above Metric.
452 //
453 // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
454 // 1970.
455 fixed64 start_time_unix_nano = 2;
456
457 // TimeUnixNano is required, see the detailed comments above Metric.
458 //
459 // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
460 // 1970.
461 fixed64 time_unix_nano = 3;
462
463 // count is the number of values in the population. Must be non-negative. This
464 // value must be equal to the sum of the "count" fields in buckets if a
465 // histogram is provided.
466 fixed64 count = 4;
467
468 // sum of the values in the population. If count is zero then this field
469 // must be zero.
470 //
471 // Note: Sum should only be filled out when measuring non-negative discrete
472 // events, and is assumed to be monotonic over the values of these events.
473 // Negative events *can* be recorded, but sum should not be filled out when
474 // doing so. This is specifically to enforce compatibility w/ OpenMetrics,
475 // see: https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#histogram
476 optional double sum = 5;
477
478 // bucket_counts is an optional field contains the count values of histogram
479 // for each bucket.
480 //
481 // The sum of the bucket_counts must equal the value in the count field.
482 //
483 // The number of elements in bucket_counts array must be by one greater than
484 // the number of elements in explicit_bounds array. The exception to this rule
485 // is when the length of bucket_counts is 0, then the length of explicit_bounds
486 // must also be 0.
487 repeated fixed64 bucket_counts = 6;
488
489 // explicit_bounds specifies buckets with explicitly defined bounds for values.
490 //
491 // The boundaries for bucket at index i are:
492 //
493 // (-infinity, explicit_bounds[i]] for i == 0
494 // (explicit_bounds[i-1], explicit_bounds[i]] for 0 < i < size(explicit_bounds)
495 // (explicit_bounds[i-1], +infinity) for i == size(explicit_bounds)
496 //
497 // The values in the explicit_bounds array must be strictly increasing.
498 //
499 // Histogram buckets are inclusive of their upper boundary, except the last
500 // bucket where the boundary is at infinity. This format is intentionally
501 // compatible with the OpenMetrics histogram definition.
502 //
503 // If bucket_counts length is 0 then explicit_bounds length must also be 0,
504 // otherwise the data point is invalid.
505 repeated double explicit_bounds = 7;
506
507 // (Optional) List of exemplars collected from
508 // measurements that were used to form the data point
509 repeated Exemplar exemplars = 8;
510
511 // Flags that apply to this specific data point. See DataPointFlags
512 // for the available flags and their meaning.
513 uint32 flags = 10;
514
515 // min is the minimum value over (start_time, end_time].
516 optional double min = 11;
517
518 // max is the maximum value over (start_time, end_time].
519 optional double max = 12;
520 }
521
522 // ExponentialHistogramDataPoint is a single data point in a timeseries that describes the
523 // time-varying values of a ExponentialHistogram of double values. A ExponentialHistogram contains
524 // summary statistics for a population of values, it may optionally contain the
525 // distribution of those values across a set of buckets.
526 //
527 message ExponentialHistogramDataPoint {
528 // The set of key/value pairs that uniquely identify the timeseries from
529 // where this point belongs. The list may be empty (may contain 0 elements).
530 // Attribute keys MUST be unique (it is not allowed to have more than one
531 // attribute with the same key).
532 //
533 // The attribute values SHOULD NOT contain empty values.
534 // The attribute values SHOULD NOT contain bytes values.
535 // The attribute values SHOULD NOT contain array values different than array of string values, bool values, int values,
536 // double values.
537 // The attribute values SHOULD NOT contain kvlist values.
538 // The behavior of software that receives attributes containing such values can be unpredictable.
539 // These restrictions can change in a minor release.
540 // The restrictions take origin from the OpenTelemetry specification:
541 // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute.
542 repeated opentelemetry.proto.common.v1.KeyValue attributes = 1;
543
544 // StartTimeUnixNano is optional but strongly encouraged, see the
545 // the detailed comments above Metric.
546 //
547 // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
548 // 1970.
549 fixed64 start_time_unix_nano = 2;
550
551 // TimeUnixNano is required, see the detailed comments above Metric.
552 //
553 // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
554 // 1970.
555 fixed64 time_unix_nano = 3;
556
557 // count is the number of values in the population. Must be
558 // non-negative. This value must be equal to the sum of the "bucket_counts"
559 // values in the positive and negative Buckets plus the "zero_count" field.
560 fixed64 count = 4;
561
562 // sum of the values in the population. If count is zero then this field
563 // must be zero.
564 //
565 // Note: Sum should only be filled out when measuring non-negative discrete
566 // events, and is assumed to be monotonic over the values of these events.
567 // Negative events *can* be recorded, but sum should not be filled out when
568 // doing so. This is specifically to enforce compatibility w/ OpenMetrics,
569 // see: https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#histogram
570 optional double sum = 5;
571
572 // scale describes the resolution of the histogram. Boundaries are
573 // located at powers of the base, where:
574 //
575 // base = (2^(2^-scale))
576 //
577 // The histogram bucket identified by `index`, a signed integer,
578 // contains values that are greater than (base^index) and
579 // less than or equal to (base^(index+1)).
580 //
581 // The positive and negative ranges of the histogram are expressed
582 // separately. Negative values are mapped by their absolute value
583 // into the negative range using the same scale as the positive range.
584 //
585 // scale is not restricted by the protocol, as the permissible
586 // values depend on the range of the data.
587 sint32 scale = 6;
588
589 // zero_count is the count of values that are either exactly zero or
590 // within the region considered zero by the instrumentation at the
591 // tolerated degree of precision. This bucket stores values that
592 // cannot be expressed using the standard exponential formula as
593 // well as values that have been rounded to zero.
594 //
595 // Implementations MAY consider the zero bucket to have probability
596 // mass equal to (zero_count / count).
597 fixed64 zero_count = 7;
598
599 // positive carries the positive range of exponential bucket counts.
600 Buckets positive = 8;
601
602 // negative carries the negative range of exponential bucket counts.
603 Buckets negative = 9;
604
605 // Buckets are a set of bucket counts, encoded in a contiguous array
606 // of counts.
607 message Buckets {
608 // Offset is the bucket index of the first entry in the bucket_counts array.
609 //
610 // Note: This uses a varint encoding as a simple form of compression.
611 sint32 offset = 1;
612
613 // bucket_counts is an array of count values, where bucket_counts[i] carries
614 // the count of the bucket at index (offset+i). bucket_counts[i] is the count
615 // of values greater than base^(offset+i) and less than or equal to
616 // base^(offset+i+1).
617 //
618 // Note: By contrast, the explicit HistogramDataPoint uses
619 // fixed64. This field is expected to have many buckets,
620 // especially zeros, so uint64 has been selected to ensure
621 // varint encoding.
622 repeated uint64 bucket_counts = 2;
623 }
624
625 // Flags that apply to this specific data point. See DataPointFlags
626 // for the available flags and their meaning.
627 uint32 flags = 10;
628
629 // (Optional) List of exemplars collected from
630 // measurements that were used to form the data point
631 repeated Exemplar exemplars = 11;
632
633 // min is the minimum value over (start_time, end_time].
634 optional double min = 12;
635
636 // max is the maximum value over (start_time, end_time].
637 optional double max = 13;
638
639 // ZeroThreshold may be optionally set to convey the width of the zero
640 // region. Where the zero region is defined as the closed interval
641 // [-ZeroThreshold, ZeroThreshold].
642 // When ZeroThreshold is 0, zero count bucket stores values that cannot be
643 // expressed using the standard exponential formula as well as values that
644 // have been rounded to zero.
645 double zero_threshold = 14;
646 }
647
648 // SummaryDataPoint is a single data point in a timeseries that describes the
649 // time-varying values of a Summary metric. The count and sum fields represent
650 // cumulative values.
651 message SummaryDataPoint {
652 reserved 1;
653
654 // The set of key/value pairs that uniquely identify the timeseries from
655 // where this point belongs. The list may be empty (may contain 0 elements).
656 // Attribute keys MUST be unique (it is not allowed to have more than one
657 // attribute with the same key).
658 //
659 // The attribute values SHOULD NOT contain empty values.
660 // The attribute values SHOULD NOT contain bytes values.
661 // The attribute values SHOULD NOT contain array values different than array of string values, bool values, int values,
662 // double values.
663 // The attribute values SHOULD NOT contain kvlist values.
664 // The behavior of software that receives attributes containing such values can be unpredictable.
665 // These restrictions can change in a minor release.
666 // The restrictions take origin from the OpenTelemetry specification:
667 // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute.
668 repeated opentelemetry.proto.common.v1.KeyValue attributes = 7;
669
670 // StartTimeUnixNano is optional but strongly encouraged, see the
671 // the detailed comments above Metric.
672 //
673 // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
674 // 1970.
675 fixed64 start_time_unix_nano = 2;
676
677 // TimeUnixNano is required, see the detailed comments above Metric.
678 //
679 // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
680 // 1970.
681 fixed64 time_unix_nano = 3;
682
683 // count is the number of values in the population. Must be non-negative.
684 fixed64 count = 4;
685
686 // sum of the values in the population. If count is zero then this field
687 // must be zero.
688 //
689 // Note: Sum should only be filled out when measuring non-negative discrete
690 // events, and is assumed to be monotonic over the values of these events.
691 // Negative events *can* be recorded, but sum should not be filled out when
692 // doing so. This is specifically to enforce compatibility w/ OpenMetrics,
693 // see: https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#summary
694 double sum = 5;
695
696 // Represents the value at a given quantile of a distribution.
697 //
698 // To record Min and Max values following conventions are used:
699 // - The 1.0 quantile is equivalent to the maximum value observed.
700 // - The 0.0 quantile is equivalent to the minimum value observed.
701 //
702 // See the following issue for more context:
703 // https://github.com/open-telemetry/opentelemetry-proto/issues/125
704 message ValueAtQuantile {
705 // The quantile of a distribution. Must be in the interval
706 // [0.0, 1.0].
707 double quantile = 1;
708
709 // The value at the given quantile of a distribution.
710 //
711 // Quantile values must NOT be negative.
712 double value = 2;
713 }
714
715 // (Optional) list of values at different quantiles of the distribution calculated
716 // from the current snapshot. The quantiles must be strictly increasing.
717 repeated ValueAtQuantile quantile_values = 6;
718
719 // Flags that apply to this specific data point. See DataPointFlags
720 // for the available flags and their meaning.
721 uint32 flags = 8;
722 }
723
724 // A representation of an exemplar, which is a sample input measurement.
725 // Exemplars also hold information about the environment when the measurement
726 // was recorded, for example the span and trace ID of the active span when the
727 // exemplar was recorded.
728 message Exemplar {
729 reserved 1;
730
731 // The set of key/value pairs that were filtered out by the aggregator, but
732 // recorded alongside the original measurement. Only key/value pairs that were
733 // filtered out by the aggregator should be included
734 repeated opentelemetry.proto.common.v1.KeyValue filtered_attributes = 7;
735
736 // time_unix_nano is the exact time when this exemplar was recorded
737 //
738 // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
739 // 1970.
740 fixed64 time_unix_nano = 2;
741
742 // The value of the measurement that was recorded. An exemplar is
743 // considered invalid when one of the recognized value fields is not present
744 // inside this oneof.
745 oneof value {
746 double as_double = 3;
747 sfixed64 as_int = 6;
748 }
749
750 // (Optional) Span ID of the exemplar trace.
751 // span_id may be missing if the measurement is not recorded inside a trace
752 // or if the trace is not sampled.
753 bytes span_id = 4;
754
755 // (Optional) Trace ID of the exemplar trace.
756 // trace_id may be missing if the measurement is not recorded inside a trace
757 // or if the trace is not sampled.
758 bytes trace_id = 5;
759 }