diff --git a/opentelemetry/proto/metrics/v1/metrics.proto b/opentelemetry/proto/metrics/v1/metrics.proto index b53a441d4..d4275a907 100644 --- a/opentelemetry/proto/metrics/v1/metrics.proto +++ b/opentelemetry/proto/metrics/v1/metrics.proto @@ -46,20 +46,24 @@ message InstrumentationLibraryMetrics { // Defines a Metric which has one or more timeseries. // -// The data model and relation between entities is shown in the diagram below. +// The data model and relation between entities is shown in the +// diagram below. Here, "DataPoint" is the term used to refer to any +// one of the specific data point kinds, and "points" is the term use +// to refer to any one of the lists of points contained in the Metric. // // - 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. +// - MetricDescriptor contains a name, description, unit, type, and temporarility. +// - Points is a list of DataPoints (shown vertically). +// - DataPoint contains timestamps, labels, and one of the possible value type fields. // // Metric // +----------+ +------------------------+ // |descriptor|-------->| MetricDescriptor | -// | | |+-----+-----+ +-----+ | -// | | ||label|label|...|label| | -// | data|--+ ||key1 |key2 | |keyN | | -// +----------+ | |+-----+-----+ +-----+ | +// | | | name | +// | | | description | +// | | | unit | +// | points|--+ | type | +// +----------+ | | temporarility | // | +------------------------+ // | // | +---------------------------+ @@ -86,13 +90,15 @@ message InstrumentationLibraryMetrics { // |+-----+ | // +---------------------------+ // -//----------------------------------------------------------------------- -// 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. +// All DataPoint types have includes three common fields: +// - Labels are the optional key-value pairs associated with the data point. +// - StartTimeUnixNano MUST be set to the start of the interval when the +// descriptor kind includes CUMULATIVE or DELTA. This field is not set +// for INSTANTANEOUS timeseries, where instead the TimeUnixNano field is +// set for individual points. +// - TimeUnixNano MUST be set to: +// - the end of the interval (CUMULATIVE or DELTA) +// - the instantaneous time of the event (INSTANTANEOUS). message Metric { // metric_descriptor describes the Metric. MetricDescriptor metric_descriptor = 1;