From 2caaafdc5fb0527f86c6078407b05796568438dd Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 13 Jun 2023 11:30:44 -0700 Subject: [PATCH] .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]