Prometheus translation modes

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.

specification/compatibility/prometheus_and_openmetrics.md

@@ -248,23 +248,22 @@ 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.
 * Special case: Converting "1" to "ratio".
 * 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

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.