forked from open-telemetry/opentelemetry-specification
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Metrics SDK spec skeleton (open-telemetry#1673)
* skeleton of metrics SDK spec * add more design questions * finish the skeleton * fix CI * add more links and clarification * nits * improve the wording for contex/baggage/trace interaction with metrics * fix typo * update the diagram to show logical in-memory state * update the diagram * update the wording * update the wording Co-authored-by: Sergey Kanzhelev <S.Kanzhelev@live.com>
- Loading branch information
1 parent
54eaaf0
commit c274dae
Showing
2 changed files
with
145 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,144 @@ | ||
| # Metrics SDK | ||
|
|
||
| **Status**: [Experimental](../document-status.md) | ||
|
|
||
| **Owner:** | ||
|
|
||
| * [Reiley Yang](https://github.com/reyang) | ||
|
|
||
| **Domain Experts:** | ||
|
|
||
| * [Bogdan Drutu](https://github.com/bogdandrutu) | ||
| * [Josh Suereth](https://github.com/jsuereth) | ||
| * [Joshua MacDonald](https://github.com/jmacd) | ||
|
|
||
| Note: this specification is subject to major changes. To avoid thrusting | ||
| language client maintainers, we don't recommend OpenTelemetry clients to start | ||
| the implementation unless explicitly communicated via | ||
| [OTEP](https://github.com/open-telemetry/oteps#opentelemetry-enhancement-proposal-otep). | ||
|
|
||
| <details> | ||
| <summary> | ||
| Table of Contents | ||
| </summary> | ||
|
|
||
| * [MeterProvider](#meterprovider) | ||
| * [MeasurementProcessor](#measurementprocessor) | ||
| * [MetricProcessor](#metricprocessor) | ||
| * [MetricExporter](#metricexporter) | ||
| * [Push Metric Exporter](#push-metric-exporter) | ||
| * [Pull Metric Exporter](#pull-metric-exporter) | ||
|
|
||
| </details> | ||
|
|
||
| ## MeterProvider | ||
|
|
||
| TODO: | ||
|
|
||
| * Allow multiple pipelines (processors, exporters). | ||
| * Configure "Views". | ||
| * Configure timing (related to [issue | ||
| 1432](https://github.com/open-telemetry/opentelemetry-specification/issues/1432)). | ||
|
|
||
| ## MeasurementProcessor | ||
|
|
||
| `MeasurementProcessor` is an interface which allows hooks when a | ||
| [Measurement](./api.md#measurement) is recorded by an | ||
| [Instrument](./api.md#instrument). | ||
|
|
||
| `MeasurementProcessor` MUST have access to: | ||
|
|
||
| * The `Measurement` | ||
| * The `Instrument`, which is used to report the `Measurement` | ||
| * The `Resource`, which is associated with the `MeterProvider` | ||
|
|
||
| In addition to things listed above, if the `Measurement` is reported by a | ||
| synchronous `Instrument` (e.g. [Counter](./api.md#counter)), | ||
| `MeasurementProcessor` MUST have access to: | ||
|
|
||
| * [Baggage](../baggage/api.md) | ||
| * [Context](../context/context.md) | ||
| * The [Span](../trace/api.md#span) which is associated with the `Measurement` | ||
|
|
||
| Depending on the programming language and runtime model, these can be provided | ||
| explicitly (e.g. as input arguments) or implicitly (e.g. [implicit | ||
| Context](../context/context.md#optional-global-operations) and the [currently | ||
| active span](../trace/api.md#context-interaction)). | ||
|
|
||
| ```text | ||
| +------------------+ | ||
| | MeterProvider | +----------------------+ +-----------------+ | ||
| | Meter A | Measurements... | | Metrics... | | | ||
| | Instrument X |-----------------> MeasurementProcessor +------------> In-memory state | | ||
| | Instrument Y + | | | | | ||
| | Meter B | +----------------------+ +-----------------+ | ||
| | Instrument Z | | ||
| | ... | +----------------------+ +-----------------+ | ||
| | ... | Measurements... | | Metrics... | | | ||
| | ... |-----------------> MeasurementProcessor +------------> In-memory state | | ||
| | ... | | | | | | ||
| | ... | +----------------------+ +-----------------+ | ||
| +------------------+ | ||
| ``` | ||
|
|
||
| ## MetricProcessor | ||
|
|
||
| `MetricProcessor` is an interface which allows hooks for [pre-aggregated metrics | ||
| data](./datamodel.md#timeseries-model). | ||
|
|
||
| Built-in metric processors are responsible for batching and conversion of | ||
| metrics data to exportable representation and passing batches to exporters. | ||
|
|
||
| The following diagram shows `MetricProcessor`'s relationship to other components | ||
| in the SDK: | ||
|
|
||
| ```text | ||
| +-----------------+ +-----------------+ +-----------------------+ | ||
| | | Metrics... | | Metrics... | | | ||
| > In-memory state | -----------> MetricProcessor | -----------> MetricExporter (push) |--> Another process | ||
| | | | | | | | ||
| +-----------------+ +-----------------+ +-----------------------+ | ||
| +-----------------+ +-----------------+ +-----------------------+ | ||
| | | Metrics... | | Metrics... | | | ||
| > In-memory state |------------> MetricProcessor |------------> MetricExporter (pull) |--> Another process (scraper) | ||
| | | | | | | | ||
| +-----------------+ +-----------------+ +-----------------------+ | ||
| ``` | ||
|
|
||
| ## MetricExporter | ||
|
|
||
| `MetricExporter` defines the interface that protocol-specific exporters must | ||
| implement so that they can be plugged into OpenTelemetry SDK and support sending | ||
| of telemetry data. | ||
|
|
||
| The goal of the interface is to minimize burden of implementation for | ||
| protocol-dependent telemetry exporters. The protocol exporter is expected to be | ||
| primarily a simple telemetry data encoder and transmitter. | ||
|
|
||
| Metric Exporter has access to the [pre-aggregated metrics | ||
| data](./datamodel.md#timeseries-model). | ||
|
|
||
| There could be multiple [Push Metric Exporters](#push-metric-exporter) or [Pull | ||
| Metric Exporters](#pull-metric-exporter) or even a mixture of both configured on | ||
| a given `MeterProvider`. Different exporters can run at different schedule, for | ||
| example: | ||
|
|
||
| * Exporter A is a push exporter which sends data every 1 minute. | ||
| * Exporter B is a push exporter which sends data every 5 seconds. | ||
| * Exporter C is a pull exporter which reacts to a scraper over HTTP. | ||
| * Exporter D is a pull exporter which reacts to another scraper over a named | ||
| pipe. | ||
|
|
||
| ### Push Metric Exporter | ||
|
|
||
| Push Metric Exporter sends the data on its own schedule. Here are some examples: | ||
|
|
||
| * Sends the data based on a user configured schedule, e.g. every 1 minute. | ||
| * Sends the data when there is a severe error. | ||
|
|
||
| ### Pull Metric Exporter | ||
|
|
||
| Pull Metric Exporter reacts to the metrics scrapers and reports the data | ||
| passively. This pattern has been widely adopted by | ||
| [Prometheus](https://prometheus.io/). |