Skip to content

Commit

Permalink
[chore] [pkg/translator/prometheus] Document Prometheus->OTel conversion
Browse files Browse the repository at this point in the history 
Describe transformations currently applied in the Prometheus receiver in README.md
  • Loading branch information
@dmitryax
dmitryax committed Jun 7, 2023
1 parent 8dc41a8 commit 2da3530
Showing 1 changed file with 21 additions and 13 deletions.
34 changes: 21 additions & 13 deletions pkg/translator/prometheus/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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:
Expand Down

0 comments on commit 2da3530

Please sign in to comment.