diff --git a/terminology.md b/terminology.md index 57eb62c1d53..8060f476266 100644 --- a/terminology.md +++ b/terminology.md @@ -104,7 +104,82 @@ Trace instead of trusting incoming Trace context. ## Metrics -TODO: Describe metrics terminology https://github.com/open-telemetry/opentelemetry-specification/issues/45 +OpenTelemetry allows to record raw measurements or metrics with predefined +aggregation and set of labels. + +Recording raw measurements using OpenTelemetry API allows to defer to end-user +the decision on what aggregation algorithm should be applied for this metric as +well as defining labels (dimensions). It will be used in client libraries like +gRPC to record raw measurements "server_latency" or "received_bytes". So end +user will decide what type of aggregated values should be collected out of these +raw measurements. It may be simple average or elaborate histogram calculation. + +Recording of metrics with the pre-defined aggregation using OpenTelemtry API is +not less important. It allows to collect values like cpu and memory usage, or +simple metrics like "queue length". + +### Recording raw measurements + +The main classes used to record raw measurements are `Measure` and +`Measurement`. List of `Measurement`s alongside the additional context can be +recorded using OpenTelemetry API. So user may define to aggregate those +`Measurement`s and use the context passed alongside to define additional +dimensions of the resulting metric. + +#### Measure + +`Measure` describes the type of the individual values recorded by a library. It +defines a contract between the library exposing the measurements and an +application that will aggregate those individual measurements into a `Metric`. +`Measure` is identified by name, description and a unit of values. + +#### Measurement + +`Measurement` describes a single value to be collected for a `Measure`. +`Measurement` is an empty interface in API surface. This interface is defined in +SDK. + +### Recording metrics with predefined aggregation + +The base class for all types of pre-aggregated metrics is called `Metric`. It +defines basic metric properties like a name and labels. Classes inheriting from +the `Metric` define their aggregation type as well as a structure of individual +measurements or Points. API defines the following types of pre-aggregated +metrics: + +- Counter metric to report instantaneous measurement. Counter values can go + up or stay the same, but can never go down. Counter values cannot be + negative. There are two types of counter metric values - `double` and `long`. +- Gauge metric to report instantaneous measurement of a double value. Gauges can + go both up and down. The gauges values can be negative. There are two types of + gauge metric values - `double` and `long`. + +API allows to construct the `Metric` of a chosen type. SDK defines the way to +query the current value of a `Metric` to be exported. + +Every type of a `Metric` has it's API to record values to be aggregated. API +supports both - push and pull model of setting the `Metric` value. + +### Metrics data model and SDK + +Metrics data model is defined in SDK and is based on +[metrics.proto](https://github.com/open-telemetry/opentelemetry-proto/blob/master/src/opentelemetry/proto/metrics/v1/metrics.proto). +This data model is used by all the OpenTelemetry exporters as an input. +Different exporters have different capabilities (e.g. which data types are +supported) and different constraints (e.g. which characters are allowed in label +keys). Metrics is intended to be a superset of what's possible, not a lowest +common denominator that's supported everywhere. All exporters consume data from +Metrics Data Model via a Metric Producer interface defined in OpenTelemetry SDK. + +Because of this, Metrics puts minimal constraints on the data (e.g. which +characters are allowed in keys), and code dealing with Metrics should avoid +validation and sanitization of the Metrics data. Instead, pass the data to the +backend, rely on the backend to perform validation, and pass back any errors +from the backend. + +OpenTelemetry defines the naming convention for metric names as well as a +well-known metric names in [Semantic Conventions](semantic-conventions.md) +document. ## DistributedContext diff --git a/work_in_progress/specification/metrics/Metrics.md b/work_in_progress/specification/metrics/Metrics.md deleted file mode 100644 index 307cb30cfec..00000000000 --- a/work_in_progress/specification/metrics/Metrics.md +++ /dev/null @@ -1,21 +0,0 @@ -# Metrics -Metrics are a data model for what stats exporters take as input. - -Different exporters have different capabilities (e.g. which data types -are supported) and different constraints (e.g. which characters are allowed in -label keys). Metrics is intended to be a superset of what's possible, not a -lowest common denominator that's supported everywhere. - -Because of this, Metrics puts minimal constraints on the data (e.g. which -characters are allowed in keys), and code dealing with Metrics should avoid -validation and sanitization of the Metrics data. Instead, pass the data to the -backend, rely on the backend to perform validation, and pass back any errors -from the backend. - -The Metrics data model is defined as -[metrics.proto](https://github.com/census-instrumentation/opencensus-proto/blob/master/src/opencensus/proto/metrics/v1/metrics.proto), -but the proto is just to illustrate the concepts. OpenCensus implementations -don't have to use the actual proto, and can instead use a language-specific -in-memory data structure that captures what exporters need. This structure -should use the names and fields from the data model, for API consistency across -languages. diff --git a/work_in_progress/specification/metrics/README.md b/work_in_progress/specification/metrics/README.md deleted file mode 100644 index e186e160450..00000000000 --- a/work_in_progress/specification/metrics/README.md +++ /dev/null @@ -1,8 +0,0 @@ -# OpenCensus Library Metrics Package -This documentation serves to document the "look and feel" of the open source metrics package. It -describes the key types and the overall behavior. - -Note: This is an experimental package and is likely to get backwards-incompatible updates in the future. - -## Main APIs -* [Metrics Data Model](Metrics.md): defines the metrics data model.