Skip to content

Commit

Permalink
aggregation -> aggregator, other small changes
Browse files Browse the repository at this point in the history
  • Loading branch information
cnnradams committed Jun 11, 2020
1 parent 8bb0d55 commit ab60d38
Showing 1 changed file with 10 additions and 10 deletions.
20 changes: 10 additions & 10 deletions text/metrics/0113-exemplars.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Exemplars are meaningful for all aggregations where relevant traces can provide

## Internal details

An exemplar is defined as:
An exemplar is a `RawValue`, which is defined as:

```
message RawValue {
Expand All @@ -43,27 +43,27 @@ message RawValue {
}
```

Exemplar collection should be enabled through an optional parameter (disabled by default), and when not enabled, there should be no collection/logic performed related to exemplars. This is to ensure that when necessary, aggregations are as high performance as possible. Aggregations should also have a parameter to determine whether exemplars should only be collected if they are recorded during a sampled trace, or if tracing should have no effect on which exemplars are sampled. This allows aggregations to prioritize either the link between metrics and traces or the statistical significance of exemplars, when necessary.
Exemplar collection should be enabled through an optional parameter (disabled by default), and when not enabled, there should be no collection/logic performed related to exemplars. This is to ensure that when necessary, aggregators are as high performance as possible. Aggregators should also have a parameter to determine whether exemplars should only be collected if they are recorded during a sampled trace, or if tracing should have no effect on which exemplars are sampled. This allows aggregations to prioritize either the link between metrics and traces or the statistical significance of exemplars, when necessary.

[#347](https://github.com/open-telemetry/opentelemetry-specification/pull/347) describes a set of standard aggregations in the metrics SDK. Here we describe how exemplars could be implemented for each aggregation.
[#347](https://github.com/open-telemetry/opentelemetry-specification/pull/347) describes a set of standard aggregators in the metrics SDK. Here we describe how exemplars could be implemented for each aggregator.

### Exemplar behaviour for standard aggregations
### Exemplar behaviour for standard aggregators

#### HistogramAggregator

The HistogramAggregator MUST (when enabled) maintain a list of exemplars whose values are distributed across all buckets of the histogram (there should be one or more exemplars in every bucket that has a population of at least one sample-able measurement). Implementations SHOULD NOT retain an unbounded number of exemplars.

#### Sketch

A Sketch aggregation SHOULD maintain a list of exemplars whose values are spaced out across the distribution. There is no specific number of exemplars that should be retained (although the amount SHOULD NOT be unbounded), but the implementation SHOULD pick exemplars that represent as much of the distribution as possible. (Specific details not defined, see open questions.)
A Sketch aggregator SHOULD maintain a list of exemplars whose values are spaced out across the distribution. There is no specific number of exemplars that should be retained (although the amount SHOULD NOT be unbounded), but the implementation SHOULD pick exemplars that represent as much of the distribution as possible. (Specific details not defined, see open questions.)

#### Last-Value

Most (if not all) Gauges operate asynchronously and do not ever interact with traces. Since the value of a Gauge is the last measurement (essentially the other parts of an exemplar), exemplars are not worth implementing for Gauge.
Most (if not all) Last-Value aggregators operate asynchronously and do not ever interact with context. Since the value of a Last-Value is the last measurement (essentially the other parts of an exemplar), exemplars are not worth implementing for Gauge.

#### Exact

The Exact aggregation will function by maintaining a list of `RawValue`s, which contain all of the information exemplars would carry. Therefore the Exact aggregation will not need to maintain any exemplars.
The Exact aggregator will function by maintaining a list of `RawValue`s, which contain all of the information exemplars would carry. Therefore the Exact aggregator will not need to maintain any exemplars.

#### Counter

Expand All @@ -73,17 +73,17 @@ Exemplars give value to counter aggregations in two ways: One, by tying metric a

Similar to Counter, MinMaxSumCount should retain a bounded list of exemplars that were sampled from across the input distribution in a statistically significant way.

#### Custom Aggregations
#### Custom Aggregators

Custom aggregations MAY support exemplars by maintaining a list of exemplars that can be retrieved by exporters. Custom aggregations should select exemplars based on their usage by the connected exporter (for example, exemplars recorded for Stackdriver should only be retained if they were recorded within a sampled trace).
Custom aggregators MAY support exemplars by maintaining a list of exemplars that can be retrieved by exporters. Custom aggregators should select exemplars based on their usage by the connected exporter (for example, exemplars recorded for Stackdriver should only be retained if they were recorded within a sampled trace).

Exemplars will always be retrieved from aggregations (by the exporter) as a list of RawValue objects. They will be communicated via a

```
optional repeated RawValue exemplars = 6
```

attribute on the `metric_descriptor` object.
attribute on the `Metric` object.

## Trade-offs and mitigations

Expand Down

0 comments on commit ab60d38

Please sign in to comment.