From 2a27d88c9617044b7c06843f16304e0c25416019 Mon Sep 17 00:00:00 2001 From: Dmitrii Anoshin Date: Wed, 7 Jun 2023 10:51:38 -0700 Subject: [PATCH] [chore] [pkg/translator/prometheus] Update documentation (#23209) - Describe transformations currently applied in the Prometheus receiver - Fix `crypto.dogecoin.value_dollars`-> `crypto_dogecoin_value_dollars` typo --- pkg/translator/prometheus/README.md | 34 ++++++++++++++++++----------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/pkg/translator/prometheus/README.md b/pkg/translator/prometheus/README.md index 814069d27f36..700f442b45c3 100644 --- a/pkg/translator/prometheus/README.md +++ b/pkg/translator/prometheus/README.md @@ -18,19 +18,20 @@ > $ otelcol --config=config.yaml --feature-gates=-pkg.translator.prometheus.NormalizeName > ``` -List of transformations performed on OpenTelemetry metrics names: - -| Case | Transformation | Example | -| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -| Unsupported characters and extraneous underscores | Replace unsupported characters with underscores (`_`). Drop redundant, leading and trailing underscores. | `(lambda).function.executions(#)` ==> `lambda_function_executions` | -| Standard unit | Convert the unit from [Unified Code for Units of Measure](http://unitsofmeasure.org/ucum.html) to Prometheus standard and append | `system.filesystem.usage` with unit `By` ==> `system_filesystem_usage_bytes` | -| Non-standard unit (unit is surrounded with `{}`) | Drop the unit | `system.network.dropped` with unit `{packets}` ==> `system_network_dropped` | -| Non-standard unit (unit is **not** surrounded with `{}`) | Append the unit, if not already present, after sanitization (all non-alphanumeric chars are dropped) | `system.network.dropped` with unit `packets` ==> `system_network_dropped_packets` | -| Percentages (unit is `1`) | Append `_ratio` (for gauges only) | `system.memory.utilization` with unit `1` ==> `system_memory_utilization_ratio` | -| Percentages (unit is `%`) | Replace `%` with `percent` `_percent` | `storage.filesystem.utilization` with unit `%` ==> `storage_filesystem_utilization_percent` | -| Rates (unit contains `/`) | Replace `/` with `per` | `astro.light.speed` with unit `m/s` ==> `astro_light_speed_meters_per_second` | -| Dollars (unit is `$`) | Replace `$` with `dollars` | `crypto.dogecoin.value` with unit `$` ==> `crypto.dogecoin.value_dollars` | -| Counter | Append `_total` | `system.processes.created` ==> `system_processes_created_total` | +#### List of transformations to convert OpenTelemetry metrics to Prometheus metrics + +| Case | Transformation | Example | +|----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------| +| Unsupported characters and extraneous underscores | Replace unsupported characters with underscores (`_`). Drop redundant, leading and trailing underscores. | `(lambda).function.executions(#)` → `lambda_function_executions` | +| Standard unit | Convert the unit from [Unified Code for Units of Measure](http://unitsofmeasure.org/ucum.html) to Prometheus standard and append | `system.filesystem.usage` with unit `By` → `system_filesystem_usage_bytes` | +| Non-standard unit (unit is surrounded with `{}`) | Drop the unit | `system.network.dropped` with unit `{packets}` → `system_network_dropped` | +| Non-standard unit (unit is **not** surrounded with `{}`) | Append the unit, if not already present, after sanitization (all non-alphanumeric chars are dropped) | `system.network.dropped` with unit `packets` → `system_network_dropped_packets` | +| Percentages (unit is `1`) | Append `_ratio` (for gauges only) | `system.memory.utilization` with unit `1` → `system_memory_utilization_ratio` | +| Percentages (unit is `%`) | Replace `%` with `percent` `_percent` | `storage.filesystem.utilization` with unit `%` → `storage_filesystem_utilization_percent` | +| Rates (unit contains `/`) | Replace `/` with `per` | `astro.light.speed` with unit `m/s` → `astro_light_speed_meters_per_second` | +| Dollars (unit is `$`) | Replace `$` with `dollars` | `crypto.dogecoin.value` with unit `$` → `crypto_dogecoin_value_dollars` | +| Counter | Append `_total` | `system.processes.created` → `system_processes_created_total` | + List of standard OpenTelemetry units that will be translated to [Prometheus standard base units](https://prometheus.io/docs/practices/naming/#base-units): | OpenTelemetry Unit | Corresponding Prometheus Unit | @@ -74,6 +75,13 @@ List of standard OpenTelemetry units that will be translated to [Prometheus stan > **Note** > Prometheus also recommends using base units (no kilobytes, or milliseconds, for example) but these functions will not attempt to convert non-base units to base units. +#### List of transformations performed to convert Prometheus metrics to OpenTelemetry metrics + +| Case | Transformation | Example | +|------------------------------------|------------------------------------------------------------------------|---------------------------------------------------------------------------------| +| UNIT defined in OpenMetrics format | Drop the unit suffix and set it in the OpenTelemetry metric unit field | `system_network_dropped_packets` → `system_network_dropped` with `packets` unit | +| Counter | Drop `_total` suffix | `system_processes_created_total`→ `system_processes_created` | + ### Simple normalization If feature `pkg.translator.prometheus.NormalizeName` is not enabled, a simple sanitization of the OpenTelemetry metric name is performed to ensure it follows Prometheus naming conventions: