diff --git a/text/0096-metric-instrument-terminology.md b/text/0096-metric-instrument-terminology.md new file mode 100644 index 000000000..25ea6a808 --- /dev/null +++ b/text/0096-metric-instrument-terminology.md @@ -0,0 +1,153 @@ +# Rationalize naming of metric instruments and their default aggregations + +Propose final names for the seven metric instruments introduced in [OTEP 93](https://github.com/open-telemetry/oteps/pull/93) and address related confusion. + +## Motivation + +[OTEP 88](https://github.com/open-telemetry/oteps/pull/88) introduced +a logical structure for metric instruments with two foundational +categories of instrument, called "synchronous" vs. "asynchronous", +named "Measure" and "Observer" in the abstract. This proposal +identified four kinds of "refinement" and mapped out the space of +_possible_ instruments, while not proposing which would actually be +included in the standard. + +[OTEP 93](https://github.com/open-telemetry/oteps/pull/93) followed +with a list of six standard instruments, the most necessary and useful +combination of instrument refinements, plus one special case used to +record timing measurements. + +This proposal finalizes the names used to describe the seven +instruments above, seeking to address core confusion related to +"Measure": + +1. OTEP 88 stipulates that the terms currently in use to name +synchronous and asynchronous instruments become abstract, but also +using "Measure-like" and "Observer-like" to discuss instruments with +refinements. This proposal states that we shall prefer the +adjectives, commonly abbreviated "Sync" and "Async", when describing +instruments. +2. Prior to OTEP 88, but even with OTEPs 88 and 93 included, there is +inconsistency in the naming of instruments. Note that "Counter" and +"Observer" end in "-er", a noun suffix used in the sense of "[person +occupationally connected +with](https://www.merriam-webster.com/dictionary/-er)", while the term +"Measure" does not fit this pattern. This proposal proposes to +replace the abstract term "Measure" by "Recorder", since the +associated method name (verb) is specified as `Record()`. +3. The OTEP 93 asynchronous instruments ("LastValueObserver", +"DeltaObserver", and "CumulativeObserver") have the pattern +"-Observer", while the OTEP 93 synchronous instruments +("Counter", "UpDownCounter", "Distribution", "Timing") do not. This +proposal keeps "Counter" and "UpDownCounter" for Sum-only synchronous instruments, and does the same +with "Recorder", yielding "Recorder" and "TimingRecorder". +4. Confusion over the loss of "Gauge" is addressed by replacing +"LastValueObserver" with "GaugeObserver". + +This proposal also repeats the current specification of the default +Aggregator for each kind of instrument. + +## Explanation + +The following table summarizes the four synchronous instruments and +three asynchronous instruments that will be standardized as a result +of this set of proposals. + +| Existing name | OTEP 93 name | **Final name** | Sync or Async | Function | Default aggregation | Measurement kind | Rate support | +| ------------- | ------------------ | ---------------------- | ----------- | ------------- | ---------- | ---- | --- | +| Counter | Counter | **Counter** | Sync | Add() | Sum | Delta | Yes | +| | UpDownCounter | **UpDownCounter** | Sync | Add() | Sum | Delta | No | +| Measure | Distribution | **Recorder** | Sync | Record() | MinMaxSumCount | Instantaneous | No | +| | Timing | **TimingRecorder** | Sync | Record() | MinMaxSumCount | Instantaneous | No | +| Observer | LastValueObserver | **GaugeObserver** | Async | Observe() | MinMaxSumCount | Instantaneous | No | +| | DeltaObserver | **DeltaObserver** | Async | Observe() | Sum | Delta | Yes | +| | CumulativeObserver | **CumulativeObserver** | Async | Observe() | Sum | Cumulative | Yes | + +The argument for "Recorder" instead of "Distribution" is that we +should prefer instrument descriptives associated with the action being +performed ("occupationally connected"), not the value being computed, +as the latter is dependent on SDK configuration. A "Recorder" records +a value that is part of a distribution. A "Counter" counts a value +that is part of a sum. An "GaugeObserver" observes an instantaneous +value ("reads a gauge"). A "Recorder" records an arbitrary value. A +"TimingRecorder" records a timing value, and so on. + +## Details + +This proposal consolidates OTEP 88 and OTEP 93 and proposes a consistent +pattern for naming instruments. It will be the source of truth when +applying OTEP 88 and OTEP 93 to the OpenTelemetry metrics specification. + +### Function names + +The function names of the standard instruments are determined as +follows. + +#### Counter and UpDownCounter + +Counter and UpDownCounter instruments use `Add()` as the function +name, since they capture deltas to a Sum-only instrument. We prefer +`Add()` as opposed to `Count()`, since floating point numbers are +supported, to avoid some an association with "Countable" numbers, a +mathemtical term associated with natural numbers. + +#### Recorder and TimingRecorder + +Recorder and TimingRecorder use `Record()` as the function name, as in +the existing specification for Measure instruments. This conveys the +fact that these are not a sum, and that individual events are of +importance. + +#### Asynchronous instruments + +Asynchronous instruments use `Observe()` as the function name. This +signifies that the instrument passively captures a measurement, is not +an active participant, as implied by `Record()`. _Observation_ also +conveys the last-value relationship specified for asynchronous +instruments. The observer can only observe one value at a time, where +the last-observed value wins. + +### Default aggregations + +This [OTEP 93 +conversation](https://github.com/open-telemetry/oteps/pull/93#discussion_r405852507) +raised a question about the default aggregation for GaugeObserver, +given as MinMaxSumCount. Would "Sum" be a more appropriate default? + +Note that the distinction between whether the default aggregation is +"Sum" or "MinMaxSumCount" corresponds exactly to whether the +instrument has the Sum-only refinement. "Sum" is the default +aggregation for any Sum-only instrument since, by definition, the +Sum aggregation provides complete information. + +The three instruments with a default "MinMaxSumCount" are all used to +record a value that is, by definition, more than only a sum. In this +case, "complete information" requires recording every value, i.e., no +aggregation. MinMaxSumCount is applied in these cases because it +provides the maximum amount of information that can be recorded using +a fixed number of values, per time series, per collection interval. + +### GaugeObserver aggregation + +Why should GaugeObserver aggregate the Min, Max, Sum, and Count when +it is permitted to observe just one measurement per interval? This +says that when observed values are aggregated they should be treated +like a distribution--we are intersted in more than a sum, by +definition. If observing only a sum, the DeltaObserver or +CumulativeObserver should be used instead. + +Clearly, when Count equals 1, the Min, Max, and Sum are equal to the +value. Exporters may be able take advantage of this fact when +exporting data from these instruments. In particular, since it is +known that asynchronous instruments produce only one valiue per +interval (with last-value-wins semantics), when we know in the SDK +that no spatial aggregation is configured, we can be sure that Count +equals one, and we can use the most appropriate exposition format for +the target system. + +This means Prometheus and Statsd exporters SHOULD export Gauge values +for the GaugeObserver when there is no spatial aggregation being +applied, because that is the natural exposition format for +MinMaxSumCount aggregations when Count equals 1. If there is spatial +aggregation being applied, the default MinMaxSumCount aggregation +still applies.