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.

Sign up for GitHub

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

Jump to bottom

Clarify prometheus unit conversions #3066

Merged
merged 5 commits into from
Feb 1, 2023
Merged

Clarify prometheus unit conversions #3066

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f0d82e7
clarify prometheus unit conversions
dashpole Jan 3, 2023
1cb4bc4
don't add unit if it already exists
dashpole Jan 4, 2023
36723e0
remove recommendation to convert to base units
dashpole Jan 13, 2023
815f620
Merge branch 'main' into prom_unit_clarification
dashpole Jan 20, 2023
a560595
Merge branch 'main' into prom_unit_clarification
jmacd Feb 1, 2023
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
23 changes: 17 additions & 6 deletions specification/compatibility/prometheus_and_openmetrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,12 @@ suffixes described below.
The [OpenMetrics UNIT metadata](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#metricfamily),
if present, MUST be converted to the unit of the OTLP metric. After trimming
type-specific suffixes, such as `_total` for counters, the unit MUST be trimmed
from the suffix as well, if the metric suffix matches the unit.
from the suffix as well, if the metric suffix matches the unit. The unit SHOULD
be translated from Prometheus conventions to OpenTelemetry conventions by:

* Converting from full words to abbreviations (e.g. "milliseconds" to "ms").
* Special case: Converting "ratio" to "1".
* Converting "foo_per_bar" to "foo/bar".

The [OpenMetrics HELP metadata](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#metricfamily),
if present, MUST be added as the description of the OTLP metric.
Expand Down Expand Up @@ -223,11 +228,17 @@ required to match the regex: `[a-zA-Z_:]([a-zA-Z0-9_:])*`. Invalid characters
in the metric name MUST be replaced with the `_` character. Multiple
consecutive `_` characters MUST be replaced with a single `_` character.

The Unit of an OTLP metric point MUST be added as
[OpenMetrics UNIT metadata](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#metricfamily).
Additionally, the unit MUST be added as a suffix to the metric name, and SHOULD
be converted to [base units](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#units-and-base-units)
recommended by OpenMetrics when possible. The unit suffix comes before any
The Unit of an OTLP metric point SHOULD be converted to the equivalent unit in Prometheus when possible. This includes:

* Converting from abbreviations to full words (e.g. "ms" to "milliseconds").
* Dropping the portions of the Unit within brackets (e.g. {packets}). Brackets MUST NOT be included in the resulting unit. A "count of foo" is considered unitless in Prometheus.
* Special case: Converting "1" to "ratio".
jmacd marked this conversation as resolved.
Show resolved Hide resolved
* Converting "foo/bar" to "foo_per_bar".
dashpole marked this conversation as resolved.
Show resolved Hide resolved

The resulting unit SHOULD be added to the metric as
[OpenMetrics UNIT metadata](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#metricfamily)
and as a suffix to the metric name unless the metric name already contains the
unit, or the unit MUST be omitted. The unit suffix comes before any
type-specific suffixes.

The description of an OTLP metrics point MUST be added as
Expand Down