Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add metric name pluralization guidelines #1109

Merged
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions specification/metrics/semantic_conventions/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,18 @@
# Metrics Semantic Conventions

<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->

<!-- toc -->

- [General Guidelines](#general-guidelines)
* [Units](#units)
* [Pluralization](#pluralization)
- [General Metric Semantic Conventions](#general-metric-semantic-conventions)
* [Instrument Naming](#instrument-naming)
* [Units](#units-1)

<!-- tocstop -->

The following semantic conventions surrounding metrics are defined:

* [HTTP Metrics](http-metrics.md): Semantic conventions and instruments for HTTP metrics.
Expand Down Expand Up @@ -50,12 +63,29 @@ and confusion for end users. (For example, prefer `runtime.java.gc*` over
`runtime.gc.*`.) Measures of many operating system metrics are similarly
ambiguous.

### Units

Conventional metrics or metrics that have their units included in
OpenTelemetry metadata (e.g. `metric.WithUnit` in Go) SHOULD NOT include the
units in the metric name. Units may be included when it provides additional
meaning to the metric name. Metrics MUST, above all, be understandable and
usable.

### Pluralization

Metric names SHOULD NOT be pluralized, unless the value being recorded
represents discrete instances of a
[countable quantity](https://en.wikipedia.org/wiki/Count_noun).
arminru marked this conversation as resolved.
Show resolved Hide resolved
Generally, the name SHOULD be pluralized only if the unit of the metric in
question is a pseudo-unit (like `{faults}` or `{operations}`).

Examples:
arminru marked this conversation as resolved.
Show resolved Hide resolved

* `system.filesystem.utilization`, `http.server.duration`, and `system.cpu.time`
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.

## General Metric Semantic Conventions

The following semantic conventions aim to keep naming consistent. They
Expand Down