diff --git a/docs/guides/opentelemetry.md b/docs/guides/opentelemetry.md index 31d768db..b0e897d7 100644 --- a/docs/guides/opentelemetry.md +++ b/docs/guides/opentelemetry.md @@ -148,9 +148,10 @@ For each of a resource's OTel metrics, Prometheus converts it to a corresponding From the 3.x version, Prometheus supports UTF-8 for metric names and labels, so [Prometheus normalization translator package from OpenTelemetry](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/pkg/translator/prometheus) can be omitted. Note that when Prometheus announces through content negotiation that it allows UTF-8 characters, it does not require that metric names contain previously-unsupported characters. The OTLP metrics may be converted in several different ways, depending on the configuration of the endpoint. So while UTF-8 is enabled by default in Prometheus storage and UI, you need to set the `translation_strategy` for OTLP metrics receiver, which by default is set to old normalization `UnderscoreEscapingWithSuffixes`. -There are three possible translation strategies, two of which require UTF-8 support to be enabled in Prometheus: +There are four possible translation strategies, two of which require UTF-8 support to be enabled in Prometheus: * `UnderscoreEscapingWithSuffixes`, the default. This fully escapes metric names for classic [Prometheus metric name compatibility](https://prometheus.io/docs/practices/naming/), and includes appending type and unit suffixes. +* `UnderscoreEscapingWithoutSuffixes`. This fully escapes metric names similar to UnderscoreEscapingWithSuffixes, but does not append type and unit suffixes. This mode is undesirable from a number of standpoints and users should be aware that the lack of suffixes could cause metric name collisions and only enable this mode in concert with careful testing. It is used by some organizations who prefer this balance of Otel symmetry and limited character support. * `NoUTF8EscapingWithSuffixes` will disable changing special characters to `_` which allows native use of OpenTelemetry metric format, especially with [the semantic conventions](https://opentelemetry.io/docs/specs/semconv/general/metrics/). Note that special suffixes like units and `_total` for counters will be attached to prevent possible collisions with multiple metrics of the same name having different type or units. This mode requires UTF-8 to be enabled. * `NoTranslation`. This strategy bypasses all metric and label name translation, passing them through unaltered. This mode requires UTF-8 to be enabled. Note that without suffixes, it is possible to have collisions when multiple metrics of the same name have different type or units.