This repository has been archived by the owner on Dec 6, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 164
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Metrics API: Rename Cumulative to Counter (#47)
* Rename Cumulative to Counter * Reword that * More explanation and caveats * More explanation and caveats
- Loading branch information
1 parent
b5011e2
commit 969a99c
Showing
1 changed file
with
46 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,46 @@ | ||
# Rename "Cumulative" to "Counter" in the metrics API | ||
|
||
**Status:** `proposed` | ||
|
||
Prefer the name "Counter" as opposed 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. | ||
|
||
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 (vs. Gauge) | ||
|
||
It is possible that reducing all of these cases into the broad term "Counter" creates more confusion than it addresses. | ||
|
||
## 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. |