metrics.proto

// Copyright 2019, OpenTelemetry Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package opentelemetry.proto.metrics.v1;

import "opentelemetry/proto/common/v1/common.proto";
import "opentelemetry/proto/resource/v1/resource.proto";

option java_multiple_files = true;
option java_package = "io.opentelemetry.proto.metrics.v1";
option java_outer_classname = "MetricsProto";
option go_package = "github.com/open-telemetry/opentelemetry-proto/gen/go/metrics/v1";

// A collection of InstrumentationLibraryMetrics from a Resource.
message ResourceMetrics {
  // The resource for the metrics in this message.
  // If this field is not set then no resource info is known.
  opentelemetry.proto.resource.v1.Resource resource = 1;

  // A list of metrics that originate from a resource.
  repeated InstrumentationLibraryMetrics instrumentation_library_metrics = 2;
}

// A collection of Metrics produced by an InstrumentationLibrary.
message InstrumentationLibraryMetrics {
  // The instrumentation library information for the metrics in this message.
  // If this field is not set then no library info is known.
  opentelemetry.proto.common.v1.InstrumentationLibrary instrumentation_library = 1;

  // A list of metrics that originate from an instrumentation library.
  repeated Metric metrics = 2;
}

// Defines a Metric which has one or more timeseries.
//
// The data model and relation between entities is shown in the diagram below.
//
// - Metric is composed of a MetricDescriptor and a list of data points.
// - MetricDescriptor contains a list of label keys (shown horizontally).
// - Data is a list of DataPoints (shown vertically).
// - DataPoint contains a list of label values and a value.
//
//     Metric
//  +----------+         +------------------------+
//  |descriptor|-------->| MetricDescriptor       |
//  |          |         |+-----+-----+   +-----+ |
//  |          |         ||label|label|...|label| |
//  |      data|--+      ||key1 |key2 |   |keyN | |
//  +----------+  |      |+-----+-----+   +-----+ |
//                |      +------------------------+
//                |
//                |      +---------------------------+
//                |      |DataPoint 1                |
//                v      |+------+------+   +------+ |
//             +-----+   ||label |label |...|label | |
//             |  1  |-->||value1|value2|...|valueN| |
//             +-----+   |+------+------+   +------+ |
//             |  .  |   |+-----+                    |
//             |  .  |   ||value|                    |
//             |  .  |   |+-----+                    |
//             |  .  |   +---------------------------+
//             |  .  |                   .
//             |  .  |                   .
//             |  .  |                   .
//             |  .  |   +---------------------------+
//             |  .  |   |DataPoint M                |
//             +-----+   |+------+------+   +------+ |
//             |  M  |-->||label |label |...|label | |
//             +-----+   ||value1|value2|...|valueN| |
//                       |+------+------+   +------+ |
//                       |+-----+                    |
//                       ||value|                    |
//                       |+-----+                    |
//                       +---------------------------+
//
//-----------------------------------------------------------------------
// DataPoint is a value of specific type corresponding to a given moment in
// time. Each DataPoint is timestamped.
//
// DataPoint is strongly typed: each DataPoint type has a specific Protobuf message
// depending on the value type of the metric and thus there are currently 4 DataPoint
// messages, which correspond to the types of metric values.
message Metric {
  // metric_descriptor describes the Metric.
  MetricDescriptor metric_descriptor = 1;

  // Data is a list of one or more DataPoints for a single metric. Only one of the
  // following fields is used for the data, depending on the type of the metric defined
  // by MetricDescriptor.type field.
  repeated Int64DataPoint int64_data_points = 2;
  repeated DoubleDataPoint double_data_points = 3;
  repeated HistogramDataPoint histogram_data_points = 4;
  repeated SummaryDataPoint summary_data_points = 5;
}

