Clarify the NoUTF8EscapingWithSuffixes and UnderscoreEscapingWithSuffixes modes (#15567)

Signed-off-by: Arve Knudsen <arve.knudsen@gmail.com>

config/config.go

@@ -1427,10 +1427,13 @@ func getGoGCEnv() int {
 type translationStrategyOption string
 
 var (
-	// NoUTF8EscapingWithSuffixes will keep UTF-8 characters as they are, units and type suffixes will still be added.
+	// NoUTF8EscapingWithSuffixes will accept metric/label names as they are.
+	// Unit and type suffixes may be added to metric names, according to certain rules.
 	NoUTF8EscapingWithSuffixes translationStrategyOption = "NoUTF8EscapingWithSuffixes"
 	// UnderscoreEscapingWithSuffixes is the default option for translating OTLP to Prometheus.
-	// This option will translate all UTF-8 characters to underscores, while adding units and type suffixes.
+	// This option will translate metric name characters that are not alphanumerics/underscores/colons to underscores,
+	// and label name characters that are not alphanumerics/underscores to underscores.
+	// Unit and type suffixes may be appended to metric names, according to certain rules.
 	UnderscoreEscapingWithSuffixes translationStrategyOption = "UnderscoreEscapingWithSuffixes"
 )
 

docs/configuration/configuration.md

@@ -179,8 +179,8 @@ otlp:
   # - "UnderscoreEscapingWithSuffixes" refers to commonly agreed normalization used
   #   by OpenTelemetry in https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/pkg/translator/prometheus
   # - "NoUTF8EscapingWithSuffixes" is a mode that relies on UTF-8 support in Prometheus.
-  #   It preserves all special characters like dots, but it still add required suffixes
+  #   It preserves all special characters like dots, but still adds required metric name suffixes
-  #   for units and _total like in UnderscoreEscapingWithSuffixes.
+  #   for units and _total, as UnderscoreEscapingWithSuffixes does.
   [ translation_strategy: <string> | default = "UnderscoreEscapingWithSuffixes" ]
   # Enables adding "service.name", "service.namespace" and "service.instance.id"
   # resource attributes to the "target_info" metric, on top of converting

documentation/examples/prometheus-otlp.yml

@@ -22,7 +22,7 @@ otlp:
     - k8s.pod.name
     - k8s.replicaset.name
     - k8s.statefulset.name
-  # Ingest OTLP data keeping UTF-8 characters in metric/label names.
+  # Ingest OTLP data keeping all characters in metric/label names.
   translation_strategy: NoUTF8EscapingWithSuffixes
 
 storage: