UTF-8 support in metric and label names

benchmarks/src/main/java/io/prometheus/metrics/benchmarks/TextFormatUtilBenchmark.java

@@ -3,6 +3,7 @@
 import io.prometheus.metrics.expositionformats.ExpositionFormatWriter;
 import io.prometheus.metrics.expositionformats.OpenMetricsTextFormatWriter;
 import io.prometheus.metrics.expositionformats.PrometheusTextFormatWriter;
+import io.prometheus.metrics.model.snapshots.EscapingScheme;
 import io.prometheus.metrics.model.snapshots.GaugeSnapshot;
 import io.prometheus.metrics.model.snapshots.GaugeSnapshot.GaugeDataPointSnapshot;
 import io.prometheus.metrics.model.snapshots.Labels;
@@ -69,14 +70,15 @@ public OutputStream openMetricsWriteToByteArray(WriterState writerState) throws
     // avoid growing the array
     ByteArrayOutputStream byteArrayOutputStream = writerState.byteArrayOutputStream;
     byteArrayOutputStream.reset();
-    OPEN_METRICS_TEXT_FORMAT_WRITER.write(byteArrayOutputStream, SNAPSHOTS);
+    OPEN_METRICS_TEXT_FORMAT_WRITER.write(
+        byteArrayOutputStream, SNAPSHOTS, EscapingScheme.NO_ESCAPING);
     return byteArrayOutputStream;
   }
 
   @Benchmark
   public OutputStream openMetricsWriteToNull() throws IOException {
     OutputStream nullOutputStream = NullOutputStream.INSTANCE;
-    OPEN_METRICS_TEXT_FORMAT_WRITER.write(nullOutputStream, SNAPSHOTS);
+    OPEN_METRICS_TEXT_FORMAT_WRITER.write(nullOutputStream, SNAPSHOTS, EscapingScheme.NO_ESCAPING);
     return nullOutputStream;
   }
 
@@ -85,14 +87,15 @@ public OutputStream prometheusWriteToByteArray(WriterState writerState) throws I
     // avoid growing the array
     ByteArrayOutputStream byteArrayOutputStream = writerState.byteArrayOutputStream;
     byteArrayOutputStream.reset();
-    PROMETHEUS_TEXT_FORMAT_WRITER.write(byteArrayOutputStream, SNAPSHOTS);
+    PROMETHEUS_TEXT_FORMAT_WRITER.write(
+        byteArrayOutputStream, SNAPSHOTS, EscapingScheme.NO_ESCAPING);
     return byteArrayOutputStream;
   }
 
   @Benchmark
   public OutputStream prometheusWriteToNull() throws IOException {
     OutputStream nullOutputStream = NullOutputStream.INSTANCE;
-    PROMETHEUS_TEXT_FORMAT_WRITER.write(nullOutputStream, SNAPSHOTS);
+    PROMETHEUS_TEXT_FORMAT_WRITER.write(nullOutputStream, SNAPSHOTS, EscapingScheme.NO_ESCAPING);
     return nullOutputStream;
   }
 

prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterPushgatewayProperties.java

