From 90c5d3a202e2c8e8a392e94b1106236e3bb9e087 Mon Sep 17 00:00:00 2001 From: jmacd Date: Thu, 12 Sep 2019 17:06:05 -0700 Subject: [PATCH 1/4] Rename Cumulative to Counter --- text/0000-cumulative-to-counter.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 text/0000-cumulative-to-counter.md diff --git a/text/0000-cumulative-to-counter.md b/text/0000-cumulative-to-counter.md new file mode 100644 index 000000000..9a101359f --- /dev/null +++ b/text/0000-cumulative-to-counter.md @@ -0,0 +1,23 @@ +# Rename "Cumulative" to "Counter" in the metrics API + +**Status:** `proposed` + +Prefer the name "Counter" as oppose to "Cumulative". + +## Motivation + +Informally speaking, it seems that OpenTelemetry community members would prefer to call Cumulative metric instruments "Counters". During conversation (e.g., in the 8/21 working session), this has become clear. + +Counter is a noun, like the other kinds Gauge and Measure. Cumulative is an adjective, so while "Cumulative instrument" makes sense, it describes a "Counter". + +## Explanation + +This will eliminate the cognitive cost of mapping "cumulative" to "counter" when speaking about these APIs. + +## Internal details + +Simply replace every "Cumulative" with "Counter", then edit for grammar. + +## Prior art and alternatives + +In a survey of existing metrics libraries, Counter is far more common. From 3b39cb8eaf8739e0243f719dda02621cdabf9b73 Mon Sep 17 00:00:00 2001 From: jmacd Date: Thu, 12 Sep 2019 17:06:55 -0700 Subject: [PATCH 2/4] Reword that --- text/0000-cumulative-to-counter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-cumulative-to-counter.md b/text/0000-cumulative-to-counter.md index 9a101359f..04703d139 100644 --- a/text/0000-cumulative-to-counter.md +++ b/text/0000-cumulative-to-counter.md @@ -12,7 +12,7 @@ Counter is a noun, like the other kinds Gauge and Measure. Cumulative is an adj ## Explanation -This will eliminate the cognitive cost of mapping "cumulative" to "counter" when speaking about these APIs. +This will eliminate the cognitive cost of mapping "counter" to "cumulative" when speaking about these APIs. ## Internal details From c5db879389b9fe6158b2ef39c2782f4e43e07b63 Mon Sep 17 00:00:00 2001 From: jmacd Date: Fri, 13 Sep 2019 09:55:05 -0700 Subject: [PATCH 3/4] More explanation and caveats --- text/0000-cumulative-to-counter.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/text/0000-cumulative-to-counter.md b/text/0000-cumulative-to-counter.md index 04703d139..114096bf4 100644 --- a/text/0000-cumulative-to-counter.md +++ b/text/0000-cumulative-to-counter.md @@ -2,7 +2,7 @@ **Status:** `proposed` -Prefer the name "Counter" as oppose to "Cumulative". +Prefer the name "Counter" as opposed to "Cumulative". ## Motivation @@ -12,7 +12,30 @@ Counter is a noun, like the other kinds Gauge and Measure. Cumulative is an adj ## Explanation -This will eliminate the cognitive cost of mapping "counter" to "cumulative" when speaking about these APIs. +This will eliminate the cognitive cost of mapping "cumulative" to "counter" when speaking about these APIs. + +This is the term used for a cumulative metric instrument, for example, in [Statsd](https://github.com/statsd/statsd/blob/master/docs/metric_types.md) and [Prometheus](https://prometheus.io/docs/concepts/metric_types/#counter). + +However, we have identified important sub-cases of Counter that are treated as follows. Counters have an option: + +- True-cumulative Counter: By default, `Add()` arguments must be >= 0. +- Bi-directional Counter: As an option, `Add()` arguments must be +/-0. + +Gauges are sometimes used to monitoring non-descending quantities (e.g., cpu usage), as an option: + +- Bi-directional Gauge: By default, `Set()` arguments may by +/- 0. +- Uni-directional Gauge: As an option, `Set()` arguments must change by >= 0. + +Uni-directional Gauge instruments are typically used in metric `Observer` callbacks where the observed value is cumulative. + +## Trade-offs and mitigations + +Other ways to describe the distinction between true-cumulative and bi-directional Counters are: + +- Additive (vs Cumulative) +- GaugeDelta + +It is possible that reducing all of these cases into the broad term "Counter" creates more confusion than it addresses. ## Internal details From 43f9305c3f3edae820b372d5523f6fab14c2bc93 Mon Sep 17 00:00:00 2001 From: jmacd Date: Fri, 13 Sep 2019 09:57:09 -0700 Subject: [PATCH 4/4] More explanation and caveats --- text/0000-cumulative-to-counter.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-cumulative-to-counter.md b/text/0000-cumulative-to-counter.md index 114096bf4..92d1f0a7a 100644 --- a/text/0000-cumulative-to-counter.md +++ b/text/0000-cumulative-to-counter.md @@ -32,8 +32,8 @@ Uni-directional Gauge instruments are typically used in metric `Observer` callba Other ways to describe the distinction between true-cumulative and bi-directional Counters are: -- Additive (vs Cumulative) -- GaugeDelta +- Additive (vs. Cumulative) +- GaugeDelta (vs. Gauge) It is possible that reducing all of these cases into the broad term "Counter" creates more confusion than it addresses.