From b5d43fe61ca48476b74091d75fa8e2dcb45ed689 Mon Sep 17 00:00:00 2001 From: jmacd Date: Fri, 10 Apr 2020 11:22:49 -0700 Subject: [PATCH 01/10] Rationalize naming of metric instruments and their default aggregations --- text/0094-metric-instrument-terminology.md | 122 +++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 text/0094-metric-instrument-terminology.md diff --git a/text/0094-metric-instrument-terminology.md b/text/0094-metric-instrument-terminology.md new file mode 100644 index 000000000..194f29b3c --- /dev/null +++ b/text/0094-metric-instrument-terminology.md @@ -0,0 +1,122 @@ +# 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 explains this set of proposals. + +| Existing name | OTEP 93 name | Final name | Sync or Async | Default Aggregation | Rate support | +| ------------- | ------------------ | ------------------ | ----------- | ---------- | ---- | +| Counter | Counter | Counter | Sync | Sum | Yes | +| Measure | Distribution | Recorder | Sync | MinMaxSumCount | No | +| | UpDownCounter | UpDownCounter | Sync | Sum | Yes | +| | Timing | TimingRecorder | Sync | MinMaxSumCount | No | +| Observer | LastValueObserver | GaugeObserver | Async | MinMaxSumCount | No | +| | DeltaObserver | DeltaObserver | Async | Sum | Yes | +| | CumulativeObserver | CumulativeObserver | Async | Sum | 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. + +### 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 defintion, 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. From b351996e519529189fec7e830337027f3671a38c Mon Sep 17 00:00:00 2001 From: jmacd Date: Fri, 10 Apr 2020 11:23:58 -0700 Subject: [PATCH 02/10] Use more sync and async --- text/0094-metric-instrument-terminology.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/text/0094-metric-instrument-terminology.md b/text/0094-metric-instrument-terminology.md index 194f29b3c..5299c6a0a 100644 --- a/text/0094-metric-instrument-terminology.md +++ b/text/0094-metric-instrument-terminology.md @@ -49,7 +49,9 @@ Aggregator for each kind of instrument. ## Explanation -The following table explains this set of proposals. +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 | Default Aggregation | Rate support | | ------------- | ------------------ | ------------------ | ----------- | ---------- | ---- | From c651362cb82875014b235a7d8afe991cd9cf5f5f Mon Sep 17 00:00:00 2001 From: jmacd Date: Fri, 10 Apr 2020 11:26:37 -0700 Subject: [PATCH 03/10] Use bold for current proposed names --- text/0094-metric-instrument-terminology.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/text/0094-metric-instrument-terminology.md b/text/0094-metric-instrument-terminology.md index 5299c6a0a..4cb760900 100644 --- a/text/0094-metric-instrument-terminology.md +++ b/text/0094-metric-instrument-terminology.md @@ -53,15 +53,15 @@ 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 | Default Aggregation | Rate support | -| ------------- | ------------------ | ------------------ | ----------- | ---------- | ---- | -| Counter | Counter | Counter | Sync | Sum | Yes | -| Measure | Distribution | Recorder | Sync | MinMaxSumCount | No | -| | UpDownCounter | UpDownCounter | Sync | Sum | Yes | -| | Timing | TimingRecorder | Sync | MinMaxSumCount | No | -| Observer | LastValueObserver | GaugeObserver | Async | MinMaxSumCount | No | -| | DeltaObserver | DeltaObserver | Async | Sum | Yes | -| | CumulativeObserver | CumulativeObserver | Async | Sum | Yes | +| Existing name | OTEP 93 name | Final name | Sync or Async | Default aggregation | Rate support | +| ------------- | ------------------ | ---------------------- | ----------- | ---------- | ---- | +| Counter | Counter | **Counter** | Sync | Sum | Yes | +| Measure | Distribution | **Recorder** | Sync | MinMaxSumCount | No | +| | UpDownCounter | **UpDownCounter** | Sync | Sum | Yes | +| | Timing | **TimingRecorder** | Sync | MinMaxSumCount | No | +| Observer | LastValueObserver | **GaugeObserver** | Async | MinMaxSumCount | No | +| | DeltaObserver | **DeltaObserver** | Async | Sum | Yes | +| | CumulativeObserver | **CumulativeObserver** | Async | Sum | Yes | The argument for "Recorder" instead of "Distribution" is that we should prefer instrument descriptives associated with the action being From 99a3a4196554c6a54e685a94cea1ea01bedd14c0 Mon Sep 17 00:00:00 2001 From: jmacd Date: Fri, 10 Apr 2020 11:28:45 -0700 Subject: [PATCH 04/10] Reorder --- text/0094-metric-instrument-terminology.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0094-metric-instrument-terminology.md b/text/0094-metric-instrument-terminology.md index 4cb760900..dbe916fad 100644 --- a/text/0094-metric-instrument-terminology.md +++ b/text/0094-metric-instrument-terminology.md @@ -53,11 +53,11 @@ 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 | Default aggregation | Rate support | +| Existing name | OTEP 93 name | **Final name** | Sync or Async | Default aggregation | Rate support | | ------------- | ------------------ | ---------------------- | ----------- | ---------- | ---- | | Counter | Counter | **Counter** | Sync | Sum | Yes | -| Measure | Distribution | **Recorder** | Sync | MinMaxSumCount | No | | | UpDownCounter | **UpDownCounter** | Sync | Sum | Yes | +| Measure | Distribution | **Recorder** | Sync | MinMaxSumCount | No | | | Timing | **TimingRecorder** | Sync | MinMaxSumCount | No | | Observer | LastValueObserver | **GaugeObserver** | Async | MinMaxSumCount | No | | | DeltaObserver | **DeltaObserver** | Async | Sum | Yes | From 59a9f58b7d46c5021a78a45b417a87692d781ff3 Mon Sep 17 00:00:00 2001 From: jmacd Date: Fri, 10 Apr 2020 11:30:45 -0700 Subject: [PATCH 05/10] Typo --- ...ent-terminology.md => 0096-metric-instrument-terminology.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename text/{0094-metric-instrument-terminology.md => 0096-metric-instrument-terminology.md} (98%) diff --git a/text/0094-metric-instrument-terminology.md b/text/0096-metric-instrument-terminology.md similarity index 98% rename from text/0094-metric-instrument-terminology.md rename to text/0096-metric-instrument-terminology.md index dbe916fad..f184a1ef3 100644 --- a/text/0094-metric-instrument-terminology.md +++ b/text/0096-metric-instrument-terminology.md @@ -92,7 +92,7 @@ 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 defintion, more than only a sum. In this +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 From 6a8401eabf2d387afa72a9942ab77ba9b2f3e083 Mon Sep 17 00:00:00 2001 From: jmacd Date: Fri, 10 Apr 2020 13:00:48 -0700 Subject: [PATCH 06/10] Add depth on the instrument function names --- text/0096-metric-instrument-terminology.md | 47 +++++++++++++++++----- 1 file changed, 38 insertions(+), 9 deletions(-) diff --git a/text/0096-metric-instrument-terminology.md b/text/0096-metric-instrument-terminology.md index f184a1ef3..2da135016 100644 --- a/text/0096-metric-instrument-terminology.md +++ b/text/0096-metric-instrument-terminology.md @@ -53,15 +53,15 @@ 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 | Default aggregation | Rate support | -| ------------- | ------------------ | ---------------------- | ----------- | ---------- | ---- | -| Counter | Counter | **Counter** | Sync | Sum | Yes | -| | UpDownCounter | **UpDownCounter** | Sync | Sum | Yes | -| Measure | Distribution | **Recorder** | Sync | MinMaxSumCount | No | -| | Timing | **TimingRecorder** | Sync | MinMaxSumCount | No | -| Observer | LastValueObserver | **GaugeObserver** | Async | MinMaxSumCount | No | -| | DeltaObserver | **DeltaObserver** | Async | Sum | Yes | -| | CumulativeObserver | **CumulativeObserver** | Async | Sum | Yes | +| Existing name | OTEP 93 name | **Final name** | Sync or Async | Function | Default aggregation | Rate support | +| ------------- | ------------------ | ---------------------- | ----------- | ------------- | ---------- | ---- | +| Counter | Counter | **Counter** | Sync | Add() | Sum | Yes | +| | UpDownCounter | **UpDownCounter** | Sync | Add() | Sum | Yes | +| Measure | Distribution | **Recorder** | Sync | Record | MinMaxSumCount | No | +| | Timing | **TimingRecorder** | Sync | Record | MinMaxSumCount | No | +| Observer | LastValueObserver | **GaugeObserver** | Async | Observe | MinMaxSumCount | No | +| | DeltaObserver | **DeltaObserver** | Async | Observe | Sum | Yes | +| | CumulativeObserver | **CumulativeObserver** | Async | Observe | Sum | Yes | The argument for "Recorder" instead of "Distribution" is that we should prefer instrument descriptives associated with the action being @@ -78,6 +78,35 @@ 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 From 2641f6a497f18d91d4841b9e33987357e0a57271 Mon Sep 17 00:00:00 2001 From: jmacd Date: Fri, 10 Apr 2020 13:03:36 -0700 Subject: [PATCH 07/10] Formatting --- text/0096-metric-instrument-terminology.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/text/0096-metric-instrument-terminology.md b/text/0096-metric-instrument-terminology.md index 2da135016..247e18799 100644 --- a/text/0096-metric-instrument-terminology.md +++ b/text/0096-metric-instrument-terminology.md @@ -57,11 +57,11 @@ of this set of proposals. | ------------- | ------------------ | ---------------------- | ----------- | ------------- | ---------- | ---- | | Counter | Counter | **Counter** | Sync | Add() | Sum | Yes | | | UpDownCounter | **UpDownCounter** | Sync | Add() | Sum | Yes | -| Measure | Distribution | **Recorder** | Sync | Record | MinMaxSumCount | No | -| | Timing | **TimingRecorder** | Sync | Record | MinMaxSumCount | No | -| Observer | LastValueObserver | **GaugeObserver** | Async | Observe | MinMaxSumCount | No | -| | DeltaObserver | **DeltaObserver** | Async | Observe | Sum | Yes | -| | CumulativeObserver | **CumulativeObserver** | Async | Observe | Sum | Yes | +| Measure | Distribution | **Recorder** | Sync | Record() | MinMaxSumCount | No | +| | Timing | **TimingRecorder** | Sync | Record() | MinMaxSumCount | No | +| Observer | LastValueObserver | **GaugeObserver** | Async | Observe() | MinMaxSumCount | No | +| | DeltaObserver | **DeltaObserver** | Async | Observe() | Sum | Yes | +| | CumulativeObserver | **CumulativeObserver** | Async | Observe() | Sum | Yes | The argument for "Recorder" instead of "Distribution" is that we should prefer instrument descriptives associated with the action being From c9cd0d37c06d1c50e662f6eae76a8a2ef409a2c5 Mon Sep 17 00:00:00 2001 From: jmacd Date: Sat, 11 Apr 2020 20:18:32 -0700 Subject: [PATCH 08/10] UpDownCounter cannot Rate --- text/0096-metric-instrument-terminology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0096-metric-instrument-terminology.md b/text/0096-metric-instrument-terminology.md index 247e18799..27d5118ec 100644 --- a/text/0096-metric-instrument-terminology.md +++ b/text/0096-metric-instrument-terminology.md @@ -56,7 +56,7 @@ of this set of proposals. | Existing name | OTEP 93 name | **Final name** | Sync or Async | Function | Default aggregation | Rate support | | ------------- | ------------------ | ---------------------- | ----------- | ------------- | ---------- | ---- | | Counter | Counter | **Counter** | Sync | Add() | Sum | Yes | -| | UpDownCounter | **UpDownCounter** | Sync | Add() | Sum | Yes | +| | UpDownCounter | **UpDownCounter** | Sync | Add() | Sum | No | | Measure | Distribution | **Recorder** | Sync | Record() | MinMaxSumCount | No | | | Timing | **TimingRecorder** | Sync | Record() | MinMaxSumCount | No | | Observer | LastValueObserver | **GaugeObserver** | Async | Observe() | MinMaxSumCount | No | From 2f35be03e38439eaa070044eeb69c2f3c8c690cd Mon Sep 17 00:00:00 2001 From: jmacd Date: Mon, 13 Apr 2020 15:29:45 -0700 Subject: [PATCH 09/10] Add measurement kind column, same as 0093 --- text/0096-metric-instrument-terminology.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/text/0096-metric-instrument-terminology.md b/text/0096-metric-instrument-terminology.md index 27d5118ec..cbff23674 100644 --- a/text/0096-metric-instrument-terminology.md +++ b/text/0096-metric-instrument-terminology.md @@ -53,15 +53,15 @@ 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 | Rate support | +| Existing name | OTEP 93 name | **Final name** | Sync or Async | Function | Default aggregation | Measurement kind | Rate support | | ------------- | ------------------ | ---------------------- | ----------- | ------------- | ---------- | ---- | -| Counter | Counter | **Counter** | Sync | Add() | Sum | Yes | -| | UpDownCounter | **UpDownCounter** | Sync | Add() | Sum | No | -| Measure | Distribution | **Recorder** | Sync | Record() | MinMaxSumCount | No | -| | Timing | **TimingRecorder** | Sync | Record() | MinMaxSumCount | No | -| Observer | LastValueObserver | **GaugeObserver** | Async | Observe() | MinMaxSumCount | No | -| | DeltaObserver | **DeltaObserver** | Async | Observe() | Sum | Yes | -| | CumulativeObserver | **CumulativeObserver** | Async | Observe() | Sum | Yes | +| 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 From 376e164c62cac913a984fc80add047628b2f9719 Mon Sep 17 00:00:00 2001 From: jmacd Date: Mon, 13 Apr 2020 15:30:23 -0700 Subject: [PATCH 10/10] Formatting --- text/0096-metric-instrument-terminology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0096-metric-instrument-terminology.md b/text/0096-metric-instrument-terminology.md index cbff23674..25ea6a808 100644 --- a/text/0096-metric-instrument-terminology.md +++ b/text/0096-metric-instrument-terminology.md @@ -54,7 +54,7 @@ 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 |