@@ -7,15 +7,19 @@ public class ExporterPushgatewayProperties {
   private static final String ADDRESS = "address";
   private static final String JOB = "job";
   private static final String SCHEME = "scheme";
+  private static final String ESCAPING_SCHEME = "escapingScheme";
   private static final String PREFIX = "io.prometheus.exporter.pushgateway";
   private final String scheme;
   private final String address;
   private final String job;
+  private final String escapingScheme;
 
-  private ExporterPushgatewayProperties(String address, String job, String scheme) {
+  private ExporterPushgatewayProperties(
+      String address, String job, String scheme, String escapingScheme) {
     this.address = address;
     this.job = job;
     this.scheme = scheme;
+    this.escapingScheme = escapingScheme;
   }
 
   /** Address of the Pushgateway in the form {@code host:port}. Default is {@code localhost:9091} */
@@ -39,6 +43,14 @@ public String getScheme() {
     return scheme;
   }
 
+  /**
+   * Escaping scheme to be used when pushing metric data to the pushgateway. Valid values:
+   * "no-escaping", "values", "underscores", "dots". Default is "no-escaping".
+   */
+  public String getEscapingScheme() {
+    return escapingScheme;
+  }
+
   /**
    * Note that this will remove entries from {@code properties}. This is because we want to know if
    * there are unused properties remaining after all properties have been loaded.
@@ -48,6 +60,8 @@ static ExporterPushgatewayProperties load(Map<Object, Object> properties)
     String address = Util.loadString(PREFIX + "." + ADDRESS, properties);
     String job = Util.loadString(PREFIX + "." + JOB, properties);
     String scheme = Util.loadString(PREFIX + "." + SCHEME, properties);
+    String escapingScheme = Util.loadString(PREFIX + "." + ESCAPING_SCHEME, properties);
+
     if (scheme != null) {
       if (!scheme.equals("http") && !scheme.equals("https")) {
         throw new PrometheusPropertiesException(
@@ -56,6 +70,20 @@ static ExporterPushgatewayProperties load(Map<Object, Object> properties)
                 PREFIX, SCHEME, scheme));
       }
     }
-    return new ExporterPushgatewayProperties(address, job, scheme);
+
+    if (escapingScheme != null) {
+      if (!escapingScheme.equals("no-escaping")
+          && !escapingScheme.equals("values")
+          && !escapingScheme.equals("underscores")
+          && !escapingScheme.equals("dots")) {
+        throw new PrometheusPropertiesException(
+            String.format(
+                "%s.%s: Illegal value. Expecting 'no-escaping', 'values', 'underscores', "
+                    + "or 'dots'. Found: %s",
+                PREFIX, ESCAPING_SCHEME, escapingScheme));
+      }
+    }
+
+    return new ExporterPushgatewayProperties(address, job, scheme, escapingScheme);
   }
 }

prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/NamingProperties.java

@@ -0,0 +1,61 @@
+package io.prometheus.metrics.config;
+
+import java.util.Map;
+import javax.annotation.Nullable;
+
+public class NamingProperties {
+
+  private static final String PREFIX = "io.prometheus.naming";
+  private static final String VALIDATION_SCHEME = "validationScheme";
+  private final ValidationScheme validationScheme;
+
+  private NamingProperties(ValidationScheme validation) {
+    this.validationScheme = validation;
+  }
+
+  public ValidationScheme getValidationScheme() {
+    return validationScheme;
+  }
+
+  static NamingProperties load(Map<Object, Object> properties)
+      throws PrometheusPropertiesException {
+    String validationScheme = Util.loadString(PREFIX + "." + VALIDATION_SCHEME, properties);
+    return new NamingProperties(parseValidationScheme(validationScheme));
+  }
+
+  static ValidationScheme parseValidationScheme(@Nullable String scheme) {
+    if (scheme == null || scheme.isEmpty()) {
+      return ValidationScheme.LEGACY_VALIDATION;
+    }
+
+    switch (scheme) {
+      case "utf-8":
+        return ValidationScheme.UTF_8_VALIDATION;
+      case "legacy":
+        return ValidationScheme.LEGACY_VALIDATION;
+      default:
+        throw new PrometheusPropertiesException(
+            "Unknown validation scheme: " + scheme + ". Valid values are: utf-8, legacy.");
+    }
+  }
+
+  public static Builder builder() {
+    return new Builder();
+  }
+
+  public static class Builder {
+
+    private ValidationScheme validationScheme;
+
+    private Builder() {}
+
+    public Builder validation(ValidationScheme validationScheme) {
+      this.validationScheme = validationScheme;
+      return this;
+    }
+
+    public NamingProperties build() {
+      return new NamingProperties(validationScheme);
+    }
+  }
+}

prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusProperties.java

@@ -20,6 +20,7 @@ public class PrometheusProperties {
   private final ExporterHttpServerProperties exporterHttpServerProperties;
   private final ExporterOpenTelemetryProperties exporterOpenTelemetryProperties;
   private final ExporterPushgatewayProperties exporterPushgatewayProperties;
+  private final NamingProperties namingProperties;
 
   /**
    * Get the properties instance. When called for the first time, {@code get()} loads the properties
@@ -48,7 +49,8 @@ public PrometheusProperties(
       ExporterFilterProperties exporterFilterProperties,
       ExporterHttpServerProperties httpServerConfig,
       ExporterPushgatewayProperties pushgatewayProperties,
-      ExporterOpenTelemetryProperties otelConfig) {
+      ExporterOpenTelemetryProperties otelConfig,
+      NamingProperties namingProperties) {
     this.defaultMetricsProperties = defaultMetricsProperties;
     this.metricProperties.putAll(metricProperties);
     this.exemplarProperties = exemplarProperties;
@@ -57,6 +59,7 @@ public PrometheusProperties(
     this.exporterHttpServerProperties = httpServerConfig;
     this.exporterPushgatewayProperties = pushgatewayProperties;
     this.exporterOpenTelemetryProperties = otelConfig;
+    this.namingProperties = namingProperties;
   }
 
   /**
@@ -100,6 +103,10 @@ public ExporterOpenTelemetryProperties getExporterOpenTelemetryProperties() {
     return exporterOpenTelemetryProperties;
   }
 
+  public NamingProperties getNamingProperties() {
+    return namingProperties;
+  }
+
   public static class Builder {
     private MetricsProperties defaultMetricsProperties;
     private Map<String, MetricsProperties> metricProperties = new HashMap<>();
@@ -109,6 +116,7 @@ public static class Builder {
     private ExporterHttpServerProperties exporterHttpServerProperties;
     private ExporterPushgatewayProperties pushgatewayProperties;
     private ExporterOpenTelemetryProperties otelConfig;
+    private NamingProperties namingProperties;
 
     private Builder() {}
 
@@ -160,6 +168,11 @@ public Builder exporterOpenTelemetryProperties(
       return this;
     }
 
+    public Builder namingProperties(NamingProperties namingProperties) {
+      this.namingProperties = namingProperties;
+      return this;
+    }
+
     public PrometheusProperties build() {
       return new PrometheusProperties(
           defaultMetricsProperties,
@@ -169,7 +182,8 @@ public PrometheusProperties build() {
           exporterFilterProperties,
           exporterHttpServerProperties,
           pushgatewayProperties,
-          otelConfig);
+          otelConfig,
+          namingProperties);
     }
   }
 }

prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusPropertiesLoader.java

@@ -42,6 +42,7 @@ public static PrometheusProperties load(Map<Object, Object> externalProperties)
         ExporterPushgatewayProperties.load(properties);
     ExporterOpenTelemetryProperties exporterOpenTelemetryProperties =
         ExporterOpenTelemetryProperties.load(properties);
+    NamingProperties namingProperties = NamingProperties.load(properties);
     validateAllPropertiesProcessed(properties);
     return new PrometheusProperties(
         defaultMetricsProperties,
@@ -51,7 +52,8 @@ public static PrometheusProperties load(Map<Object, Object> externalProperties)
         exporterFilterProperties,
         exporterHttpServerProperties,
         exporterPushgatewayProperties,
-        exporterOpenTelemetryProperties);
+        exporterOpenTelemetryProperties,
+        namingProperties);
   }
 
   // This will remove entries from properties when they are processed.

prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ValidationScheme.java

@@ -0,0 +1,16 @@
+package io.prometheus.metrics.config;
+
+/**
+ * ValidationScheme is an enum for determining how metric and label names will be validated by this
+ * library.
+ */
+public enum ValidationScheme {
+  /**
+   * LEGACY_VALIDATION is a setting that requires that metric and label names conform to the
+   * original character requirements.
+   */
+  LEGACY_VALIDATION,
+
+  /** UTF_8_VALIDATION only requires that metric and label names be valid UTF-8 strings. */
+  UTF_8_VALIDATION
+}

prometheus-metrics-config/src/test/java/io/prometheus/metrics/config/NamingPropertiesTest.java

@@ -0,0 +1,29 @@
+package io.prometheus.metrics.config;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+
+import org.junit.jupiter.api.Test;
+
+class NamingPropertiesTest {
+  @Test
+  void testBuilder() {
+    NamingProperties properties =
+        NamingProperties.builder().validation(ValidationScheme.UTF_8_VALIDATION).build();
+    assertThat(properties.getValidationScheme()).isEqualTo(ValidationScheme.UTF_8_VALIDATION);
+  }
+
+  @Test
+  void parseValidationScheme() {
+    assertThat(NamingProperties.parseValidationScheme("utf-8"))
+        .isEqualTo(ValidationScheme.UTF_8_VALIDATION);
+    assertThat(NamingProperties.parseValidationScheme("legacy"))
+        .isEqualTo(ValidationScheme.LEGACY_VALIDATION);
+    assertThat(NamingProperties.parseValidationScheme(null))
+        .isEqualTo(ValidationScheme.LEGACY_VALIDATION);
+    assertThatCode(() -> NamingProperties.parseValidationScheme("unknown"))
+        .isInstanceOf(PrometheusPropertiesException.class)
+        .hasMessageContaining(
+            "Unknown validation scheme: unknown. Valid values are: utf-8, legacy.");
+  }
+}

prometheus-metrics-config/src/test/java/io/prometheus/metrics/config/PrometheusPropertiesTest.java

@@ -4,6 +4,7 @@
 
 import java.io.IOException;
 import java.io.InputStream;
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.Properties;
 import org.junit.jupiter.api.Test;
@@ -37,15 +38,20 @@ public void testBuilder() {
     PrometheusProperties defaults = PrometheusPropertiesLoader.load(new HashMap<>());
     PrometheusProperties.Builder builder = PrometheusProperties.builder();
     builder.defaultMetricsProperties(defaults.getDefaultMetricProperties());
+    builder.metricProperties(
+        Collections.singletonMap(
+            "http_duration_seconds",
+            MetricsProperties.builder().histogramClassicUpperBounds(0.1, 0.2, 0.5, 1.0).build()));
     builder.exemplarProperties(defaults.getExemplarProperties());
     builder.defaultMetricsProperties(defaults.getDefaultMetricProperties());
     builder.exporterFilterProperties(defaults.getExporterFilterProperties());
     builder.exporterHttpServerProperties(defaults.getExporterHttpServerProperties());
     builder.exporterOpenTelemetryProperties(defaults.getExporterOpenTelemetryProperties());
     builder.pushgatewayProperties(defaults.getExporterPushgatewayProperties());
+    builder.exporterProperties(defaults.getExporterProperties());
+    builder.namingProperties(defaults.getNamingProperties());
     PrometheusProperties result = builder.build();
     assertThat(result.getDefaultMetricProperties()).isSameAs(defaults.getDefaultMetricProperties());
-    assertThat(result.getDefaultMetricProperties()).isSameAs(defaults.getDefaultMetricProperties());
     assertThat(result.getExemplarProperties()).isSameAs(defaults.getExemplarProperties());
     assertThat(result.getExporterFilterProperties())
         .isSameAs(defaults.getExporterFilterProperties());
@@ -55,5 +61,12 @@ public void testBuilder() {
         .isSameAs(defaults.getExporterOpenTelemetryProperties());
     assertThat(result.getExporterPushgatewayProperties())
         .isSameAs(defaults.getExporterPushgatewayProperties());
+    assertThat(result.getMetricProperties("http_duration_seconds"))
+        .usingRecursiveComparison()
+        .isEqualTo(
+            MetricsProperties.builder().histogramClassicUpperBounds(0.1, 0.2, 0.5, 1.0).build());
+    assertThat(result.getMetricProperties("unknown_metric")).isNull();
+    assertThat(result.getExporterProperties()).isSameAs(defaults.getExporterProperties());
+    assertThat(result.getNamingProperties()).isSameAs(defaults.getNamingProperties());
   }
 }

prometheus-metrics-core/src/test/java/io/prometheus/metrics/core/metrics/HistogramTest.java

@@ -13,12 +13,7 @@
 import io.prometheus.metrics.expositionformats.generated.com_google_protobuf_4_31_1.Metrics;
 import io.prometheus.metrics.expositionformats.internal.PrometheusProtobufWriterImpl;
 import io.prometheus.metrics.expositionformats.internal.ProtobufUtil;
-import io.prometheus.metrics.model.snapshots.ClassicHistogramBucket;
-import io.prometheus.metrics.model.snapshots.Exemplar;
-import io.prometheus.metrics.model.snapshots.Exemplars;
-import io.prometheus.metrics.model.snapshots.HistogramSnapshot;
-import io.prometheus.metrics.model.snapshots.Labels;
-import io.prometheus.metrics.model.snapshots.MetricSnapshots;
+import io.prometheus.metrics.model.snapshots.*;
 import io.prometheus.metrics.tracer.common.SpanContext;
 import io.prometheus.metrics.tracer.initializer.SpanContextSupplier;
 import java.io.ByteArrayOutputStream;
@@ -952,7 +947,7 @@ public void testDefaults() throws IOException {
     // text
     ByteArrayOutputStream out = new ByteArrayOutputStream();
     OpenMetricsTextFormatWriter writer = new OpenMetricsTextFormatWriter(false, true);
-    writer.write(out, MetricSnapshots.of(snapshot));
+    writer.write(out, MetricSnapshots.of(snapshot), EscapingScheme.NO_ESCAPING);
     assertThat(out).hasToString(expectedTextFormat);
   }
 

prometheus-metrics-core/src/test/java/io/prometheus/metrics/core/metrics/InfoTest.java

@@ -7,6 +7,7 @@
 import io.prometheus.metrics.expositionformats.generated.com_google_protobuf_4_31_1.Metrics;
 import io.prometheus.metrics.expositionformats.internal.PrometheusProtobufWriterImpl;
 import io.prometheus.metrics.expositionformats.internal.ProtobufUtil;
+import io.prometheus.metrics.model.snapshots.EscapingScheme;
 import io.prometheus.metrics.model.snapshots.Labels;
 import io.prometheus.metrics.model.snapshots.MetricSnapshots;
 import io.prometheus.metrics.model.snapshots.Unit;
@@ -126,7 +127,7 @@ public void testConstLabelsDuplicate2() {
   private void assertTextFormat(String expected, Info info) throws IOException {
     OpenMetricsTextFormatWriter writer = new OpenMetricsTextFormatWriter(true, true);
     ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
-    writer.write(outputStream, MetricSnapshots.of(info.collect()));
+    writer.write(outputStream, MetricSnapshots.of(info.collect()), EscapingScheme.NO_ESCAPING);
     String result = outputStream.toString(StandardCharsets.UTF_8.name());
     if (!result.contains(expected)) {
       throw new AssertionError(expected + " is not contained in the following output:\n" + result);