visor/pkg/metric/metric.proto

// Copyright 2018 The gVisor 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 gvisor;

import "google/protobuf/timestamp.proto";

// MetricMetadata contains all of the metadata describing a single metric.
message MetricMetadata {
  // name is the unique name of the metric, usually in a "directory" format
  // (e.g., /foo/count).
  string name = 1;

  // prometheus_name is the unique name of the metric in Prometheus format
  // (e.g. foo_count).
  string prometheus_name = 9;

  // description is a human-readable description of the metric.
  string description = 2;

  // cumulative indicates that this metric is never decremented.
  // Only applies for uint64-type metrics.
  bool cumulative = 3;

  // sync indicates that values from the final metric event should be
  // synchronized to the backing monitoring system at exit.
  //
  // If sync is false, values are only sent to the monitoring system
  // periodically. There is no guarantee that values will ever be received by
  // the monitoring system.
  bool sync = 4;

  enum Type {
    TYPE_UINT64 = 0;
    TYPE_DISTRIBUTION = 1;
  }

  // type is the type of the metric value.
  Type type = 5;

  enum Units {
    UNITS_NONE = 0;
    UNITS_NANOSECONDS = 1;
  }

  // units is the units of the metric value.
  Units units = 6;

  message Field {
    string field_name = 1;
    repeated string allowed_values = 2;
  }

  // fields contains the metric fields for this metric.
  repeated Field fields = 7;

  // For distribution-typed metrics, this list contains the lower bound of all
  // buckets (other than the underflow bucket, which has no lower bound).
  // A distribution with n finite buckets should have n+1 values here.
  // The (n+1)-th value is the upper bound of the n-th bucket, and the lower
  // bound of the "overflow" bucket (which has no upper bound).
  repeated int64 distribution_bucket_lower_bounds = 8;
}

// MetricRegistration contains the metadata for all metrics that will be in
// future MetricUpdates.
message MetricRegistration {
  repeated MetricMetadata metrics = 1;
  repeated string stages = 2;
}

// Samples contains the number of samples in each bucket of a distribution.
message Samples {
  // new_samples contains the number of *new* samples in each bucket of a
  // distribution metric. "New" means the number of new samples added since the
  // last MetricValue update for this metric and combination of fields.
  // Given a distribution metrics with `num_finite_buckets` finite buckets,
  // this means:
  //   - num_samples[0] is the number of new samples in the "underflow" bucket,
  //     i.e. samples which are smaller than the lower bound of the
  //     distribution's first (0-th) finite bucket.
  //   - num_samples[i] is the number of new samples in the distribution's
  //     0-based (i-1)-th finite bucket.
  //   - num_samples[num_finite_buckets+1] is the number of new samples in the
  //     distribution's last bucket, which is infinite (i.e. it has a lower
  //     bound but no upper bound).
  repeated uint64 new_samples = 1;
}

// MetricValue the value of a metric at a single point in time.
message MetricValue {
  // name is the unique name of the metric, as in MetricMetadata.
  string name = 1;

  // value is the value of the metric at a single point in time. The field set
  // depends on the type of the metric.
  oneof value {
    uint64 uint64_value = 2;
    Samples distribution_value = 3;
  }

  repeated string field_values = 4;
}

// StageTiming represents a new stage that's been reached by the Sentry.
message StageTiming {
  string stage = 1;
  google.protobuf.Timestamp started = 2;
  google.protobuf.Timestamp ended = 3;
}

// MetricUpdate contains new values for multiple distinct metrics.
//
// Metrics whose values have not changed are not included.
message MetricUpdate {
  repeated MetricValue metrics = 1;
  // Timing information of initialization stages reached since last update.
  // The first MetricUpdate will include multiple entries, since metric
  // initialization happens relatively late in the Sentry startup process.
  repeated StageTiming stage_timing = 2;
}