Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Metric SDK specification OUTLINE #347

Merged
merged 36 commits into from
Aug 20, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
36 commits
Select commit Hold shift + click to select a range
c10ba0e
WIP: Metric SDK specification
jmacd Nov 12, 2019
bfda24a
Updates following Tigran's feedback
jmacd Nov 12, 2019
b04e927
More rewording
jmacd Nov 12, 2019
401292b
Strengthen requirements for aggregators
jmacd Nov 13, 2019
6990089
Fix typos noted by MrAlias
jmacd Nov 13, 2019
077141b
Address some of freeformzSFDC's feedback
jmacd Nov 14, 2019
1542a43
Upstream
jmacd Dec 13, 2019
3cb05a4
Capitalization
jmacd Dec 16, 2019
7e785de
Respond to feedback
jmacd Dec 17, 2019
35dff70
Respond to feedback
jmacd Dec 17, 2019
9d40730
Handle->Bound instrument
jmacd Dec 18, 2019
3ec4e00
New img
jmacd Dec 21, 2019
6f3fbdb
New img ref
jmacd Dec 21, 2019
8692b24
Update image
jmacd Dec 23, 2019
2b75442
Rename to Differentiator/Integrator
jmacd Dec 23, 2019
7be3138
Remove reference to defaultkeys batcher
jmacd Apr 14, 2020
f9866aa
Batcher->Integrator
jmacd Apr 14, 2020
931bd8c
Differentiator->Accumulator
jmacd Apr 14, 2020
535fc0e
Upstrema
jmacd May 26, 2020
4405845
Upstream
jmacd May 26, 2020
f358adf
Move the image
jmacd May 26, 2020
1fc3ec1
Update image
jmacd May 26, 2020
64bbb0c
Simplify the diagram
jmacd May 27, 2020
7063963
Upstream
jmacd Aug 11, 2020
8929123
Remove much dead code
jmacd Aug 19, 2020
b36917a
Remove more dead code
jmacd Aug 19, 2020
f698d3c
Lint
jmacd Aug 19, 2020
16a317b
Upstream
jmacd Aug 19, 2020
53d4418
Ignore
jmacd Aug 19, 2020
4857098
Rename metrics SDK
jmacd Aug 19, 2020
023838d
Bold
jmacd Aug 19, 2020
80d0b9a
CheckpointSet -> ExportRecordSet
jmacd Aug 19, 2020
80c16b2
Update diagram
jmacd Aug 20, 2020
d5a7162
Update diagram (png)
jmacd Aug 20, 2020
5c1700a
Editing
jmacd Aug 20, 2020
6aa3683
Undo
jmacd Aug 20, 2020
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Binary file added specification/metrics/img/metrics-sdk.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
74 changes: 74 additions & 0 deletions specification/metrics/sdk.md
Original file line number Diff line number Diff line change
@@ -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
jmacd marked this conversation as resolved.
Show resolved Hide resolved
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.
jmacd marked this conversation as resolved.
Show resolved Hide resolved

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