Add Prometheus translation strategy support

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Author: zeitlinger

dependencyManagement/build.gradle.kts

@@ -15,7 +15,7 @@ val jmhVersion = "1.37"
 val mockitoVersion = "4.11.0"
 val slf4jVersion = "2.0.17"
 val opencensusVersion = "0.31.1"
-val prometheusServerVersion = "1.5.1"
+val prometheusServerVersion = "1.6.1"
 val armeriaVersion = "1.38.0"
 val junitVersion = "5.14.4"
 val okhttpVersion = "5.3.2"

exporters/prometheus/src/main/java/io/opentelemetry/exporter/prometheus/Otel2PrometheusConverter.java

@@ -7,7 +7,6 @@
 
 import static io.prometheus.metrics.model.snapshots.PrometheusNaming.prometheusName;
 import static io.prometheus.metrics.model.snapshots.PrometheusNaming.sanitizeLabelName;
-import static io.prometheus.metrics.model.snapshots.PrometheusNaming.sanitizeMetricName;
 import static java.util.Objects.requireNonNull;
 
 import io.opentelemetry.api.common.AttributeKey;
@@ -84,6 +83,7 @@ final class Otel2PrometheusConverter {
 
   private final boolean otelScopeLabelsEnabled;
   private final boolean targetInfoMetricEnabled;
+  private final TranslationStrategy translationStrategy;
   @Nullable private final Predicate<String> allowedResourceAttributesFilter;
 
   /**
@@ -104,9 +104,11 @@ final class Otel2PrometheusConverter {
   Otel2PrometheusConverter(
       boolean otelScopeLabelsEnabled,
       boolean targetInfoMetricEnabled,
+      TranslationStrategy translationStrategy,
       @Nullable Predicate<String> allowedResourceAttributesFilter) {
     this.otelScopeLabelsEnabled = otelScopeLabelsEnabled;
     this.targetInfoMetricEnabled = targetInfoMetricEnabled;
+    this.translationStrategy = translationStrategy;
     this.allowedResourceAttributesFilter = allowedResourceAttributesFilter;
     this.resourceAttributesToAllowedKeysCache =
         allowedResourceAttributesFilter != null
@@ -122,6 +124,10 @@ boolean isTargetInfoMetricEnabled() {
     return targetInfoMetricEnabled;
   }
 
+  TranslationStrategy getTranslationStrategy() {
+    return translationStrategy;
+  }
+
   @Nullable
   Predicate<String> getAllowedResourceAttributesFilter() {
     return allowedResourceAttributesFilter;
@@ -155,7 +161,8 @@ private MetricSnapshot convert(MetricData metricData) {
     // Note that AggregationTemporality.DELTA should never happen
     // because PrometheusMetricReader#getAggregationTemporality returns CUMULATIVE.
 
-    MetricMetadata metadata = convertMetadata(metricData);
+    boolean isCounter = isMonotonicSum(metricData);
+    MetricMetadata metadata = convertMetadata(metricData, isCounter);
     InstrumentationScopeInfo scope = metricData.getInstrumentationScopeInfo();
     switch (metricData.getType()) {
       case LONG_GAUGE:
@@ -210,6 +217,17 @@ private MetricSnapshot convert(MetricData metricData) {
     return null;
   }
 
+  private static boolean isMonotonicSum(MetricData metricData) {
+    switch (metricData.getType()) {
+      case LONG_SUM:
+        return metricData.getLongSumData().isMonotonic();
+      case DOUBLE_SUM:
+        return metricData.getDoubleSumData().isMonotonic();
+      default:
+        return false;
+    }
+  }
+
   private GaugeSnapshot convertLongGauge(
       MetricMetadata metadata,
       InstrumentationScopeInfo scope,
@@ -550,29 +568,91 @@ private List<AttributeKey<?>> filterAllowedResourceAttributeKeys(@Nullable Resou
    * non-standard characters (dots, dashes, etc.) to underscores, and {@code sanitizeLabelName}
    * strips invalid leading prefixes.
    */
-  private static String convertLabelName(String key) {
-    return sanitizeLabelName(prometheusName(key));
+  private String convertLabelName(String key) {
+    if (translationStrategy.shouldEscape()) {
+      return sanitizeLabelName(prometheusName(key));
+    }
+    return key;
+  }
+
+  private MetricMetadata convertMetadata(MetricData metricData, boolean isCounter) {
+    switch (translationStrategy) {
+      case UNDERSCORE_ESCAPING_WITH_SUFFIXES:
+        return convertMetadataEscapedWithSuffixes(metricData);
+      case UNDERSCORE_ESCAPING_WITHOUT_SUFFIXES:
+        return convertMetadataEscapedWithoutSuffixes(metricData);
+      case NO_UTF8_ESCAPING_WITH_SUFFIXES:
+        return convertMetadataUtf8WithSuffixes(metricData, isCounter);
+      case NO_TRANSLATION:
+        return convertMetadataNoTranslation(metricData);
+    }
+    throw new IllegalStateException("Unknown strategy: " + translationStrategy);
+  }
+
+  private static MetricMetadata convertMetadataEscapedWithSuffixes(MetricData metricData) {
+    String name = prometheusName(metricData.getName());
+    String help = metricData.getDescription();
+    Unit unit = PrometheusUnitsHelper.convertUnit(metricData.getUnit());
+    name = stripRepeatedUnderscores(stripReservedMetricSuffixes(name));
+    if (unit != null && !name.endsWith(unit.toString())) {
+      name = name + "_" + unit;
+    }
+    return new MetricMetadata(stripRepeatedUnderscores(name), help, unit);
   }
 
-  private static MetricMetadata convertMetadata(MetricData metricData) {
-    String name = sanitizeMetricName(prometheusName(metricData.getName()));
+  private static MetricMetadata convertMetadataEscapedWithoutSuffixes(MetricData metricData) {
+    String rawName = stripRepeatedUnderscores(prometheusName(metricData.getName()));
+    String name = stripReservedMetricSuffixes(rawName);
+    return new MetricMetadata(name, rawName, rawName, metricData.getDescription(), null);
+  }
+
+  private static MetricMetadata convertMetadataUtf8WithSuffixes(
+      MetricData metricData, boolean isCounter) {
+    String name = metricData.getName();
     String help = metricData.getDescription();
     Unit unit = PrometheusUnitsHelper.convertUnit(metricData.getUnit());
     if (unit != null && !name.endsWith(unit.toString())) {
       name = name + "_" + unit;
     }
-    // Repeated __ are discouraged according to spec, although this is allowed in prometheus, see
-    // https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/compatibility/prometheus_and_openmetrics.md#metric-metadata-1
+    String expositionBaseName = name;
+    if (isCounter && !expositionBaseName.endsWith("_total")) {
+      expositionBaseName = expositionBaseName + "_total";
+    }
+    return new MetricMetadata(stripReservedMetricSuffixes(name), expositionBaseName, help, unit);
+  }
+
+  private static MetricMetadata convertMetadataNoTranslation(MetricData metricData) {
+    String rawName = metricData.getName();
+    String name = stripReservedMetricSuffixes(rawName);
+    return new MetricMetadata(name, rawName, rawName, metricData.getDescription(), null);
+  }
+
+  private static String stripReservedMetricSuffixes(String name) {
+    boolean modified = true;
+    while (modified) {
+      modified = false;
+      for (String suffix : PrometheusUnitsHelper.RESERVED_SUFFIXES) {
+        if (name.equals(suffix)) {
+          return name.substring(1);
+        }
+        if (name.endsWith(suffix)) {
+          name = name.substring(0, name.length() - suffix.length());
+          modified = true;
+        }
+      }
+    }
+    return name;
+  }
+
+  private static String stripRepeatedUnderscores(String name) {
     while (name.contains("__")) {
       name = name.replace("__", "_");
     }
-
-    return new MetricMetadata(name, help, unit);
+    return name;
   }
 
-  private static void putOrMerge(
-      Map<String, MetricSnapshot> snapshotsByName, MetricSnapshot snapshot) {
-    String name = snapshot.getMetadata().getPrometheusName();
+  private void putOrMerge(Map<String, MetricSnapshot> snapshotsByName, MetricSnapshot snapshot) {
+    String name = getMergeKey(snapshot.getMetadata());
     if (snapshotsByName.containsKey(name)) {
       MetricSnapshot merged = merge(snapshotsByName.get(name), snapshot);
       if (merged != null) {
@@ -583,6 +663,13 @@ private static void putOrMerge(
     }
   }
 
+  private String getMergeKey(MetricMetadata metadata) {
+    if (translationStrategy.shouldEscape()) {
+      return metadata.getPrometheusName();
+    }
+    return metadata.getName();
+  }
+
   /**
    * OpenTelemetry may use the same metric name multiple times but in different instrumentation
    * scopes. In that case, we try to merge the metrics. They will have different {@code

exporters/prometheus/src/main/java/io/opentelemetry/exporter/prometheus/PrometheusHttpServer.java

@@ -21,6 +21,7 @@
 import io.opentelemetry.sdk.metrics.export.CollectionRegistration;
 import io.opentelemetry.sdk.metrics.export.DefaultAggregationSelector;
 import io.opentelemetry.sdk.metrics.export.MetricReader;
+import io.prometheus.metrics.config.PrometheusProperties;
 import io.prometheus.metrics.exporter.httpserver.HTTPServer;
 import io.prometheus.metrics.model.registry.PrometheusRegistry;
 import java.io.IOException;
@@ -73,6 +74,7 @@ public static PrometheusHttpServerBuilder builder() {
       @Nullable HttpHandler defaultHandler,
       DefaultAggregationSelector defaultAggregationSelector,
       @Nullable Authenticator authenticator,
+      TranslationStrategy translationStrategy,
       PrometheusMetricReader prometheusMetricReader) {
     this.host = host;
     this.port = port;
@@ -95,9 +97,17 @@ public static PrometheusHttpServerBuilder builder() {
               new LinkedBlockingQueue<>(),
               new DaemonThreadFactory("prometheus-http-server"));
     }
+    HTTPServer.Builder httpServerBuilder = HTTPServer.builder();
+    if (translationStrategy != TranslationStrategy.UNDERSCORE_ESCAPING_WITH_SUFFIXES) {
+      // Intentionally enable OM2 without content negotiation so OpenMetrics responses keep the
+      // legacy OM1 content type while using OM2 name-preservation semantics.
+      PrometheusProperties prometheusProperties =
+          PrometheusProperties.builder().enableOpenMetrics2(om2 -> {}).build();
+      httpServerBuilder = HTTPServer.builder(prometheusProperties);
+    }
     try {
       this.httpServer =
-          HTTPServer.builder()
+          httpServerBuilder
               .hostname(host)
               .port(port)
               .executorService(executor)

exporters/prometheus/src/main/java/io/opentelemetry/exporter/prometheus/PrometheusHttpServerBuilder.java

@@ -102,6 +102,20 @@ public PrometheusHttpServerBuilder setTargetInfoMetricEnabled(boolean targetInfo
     return this;
   }
 
+  /**
+   * Sets the translation strategy for metric and label name conversion.
+   *
+   * @param translationStrategy the strategy to use
+   * @return this builder
+   * @see TranslationStrategy
+   */
+  public PrometheusHttpServerBuilder setTranslationStrategy(
+      TranslationStrategy translationStrategy) {
+    requireNonNull(translationStrategy, "translationStrategy");
+    metricReaderBuilder.setTranslationStrategy(translationStrategy);
+    return this;
+  }
+
   /**
    * Set if the resource attributes should be added as labels on each exported metric.
    *
@@ -201,6 +215,7 @@ public PrometheusHttpServer build() {
         defaultHandler,
         defaultAggregationSelector,
         authenticator,
+        metricReaderBuilder.getTranslationStrategy(),
         metricReaderBuilder.build());
   }
 }

exporters/prometheus/src/main/java/io/opentelemetry/exporter/prometheus/PrometheusMetricReader.java

@@ -52,7 +52,8 @@ public PrometheusMetricReader(
     this(
         allowedResourceAttributesFilter,
         /* otelScopeLabelsEnabled= */ true,
-        /* targetInfoMetricEnabled= */ true);
+        /* targetInfoMetricEnabled= */ true,
+        TranslationStrategy.UNDERSCORE_ESCAPING_WITH_SUFFIXES);
   }
 
   /**
@@ -65,18 +66,23 @@ public PrometheusMetricReader(@Nullable Predicate<String> allowedResourceAttribu
     this(
         allowedResourceAttributesFilter,
         /* otelScopeLabelsEnabled= */ true,
-        /* targetInfoMetricEnabled= */ true);
+        /* targetInfoMetricEnabled= */ true,
+        TranslationStrategy.UNDERSCORE_ESCAPING_WITH_SUFFIXES);
   }
 
   // Package-private constructor used by builder
   @SuppressWarnings("InconsistentOverloads")
   PrometheusMetricReader(
       @Nullable Predicate<String> allowedResourceAttributesFilter,
       boolean otelScopeLabelsEnabled,
-      boolean targetInfoMetricEnabled) {
+      boolean targetInfoMetricEnabled,
+      TranslationStrategy translationStrategy) {
     this.converter =
         new Otel2PrometheusConverter(
-            otelScopeLabelsEnabled, targetInfoMetricEnabled, allowedResourceAttributesFilter);
+            otelScopeLabelsEnabled,
+            targetInfoMetricEnabled,
+            translationStrategy,
+            allowedResourceAttributesFilter);
   }
 
   @Override
