Debian Codegraph @

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