diff --git a/CHANGELOG.md b/CHANGELOG.md index 800a0d08a3..e60ef60c1d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ release. - Fix the unit of metric.process.runtime.jvm.system.cpu.load_1m to be {run_queue_item} ([#95](https://github.com/open-telemetry/semantic-conventions/pull/95)) +- 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)) ## v1.21.0 (2023-07-13) diff --git a/docs/general/metrics.md b/docs/general/metrics.md index f4b03f34f6..3ba128a273 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -12,8 +12,10 @@ aliases: [docs/specs/semconv/general/metrics-general] - [General Guidelines](#general-guidelines) * [Name Reuse Prohibition](#name-reuse-prohibition) * [Units](#units) - * [Pluralization](#pluralization) - + [Use `count` Instead of Pluralization](#use-count-instead-of-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) * [Instrument Naming](#instrument-naming) * [Instrument Units](#instrument-units) @@ -99,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 @@ -114,7 +118,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 +129,14 @@ 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`. +#### Do not use `total` + +UpDownCounters SHOULD NOT use `_total` because then they will look like +monotonic sums. + +Counters SHOULD NOT append `_total` either because then their meaning will +be confusing in delta backends. + ## General Metric Semantic Conventions **Status**: [Mixed][DocumentStatus]