metrics.proto

// Copyright 2013 Prometheus Team
// 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 = "proto2";

package io.prometheus.client;
option java_package = "io.prometheus.client";
option go_package = "github.com/prometheus/client_model/go;io_prometheus_client";

import "google/protobuf/timestamp.proto";

message LabelPair {
  optional string name  = 1;
  optional string value = 2;
}

enum MetricType {
  // COUNTER must use the Metric field "counter".
  COUNTER = 0;
  // GAUGE must use the Metric field "gauge".
  GAUGE = 1;
  // SUMMARY must use the Metric field "summary".
  SUMMARY = 2;
  // UNTYPED must use the Metric field "untyped".
  UNTYPED = 3;
  // HISTOGRAM must use the Metric field "histogram".
  HISTOGRAM = 4;
  // GAUGE_HISTOGRAM must use the Metric field "histogram".
  GAUGE_HISTOGRAM = 5;
}

message Gauge {
  optional double value = 1;
}

message Counter {
  optional double   value    = 1;
  optional Exemplar exemplar = 2;

  optional google.protobuf.Timestamp  created_timestamp = 3;
}

message Quantile {
  optional double quantile = 1;
  optional double value    = 2;
}

message Summary {
  optional uint64   sample_count = 1;
  optional double   sample_sum   = 2;
  repeated Quantile quantile     = 3;

  optional google.protobuf.Timestamp  created_timestamp = 4;
}

message Untyped {
  optional double value = 1;
}

message Histogram {
  optional uint64 sample_count       = 1;
  optional double sample_count_float = 4; // Overrides sample_count if > 0.
  optional double sample_sum         = 2;
  // Buckets for the conventional histogram.
  repeated Bucket bucket             = 3; // Ordered in increasing order of upper_bound, +Inf bucket is optional.

  optional google.protobuf.Timestamp created_timestamp = 15;

  // Everything below here is for native histograms (also known as sparse histograms).
  // Native histograms are an experimental feature without stability guarantees.

  // schema defines the bucket schema. Currently, valid numbers are -4 <= n <= 8.
  // They are all for base-2 bucket schemas, where 1 is a bucket boundary in each case, and
  // then each power of two is divided into 2^n logarithmic buckets.
  // Or in other words, each bucket boundary is the previous boundary times 2^(2^-n).
  // In the future, more bucket schemas may be added using numbers < -4 or > 8.
  optional sint32 schema           = 5;
  optional double zero_threshold   = 6; // Breadth of the zero bucket.
  optional uint64 zero_count       = 7; // Count in zero bucket.
  optional double zero_count_float = 8; // Overrides sb_zero_count if > 0.

  // Negative buckets for the native histogram.
  repeated BucketSpan negative_span =  9;
  // Use either "negative_delta" or "negative_count", the former for
  // regular histograms with integer counts, the latter for float
  // histograms.
  repeated sint64 negative_delta    = 10; // Count delta of each bucket compared to previous one (or to zero for 1st bucket).
  repeated double negative_count    = 11; // Absolute count of each bucket.

  // Positive buckets for the native histogram.
  // Use a no-op span (offset 0, length 0) for a native histogram without any
  // observations yet and with a zero_threshold of 0. Otherwise, it would be
  // indistinguishable from a classic histogram.
  repeated BucketSpan positive_span = 12;
  // Use either "positive_delta" or "positive_count", the former for
  // regular histograms with integer counts, the latter for float
  // histograms.
  repeated sint64 positive_delta    = 13; // Count delta of each bucket compared to previous one (or to zero for 1st bucket).
  repeated double positive_count    = 14; // Absolute count of each bucket.

  // Only used for native histograms. These exemplars MUST have a timestamp.
  repeated Exemplar exemplars = 16;
}

// A Bucket of a conventional histogram, each of which is treated as
// an individual counter-like time series by Prometheus.
message Bucket {
  optional uint64   cumulative_count       = 1; // Cumulative in increasing order.
  optional double   cumulative_count_float = 4; // Overrides cumulative_count if > 0.
  optional double   upper_bound            = 2; // Inclusive.
  optional Exemplar exemplar               = 3;
}

// A BucketSpan defines a number of consecutive buckets in a native
// histogram with their offset. Logically, it would be more
// straightforward to include the bucket counts in the Span. However,
// the protobuf representation is more compact in the way the data is
// structured here (with all the buckets in a single array separate
// from the Spans).
message BucketSpan {
  optional sint32 offset = 1; // Gap to previous span, or starting point for 1st span (which can be negative).
  optional uint32 length = 2; // Length of consecutive buckets.
}

message Exemplar {
  repeated LabelPair                 label     = 1;
  optional double                    value     = 2;
  optional google.protobuf.Timestamp timestamp = 3; // OpenMetrics-style.
}

message Metric {
  repeated LabelPair label        = 1;
  optional Gauge     gauge        = 2;
  optional Counter   counter      = 3;
  optional Summary   summary      = 4;
  optional Untyped   untyped      = 5;
  optional Histogram histogram    = 7;
  optional int64     timestamp_ms = 6;
}

message MetricFamily {
  optional string     name   = 1;
  optional string     help   = 2;
  optional MetricType type   = 3;
  repeated Metric     metric = 4;
  optional string     unit   = 5;
}