diff --git a/README.md b/README.md index 8cfcc7dee1e..2c741071259 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ The OpenTelemetry specification describes the cross-language requirements and ex - [Metrics](specification/metrics/api.md) - SDK Specification - [Tracing](specification/trace/sdk.md) + - [Metrics](specification/metrics/sdk.md) - [Resource](specification/resource/sdk.md) - [Configuration](specification/sdk-configuration.md) - Data Specification diff --git a/specification/metrics/img/metrics-sdk.png b/specification/metrics/img/metrics-sdk.png new file mode 100644 index 00000000000..712292d626c Binary files /dev/null and b/specification/metrics/img/metrics-sdk.png differ diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md new file mode 100644 index 00000000000..318c76e60af --- /dev/null +++ b/specification/metrics/sdk.md @@ -0,0 +1,74 @@ +# Metrics SDK + +Note: This document assumes you are familiar with the (Metrics +API)[api.md] specification. + +TODO: TOC + +## Purpose + +This document describes a model implementation of the OpenTelemetry +Metrics SDK. The architectural details of the model SDK described +here are meant to offer guidance to implementors, not to mandate an +exact reproduction of the model architecture across languages. + +## Expectations + +The SDK implementors are expected to follow the best practices for the +language and runtime environment when implementing the OpenTelemetry +API. Implementors SHOULD follow the general prescriptions on safety +and performance given in [OpenTelemetry library +guidelines](../library-guidelines.md). + +## Export Pipeline Terminology + +**Export Pipeline** is used to describe a whole assembly of SDK parts. +There are three major components of the Metrics SDK that data flows +through, in order: + +1. **Accumulator**: Receives metric events from the API, computes one Accumulation per active Instrument and Label Set pair +2. **Processor**: Receives Accumulations from the Accumulator, transforms into ExportRecordSet +3. **Exporter**: Receives ExportRecordSet, transforms into some protocol and sends it somewhere. + +These terms are defined in the Metrics API specification: + +- **Metric Instrument**: the API object used by a developer for instrumentation +- **Synchronous Instrument**: a metric instrument called by the user with application context +- **Asynchronous Instrument**: a metric instrument invoked through a callback from the SDK +- **Metric Descriptor**: describes a metric instrument +- **Metric Event**: a single recorded or observed (Instrument, Label Set, Measurement) +- **Collection Interval**: the period between calls to Accumulator.Collect() +- **Label**: a key-value describing a property of the metric event +- **Label Set**: a set of key-values with unique keys +- **Measurement**: an integer or floating point number. + +Defined in the [Resource SDK](../resource/sdk.md) specification: + +- **Resource**: a set of key-values with unique keys describing the process. + +These are the significant data types used in the model architecture: + +- **Aggregator**: aggregates one or more measurements in a useful way +- **AggregatorSelector**: chooses which Aggregator to assign to a metric instrument +- **Aggregation**: the result of aggregating one or more events by a specific aggregator +- **AggregationKind**: describes the kind of read API the Aggregation supports (e.g., Sum) +- **Accumulation**: consists of Instrument, Label Set, Resource, and Aggregator snapshot +- **ExportRecordSet**: a set of export records +- **Controller**: coordinates the Accumulator, Processor, and Exporter components in an export pipeline +- **Export Record**: consists of Instrument, Label Set, Resource, Timestamp(s), and Aggregation +- **ExportKind**: one of Delta, Cumulative, or Pass-Through +- **ExportKindSelector**: chooses which ExportKind to use for a metric instrument. + +## Dataflow Diagram + +![Metrics SDK Design Diagram](img/metrics-sdk.png) + +## Accumulator Detail + +## Controller Detail + +## Basic Processor Detail + +## Reducing Processor Detail + +## Aggregator Implementations