@@ -109,6 +115,7 @@ public String toString() {
     StringJoiner joiner = new StringJoiner(",", "PrometheusMetricReader{", "}");
     joiner.add("otelScopeLabelsEnabled=" + converter.isOtelScopeLabelsEnabled());
     joiner.add("targetInfoMetricEnabled=" + converter.isTargetInfoMetricEnabled());
+    joiner.add("translationStrategy=" + converter.getTranslationStrategy());
     joiner.add("allowedResourceAttributesFilter=" + converter.getAllowedResourceAttributesFilter());
     return joiner.toString();
   }

exporters/prometheus/src/main/java/io/opentelemetry/exporter/prometheus/PrometheusMetricReaderBuilder.java

@@ -5,6 +5,8 @@
 
 package io.opentelemetry.exporter.prometheus;
 
+import static java.util.Objects.requireNonNull;
+
 import java.util.function.Predicate;
 import javax.annotation.Nullable;
 
@@ -13,13 +15,16 @@ public final class PrometheusMetricReaderBuilder {
 
   private boolean otelScopeLabelsEnabled = true;
   private boolean targetInfoMetricEnabled = true;
+  private TranslationStrategy translationStrategy =
+      TranslationStrategy.UNDERSCORE_ESCAPING_WITH_SUFFIXES;
   @Nullable private Predicate<String> allowedResourceAttributesFilter;
 
   PrometheusMetricReaderBuilder() {}
 
   PrometheusMetricReaderBuilder(PrometheusMetricReaderBuilder metricReaderBuilder) {
     this.otelScopeLabelsEnabled = metricReaderBuilder.otelScopeLabelsEnabled;
     this.targetInfoMetricEnabled = metricReaderBuilder.targetInfoMetricEnabled;
+    this.translationStrategy = metricReaderBuilder.translationStrategy;
     this.allowedResourceAttributesFilter = metricReaderBuilder.allowedResourceAttributesFilter;
   }
 
@@ -47,6 +52,20 @@ public PrometheusMetricReaderBuilder setTargetInfoMetricEnabled(boolean targetIn
     return this;
   }
 
+  /**
+   * Sets the translation strategy for metric and label name conversion.
+   *
+   * @param translationStrategy the strategy to use
+   * @return this builder
+   * @see TranslationStrategy
+   */
+  public PrometheusMetricReaderBuilder setTranslationStrategy(
+      TranslationStrategy translationStrategy) {
+    requireNonNull(translationStrategy, "translationStrategy");
+    this.translationStrategy = translationStrategy;
+    return this;
+  }
+
   /**
    * Sets a filter to control which resource attributes are added as labels on each exported metric.
    * If {@code null}, no resource attributes will be added as labels. Default is {@code null}.
@@ -60,9 +79,16 @@ public PrometheusMetricReaderBuilder setAllowedResourceAttributesFilter(
     return this;
   }
 
+  TranslationStrategy getTranslationStrategy() {
+    return translationStrategy;
+  }
+
   /** Builds a new {@link PrometheusMetricReader}. */
   public PrometheusMetricReader build() {
     return new PrometheusMetricReader(
-        allowedResourceAttributesFilter, otelScopeLabelsEnabled, targetInfoMetricEnabled);
+        allowedResourceAttributesFilter,
+        otelScopeLabelsEnabled,
+        targetInfoMetricEnabled,
+        translationStrategy);
   }
 }