// Defines a metric type and its schema.
message MetricDescriptor {
  // name of the metric, including its DNS name prefix. It must be unique.
  string name = 1;

  // description of the metric, which can be used in documentation.
  string description = 2;

  // unit in which the metric value is reported. Follows the format
  // described by http://unitsofmeasure.org/ucum.html.
  string unit = 3;

  // Type is the type of values a metric has.
  enum Type {
    // INVALID_TYPE is the default Type, it MUST not be used.
    INVALID_TYPE = 0;

    // INT64 values are signed 64-bit integers.
    //
    // A Metric of this Type MUST store its values as Int64DataPoint.
    INT64 = 1;

    // MONOTONIC_INT64 values are monotonically increasing signed 64-bit
    // integers.
    //
    // A Metric of this Type MUST store its values as Int64DataPoint.
    MONOTONIC_INT64 = 2;

    // DOUBLE values are double-precision floating-point numbers.
    //
    // A Metric of this Type MUST store its values as DoubleDataPoint.
    DOUBLE = 3;

    // MONOTONIC_DOUBLE values are monotonically increasing double-precision
    // floating-point numbers.
    //
    // A Metric of this Type MUST store its values as DoubleDataPoint.
    MONOTONIC_DOUBLE = 4;

    // Histogram measurement.
    // Corresponding values are stored in HistogramDataPoint.
    HISTOGRAM = 5;

    // Summary value. Some frameworks implemented Histograms as a summary of observations
    // (usually things like request durations and response sizes). While it
    // also provides a total count of observations and a sum of all observed
    // values, it calculates configurable percentiles over a sliding time
    // window.
    // Corresponding values are stored in SummaryDataPoint.
    SUMMARY = 6;
  }

  // type is the type of values this metric has.
  Type type = 4;

  // Temporality is the temporal quality values of a metric have. It
  // describes how those values relate to the time interval over which they
  // are reported.
  enum Temporality {
    // INVALID_TEMPORALITY is the default Temporality, it MUST not be
    // used.
    INVALID_TEMPORALITY = 0;

    // INSTANTANEOUS is a metric whose values are measured at a particular
    // instant. The values are not aggregated over any time interval and are
    // unique per timestamp. As such, these metrics are not expected to have
    // an associated start time.
    INSTANTANEOUS = 1;

    // DELTA is a metric whose values are the aggregation of measurements
    // made over a time interval. Successive metrics contain aggregation of
    // values from continuous and non-overlapping intervals.
    //
    // The values for a DELTA metric are based only on the time interval
    // associated with one measurement cycle. There is no dependency on
    // previous measurements like is the case for CUMULATIVE metrics.
    //
    // For example, consider a system measuring the number of requests that
    // it receives and reports the sum of these requests every second as a
    // DELTA metric:
    //
    //   1. The system starts receiving at time=t_0.
    //   2. A request is received, the system measures 1 request.
    //   3. A request is received, the system measures 1 request.
    //   4. A request is received, the system measures 1 request.
    //   5. The 1 second collection cycle ends. A metric is exported for the
    //      number of requests received over the interval of time t_0 to
    //      t_0+1 with a value of 3.
    //   6. A request is received, the system measures 1 request.
    //   7. A request is received, the system measures 1 request.
    //   8. The 1 second collection cycle ends. A metric is exported for the
    //      number of requests received over the interval of time t_0+1 to
    //      t_0+2 with a value of 2.
    DELTA = 2;

    // CUMULATIVE is a metric whose values are the aggregation of
    // successively made measurements from a fixed start time until the last
    // reported measurement. This means that current values of a CUMULATIVE
    // metric depend on all previous measurements since the start time.
    // Because of this, the sender is required to retain this state in some
    // form. If this state is lost or invalidated, the CUMULATIVE metric
    // values MUST be reset and a new fixed start time following the last
    // reported measurement time sent MUST be used.
    //
    // For example, consider a system measuring the number of requests that
    // it receives and reports the sum of these requests every second as a
    // CUMULATIVE metric:
    //
    //   1. The system starts receiving at time=t_0.
    //   2. A request is received, the system measures 1 request.
    //   3. A request is received, the system measures 1 request.
    //   4. A request is received, the system measures 1 request.
    //   5. The 1 second collection cycle ends. A metric is exported for the
    //      number of requests received over the interval of time t_0 to
    //      t_0+1 with a value of 3.
    //   6. A request is received, the system measures 1 request.
    //   7. A request is received, the system measures 1 request.
    //   8. The 1 second collection cycle ends. A metric is exported for the
    //      number of requests received over the interval of time t_0 to
    //      t_0+2 with a value of 5.
    //   9. The system experiences a fault and loses state.
    //   10. The system recovers and resumes receiving at time=t_1.
    //   11. A request is received, the system measures 1 request.
    //   12. The 1 second collection cycle ends. A metric is exported for the
    //      number of requests received over the interval of time t_1 to
    //      t_0+1 with a value of 1.
    CUMULATIVE = 3;
  }

  // temporality is the Temporality of values this metric has.
  Temporality temporality = 5;
}

