Skip to content

Commit

Permalink
clarify prometheus unit conversions
Browse files Browse the repository at this point in the history
  • Loading branch information
dashpole committed Jan 3, 2023
1 parent 12c968d commit aaa1730
Showing 1 changed file with 16 additions and 7 deletions.
23 changes: 16 additions & 7 deletions specification/compatibility/prometheus_and_openmetrics.md
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 @@ -221,12 +226,16 @@ 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
type-specific suffixes.
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").
* Converting to [base units](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#units-and-base-units) (e.g. "milliseconds" to "seconds"), which also requires adjusting the value.
* 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".
* Converting "foo/bar" to "foo_per_bar".

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, 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
[OpenMetrics HELP metadata](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#metricfamily).
Expand Down

0 comments on commit aaa1730

Please sign in to comment.