From 2caaafdc5fb0527f86c6078407b05796568438dd Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 13 Jun 2023 11:30:44 -0700 Subject: [PATCH 1/5] .count metric naming convention only applies to UpDownCounters --- CHANGELOG.md | 3 +++ .../metrics/semantic_conventions/README.md | 21 +++++++++++++++++-- 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 73f7e9a753..3455152fee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -80,3 +80,6 @@ release. ([#70](https://github.com/open-telemetry/semantic-conventions/pull/70)) - Clarify that OTEL_SEMCONV_STABILITY_OPT_IN is a comma-separated list of values ([#104](https://github.com/open-telemetry/semantic-conventions/pull/104)) +- Update `.count` metric naming convention so that it only applies to UpDownCounters, + and add that `.total` should not be used by either Counters or UpDownCounters + ([#107](https://github.com/open-telemetry/opentelemetry-specification/pull/107)) diff --git a/specification/metrics/semantic_conventions/README.md b/specification/metrics/semantic_conventions/README.md index 5c33d27ec2..d5d727cfad 100644 --- a/specification/metrics/semantic_conventions/README.md +++ b/specification/metrics/semantic_conventions/README.md @@ -13,7 +13,8 @@ linkTitle: Semantic Conventions * [Name Reuse Prohibition](#name-reuse-prohibition) * [Units](#units) * [Pluralization](#pluralization) - + [Use `count` Instead of Pluralization](#use-count-instead-of-pluralization) + + [Use `count` Instead of Pluralization for UpDownCounters](#use-count-instead-of-pluralization-for-updowncounters) + + [Do not use `total`](#do-not-use-total) - [General Metric Semantic Conventions](#general-metric-semantic-conventions) * [Instrument Naming](#instrument-naming) * [Instrument Units](#instrument-units) @@ -114,7 +115,7 @@ should not be pluralized, even if many data points are recorded. * `system.paging.faults`, `system.disk.operations`, and `system.network.packets` should be pluralized, even if only a single data point is recorded. -#### Use `count` Instead of Pluralization +#### Use `count` Instead of Pluralization for UpDownCounters If the value being recorded represents the count of concepts signified by the namespace then the metric should be named `count` (within its namespace). @@ -125,6 +126,22 @@ to the processes then to represent the count of the processes we can have a metr `system.processes.count`. The suffix `count` here indicates that it is the count of `system.processes`. +This rule SHOULD only be applied to UpDownCounters, since (monotonic) Counters have +`_total` appended to their names when they are +[mapped to Prometheus](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/compatibility/prometheus_and_openmetrics.md#otlp-metric-points-to-prometheus), +which would lead to `_count_total`. + +#### Do not use `total` + +Counters SHOULD NOT append `_total` to their names. Counters have `_total` appended to their names when they are +[mapped to Prometheus](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/compatibility/prometheus_and_openmetrics.md#otlp-metric-points-to-prometheus), +which would lead to `_total_total`. The reason that the Prometheus mapping cannot +suppress adding the duplicate `_total` is because then the mapping wouldn't be +bidirectional. + +UpDownCounters SHOULD NOT use `_total` either because then they will look like +monotonic sums in Prometheus. + ## General Metric Semantic Conventions **Status**: [Mixed][DocumentStatus] From 00c72c2294581baea193cec7f2299a986468871a Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 24 Jul 2023 15:37:27 -0700 Subject: [PATCH 2/5] fix --- CHANGELOG.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8822f5c851..e60ef60c1d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -508,4 +508,3 @@ N/A ## v1.0.0 (2021-02-10) First release of OpenTelemetry Specification. Semantic conventions were not explicitly tracked in changelog up to this point. - From 681e73321843438911c25527031f029ed404c7a9 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 25 Jul 2023 09:20:05 -0700 Subject: [PATCH 3/5] updates --- docs/general/metrics.md | 23 +++++++++-------------- 1 file changed, 9 insertions(+), 14 deletions(-) diff --git a/docs/general/metrics.md b/docs/general/metrics.md index b93d1f0a3d..ea127de5a3 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -12,7 +12,8 @@ aliases: [docs/specs/semconv/general/metrics-general] - [General Guidelines](#general-guidelines) * [Name Reuse Prohibition](#name-reuse-prohibition) * [Units](#units) - * [Pluralization](#pluralization) + * [Naming rules for Counters and UpDownCounters](#naming-rules-for-counters-and-updowncounters) + * [Pluralization](#pluralization) + [Use `count` Instead of Pluralization for UpDownCounters](#use-count-instead-of-pluralization-for-updowncounters) + [Do not use `total`](#do-not-use-total) - [General Metric Semantic Conventions](#general-metric-semantic-conventions) @@ -100,7 +101,9 @@ When building components that interoperate between OpenTelemetry and a system using the OpenMetrics exposition format, use the [OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/compatibility/prometheus_and_openmetrics.md). -### Pluralization +### Naming rules for Counters and UpDownCounters + +#### Pluralization Metric names SHOULD NOT be pluralized, unless the value being recorded represents discrete instances of a @@ -126,21 +129,13 @@ to the processes then to represent the count of the processes we can have a metr `system.processes.count`. The suffix `count` here indicates that it is the count of `system.processes`. -This rule SHOULD only be applied to UpDownCounters, since (monotonic) Counters have -`_total` appended to their names when they are -[mapped to Prometheus](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/compatibility/prometheus_and_openmetrics.md#otlp-metric-points-to-prometheus), -which would lead to `_count_total`. - #### Do not use `total` -Counters SHOULD NOT append `_total` to their names. Counters have `_total` appended to their names when they are -[mapped to Prometheus](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/compatibility/prometheus_and_openmetrics.md#otlp-metric-points-to-prometheus), -which would lead to `_total_total`. The reason that the Prometheus mapping cannot -suppress adding the duplicate `_total` is because then the mapping wouldn't be -bidirectional. +UpDownCounters SHOULD NOT use `_total` because then they will look like +monotonic sums. -UpDownCounters SHOULD NOT use `_total` either because then they will look like -monotonic sums in Prometheus. +Counters SHOULD NOT append `_total` either because then their meaning will +be confusing in delta backends. ## General Metric Semantic Conventions From 1322ad5dac5097af419af65ccce247e19133e6a7 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 25 Jul 2023 09:25:25 -0700 Subject: [PATCH 4/5] empty From f805305cea2645889bfa83f3d3e7e457c3239534 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 25 Jul 2023 09:27:25 -0700 Subject: [PATCH 5/5] fix --- docs/general/metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/metrics.md b/docs/general/metrics.md index ea127de5a3..3ba128a273 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -13,7 +13,7 @@ aliases: [docs/specs/semconv/general/metrics-general] * [Name Reuse Prohibition](#name-reuse-prohibition) * [Units](#units) * [Naming rules for Counters and UpDownCounters](#naming-rules-for-counters-and-updowncounters) - * [Pluralization](#pluralization) + + [Pluralization](#pluralization) + [Use `count` Instead of Pluralization for UpDownCounters](#use-count-instead-of-pluralization-for-updowncounters) + [Do not use `total`](#do-not-use-total) - [General Metric Semantic Conventions](#general-metric-semantic-conventions)