// Int64DataPoint is a single data point in a timeseries that describes the time-varying
// values of a int64 metric.
message Int64DataPoint {
  // The set of labels that uniquely identify this timeseries.
  repeated opentelemetry.proto.common.v1.StringKeyValue labels = 1;

  // start_time_unix_nano is the time when the cumulative value was reset to zero.
  // This is used for Counter type only. For Gauge the value is not specified and
  // defaults to 0.
  //
  // The cumulative value is over the time interval (start_time_unix_nano, time_unix_nano].
  // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
  //
  // Value of 0 indicates that the timestamp is unspecified. In that case the timestamp
  // may be decided by the backend.
  fixed64 start_time_unix_nano = 2;

  // time_unix_nano is the moment when this value was recorded.
  // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
  fixed64 time_unix_nano = 3;

  // value itself.
  int64 value = 4;
}

// DoubleDataPoint is a single data point in a timeseries that describes the time-varying
// value of a double metric.
message DoubleDataPoint {
  // The set of labels that uniquely identify this timeseries.
  repeated opentelemetry.proto.common.v1.StringKeyValue labels = 1;

  // start_time_unix_nano is the time when the cumulative value was reset to zero.
  // This is used for Counter type only. For Gauge the value is not specified and
  // defaults to 0.
  //
  // The cumulative value is over the time interval (start_time_unix_nano, time_unix_nano].
  // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
  //
  // Value of 0 indicates that the timestamp is unspecified. In that case the timestamp
  // may be decided by the backend.
  fixed64 start_time_unix_nano = 2;

  // time_unix_nano is the moment when this value was recorded.
  // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
  fixed64 time_unix_nano = 3;

  // value itself.
  double value = 4;
}

