diff --git a/CHANGELOG.md b/CHANGELOG.md index 1865cc9e0aa..f61a2ba19bc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,14 @@ release. ### Metrics +- Flexibilie escaping of characters that are discouraged by Prometheus Conventions + in Prometheus exporters. + ([#4533](https://github.com/open-telemetry/opentelemetry-specification/pull/4533)) +- Flexibilize addition of unit/type related suffixes in Prometheus exporters. + ([#4533](https://github.com/open-telemetry/opentelemetry-specification/pull/4533)) +- Define the configuration option "Translation Strategies" for Prometheus exporters. + ([#4533](https://github.com/open-telemetry/opentelemetry-specification/pull/4533)) + ### Logs - Clarify that `SeverityNumber` values are used when comparing severities. diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index b9caffe6128..95389f4e091 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -248,13 +248,12 @@ comments (but not metric points) SHOULD be dropped. If dropping a comment or metric points, the exporter SHOULD warn the user through error logging. The Name of an OTLP metric MUST be added as the -[Prometheus Metric Name](https://prometheus.io/docs/instrumenting/exposition_formats/#comments-help-text-and-type-information), -with unit and type suffixes added as described below. The metric name is -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. +[Prometheus Metric Name](https://prometheus.io/docs/instrumenting/exposition_formats/#comments-help-text-and-type-information). +Prometheus naming conventions encourage metric names to match the regex: `[a-zA-Z_:]([a-zA-Z0-9_:])*`. Discouraged characters +in the metric name SHOULD be replaced with the `_` character by default, aiming for compatibility with Prometheus conventions. Multiple +consecutive `_` characters SHOULD be replaced with a single `_` character. -The Unit of an OTLP metric point SHOULD be converted to the equivalent unit in Prometheus when possible. This includes: +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. {packet}). Brackets MUST NOT be included in the resulting unit. A "count of foo" is considered unitless in Prometheus. @@ -262,9 +261,9 @@ The Unit of an OTLP metric point SHOULD be converted to the equivalent unit in P * Converting "foo/bar" to "foo_per_bar". The resulting unit SHOULD be added to the metric as -[UNIT metadata](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#metricfamily) -and as a suffix to the metric name unless the metric name already ends with the -unit (before type-specific suffixes), or the unit metadata MUST be omitted. The +[UNIT metadata](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#metricfamily). +A suffix to the metric name SHOULD be added unless the metric name already ends with the +unit (before type-specific suffixes). The unit suffix comes before any type-specific suffixes. The description of an OTLP metrics point MUST be added as @@ -306,7 +305,7 @@ to a Prometheus Gauge. - The new data point's start time must match the time of the accumulated data point. If not, see [detecting alignment issues](../metrics/data-model.md#sums-detecting-alignment-issues). - Otherwise, it MUST be dropped. -If the metric name for monotonic Sum metric points does not end in a suffix of `_total` a suffix of `_total` MUST be added by default, otherwise the name MUST remain unchanged. Exporters SHOULD provide a configuration option to disable the addition of `_total` suffixes. +If the metric name for monotonic Sum metric points does not end in a suffix of `_total` a suffix of `_total` SHOULD be added by default, otherwise the name MUST remain unchanged. Exporters SHOULD provide a configuration option to disable the addition of `_total` suffixes. Monotonic Sum metric points with `StartTimeUnixNano` should export the `{name}_created` metric as well. ### Histograms @@ -379,10 +378,9 @@ OpenTelemetry Metric Attributes MUST be converted to String Attribute values are converted directly to Metric Attributes, and non-string Attribute values MUST be converted to string attributes following the [attribute specification](../common/README.md#attribute). Prometheus -metric label keys are required to match the following regex: -`[a-zA-Z_]([a-zA-Z0-9_])*`. Metrics from OpenTelemetry with unsupported -Attribute names MUST replace invalid characters with the `_` character. -Multiple consecutive `_` characters MUST be replaced with a single `_` +naming conventions encourage metric names to match the following regex: +`[a-zA-Z_]([a-zA-Z0-9_])*`. Discouraged characters SHOULD be replace with the `_` character. +Multiple consecutive `_` characters SHOULD be replaced with a single `_` character. This may cause ambiguity in scenarios where multiple similar-named attributes share invalid characters at the same location. In such unlikely cases, if multiple key-value pairs are converted to have the same Prometheus diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md index 1db6f264d6c..91eef280ec3 100644 --- a/specification/metrics/sdk_exporters/prometheus.md +++ b/specification/metrics/sdk_exporters/prometheus.md @@ -63,11 +63,13 @@ The configuration SHOULD allow the user to select which resource attributes to c include / exclude or regular expression based). Copied Resource attributes MUST NOT be excluded from the `target` info metric. The option MAY be named `with_resource_constant_labels`. -A Prometheus Exporter MAY support a configuration option to produce metrics without a [unit suffix](../../compatibility/prometheus_and_openmetrics.md#metric-metadata) -or UNIT metadata. The option MAY be named `without_units`, and MUST be `false` by default. +A Prometheus Exporter MAY support a configuration option that controls the translation of metric names from OpenTelemetry Naming Conventions to [Prometheus Naming conventions](https://prometheus.io/docs/practices/naming/). +If the Prometheus exporter supports such configuration it MUST be named to something that resembles Prometheus configuration option `translation_strategy`, and the translation options MUST be: -A Prometheus Exporter MAY support a configuration option to produce metrics without a [type suffix](../../compatibility/prometheus_and_openmetrics.md#metric-metadata). -The option MAY be named `without_type_suffix`, and MUST be `false` by default. +- `UnderscoreEscapingWithSuffixes`, the default. This fully escapes metric names for classic Prometheus metric name compatibility, and includes appending type and unit suffixes. +- `UnderscoreEscapingWithoutSuffixes`, metric names will continue to escape special characters to `_`, but suffixes won't be attached. +- `NoUTF8EscapingWithSuffixes` will disable changing special characters to `_`. Special suffixes like units and `_total` for counters will be attached. +- `NoTranslation`. This strategy bypasses all metric and label name translation, passing them through unaltered. A Prometheus Exporter MAY support a configuration option to produce metrics without [scope labels](../../compatibility/prometheus_and_openmetrics.md#instrumentation-scope-1). The option MAY be named `without_scope_info`, and MUST be `false` by default. @@ -80,3 +82,12 @@ metric. The option MAY be named `without_target_info`, and MUST be `false` by de A Prometheus Exporter MUST support content negotiation to allow clients to request metrics in different formats based on the `Accept` header in HTTP requests. Content negotiation MUST follow [Prometheus Content Negotiation guidelines](https://prometheus.io/docs/instrumenting/content_negotiation/). + +### Interaction with Translation Strategy + +Although a Prometheus Exporter MAY be configured with a `translation_strategy` for internal metric processing, the final output format and character escaping MUST follow what the content negotiation process determines based on the client's `Accept` header. The content negotiation requirements MUST take precedence over the configured translation strategy when determining the final output format. + +Examples: + +- If configured with `NoTranslation` but the client requests `escaping=underscores`, the exporter MUST apply underscore escaping. +- If configured with `UnderscoreEscapingWithSuffixes` but the client requests `escaping=allow-utf8`, there's no need to revert what has been translated since the exporter will continue to be compliant.