// HistogramDataPoint is a single data point in a timeseries that describes the time-varying
// values of a Histogram. A Histogram contains summary statistics for a population of values,
// it may optionally contain the distribution of those values across a set of buckets.
message HistogramDataPoint {
  // The set of labels that uniquely identify this timeseries.
  repeated opentelemetry.proto.common.v1.StringKeyValue labels = 1;

  // start_time_unix_nano is the time when the cumulative value was reset to zero.
  //
  // The cumulative value is over the time interval (start_time_unix_nano, time_unix_nano].
  // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
  //
  // Value of 0 indicates that the timestamp is unspecified. In that case the timestamp
  // may be decided by the backend.
  // Note: this field is always unspecified and ignored if MetricDescriptor.type==GAUGE_HISTOGRAM.
  fixed64 start_time_unix_nano = 2;

  // time_unix_nano is the moment when this value was recorded.
  // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
  fixed64 time_unix_nano = 3;

  // count is the number of values in the population. Must be non-negative. This value
  // must be equal to the sum of the "count" fields in buckets if a histogram is provided.
  uint64 count = 4;

  // sum of the values in the population. If count is zero then this field
  // must be zero. This value must be equal to the sum of the "sum" fields in buckets if
  // a histogram is provided.
  double sum = 5;

  // Bucket contains values for a bucket.
  message Bucket {
    // The number of values in each bucket of the histogram, as described by
    // bucket_options.
    uint64 count = 1;

    // Exemplars are example points that may be used to annotate aggregated
    // Histogram values. They are metadata that gives information about a
    // particular value added to a Histogram bucket.
    message Exemplar {
      // Value of the exemplar point. It determines which bucket the exemplar belongs to.
      // If bucket_options define bounds for this bucket then this value must be within
      // the defined bounds.
      double value = 1;

      // time_unix_nano is the moment when this exemplar was recorded.
      // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
      fixed64 time_unix_nano = 2;

      // exemplar_attachments are contextual information about the example value.
      // Keys in this list must be unique.
      repeated opentelemetry.proto.common.v1.StringKeyValue attachments = 3;
    }

    // exemplar is an optional representative value of the bucket.
    Exemplar exemplar = 2;
  }

  // buckets is an optional field contains the values of histogram for each bucket.
  //
  // The sum of the values in the buckets "count" field must equal the value in the count field.
  //
  // The number of elements in buckets array must be by one greater than the
  // number of elements in bucket_bounds array.
  //
  // Note: if HistogramDataPoint.bucket_options defines bucket bounds then this field
  // must also be present and number of elements in this field must be equal to the
  // number of buckets defined by bucket_options.
  repeated Bucket buckets = 6;

  // A histogram may optionally contain the distribution of the values in the population.
  // In that case one of the option fields below and "buckets" field both must be defined.
  // Otherwise all option fields and "buckets" field must be omitted in which case the
  // distribution of values in the histogram is unknown and only the total count and sum are known.

  // explicit_bounds is the only supported bucket option currently.
  // TODO: Add more bucket options.

  // explicit_bounds specifies buckets with explicitly defined bounds for values.
  // The bucket boundaries are described by "bounds" field.
  //
  // This defines size(bounds) + 1 (= N) buckets. The boundaries for bucket
  // at index i are:
  //
  // [0, bounds[i]) for i == 0
  // [bounds[i-1], bounds[i]) for 0 < i < N-1
  // [bounds[i], +infinity) for i == N-1
  // The values in bounds array must be strictly increasing and > 0.
  //
  // Note: only [a, b) intervals are currently supported for each bucket. If we decides
  // to also support (a, b] intervals we should add support for these by defining a boolean
  // value which decides what type of intervals to use.
  repeated double explicit_bounds = 7;
}

// SummaryDataPoint is a single data point in a timeseries that describes the time-varying
// values of a Summary metric.
message SummaryDataPoint {
  // The set of labels that uniquely identify this timeseries.
  repeated opentelemetry.proto.common.v1.StringKeyValue labels = 1;

  // start_time_unix_nano is the time when the cumulative value was reset to zero.
  //
  // The cumulative value is over the time interval (start_time_unix_nano, time_unix_nano].
  // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
  //
  // Value of 0 indicates that the timestamp is unspecified. In that case the timestamp
  // may be decided by the backend.
  fixed64 start_time_unix_nano = 2;

  // time_unix_nano is the moment when this value was recorded.
  // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
  fixed64 time_unix_nano = 3;

  // The total number of recorded values since start_time. Optional since
  // some systems don't expose this.
  uint64 count = 4;

  // The total sum of recorded values since start_time. Optional since some
  // systems don't expose this. If count is zero then this field must be zero.
  double sum = 5;

  // Represents the value at a given percentile of a distribution.
  //
  // To record Min and Max values following conventions are used:
  // - The 100th percentile is equivalent to the maximum value observed.
  // - The 0th percentile is equivalent to the minimum value observed.
  //
  // See the following issue for more context:
  // https://github.com/open-telemetry/opentelemetry-proto/issues/125
  message ValueAtPercentile {
    // The percentile of a distribution. Must be in the interval
    // [0.0, 100.0].
    double percentile = 1;

    // The value at the given percentile of a distribution.
    double value = 2;
  }

  // A list of values at different percentiles of the distribution calculated
  // from the current snapshot. The percentiles must be strictly increasing.
  repeated ValueAtPercentile percentile_values = 6;
}