UTF-8 support in metric and label names

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

@@ -0,0 +1,43 @@
+package io.prometheus.metrics.config;
+
+import java.util.Map;
+
+public class NamingProperties {
+
+ private static final String VALIDATION_SCHEME = "validationScheme";
+ private final String validationScheme;
+
+ private NamingProperties(String validation) {
+ this.validationScheme = validation;
+ }
+
+ public String getValidationScheme() {
+ return validationScheme;
+ }
+
+ static NamingProperties load(String prefix, Map<Object, Object> properties) throws PrometheusPropertiesException {
+ String validationScheme = Util.loadString(prefix + "." + VALIDATION_SCHEME, properties);
+ return new NamingProperties(validationScheme);
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public static class Builder {
+
+ private String validationScheme;
+
+ private Builder() {}
+
+ public Builder validation(String 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

@@ -19,6 +19,7 @@ public class PrometheusProperties {
  private final ExporterFilterProperties exporterFilterProperties;
  private final ExporterHttpServerProperties exporterHttpServerProperties;
  private final ExporterOpenTelemetryProperties exporterOpenTelemetryProperties;
+ private final NamingProperties namingProperties;
 
  /**
  * Get the properties instance. When called for the first time, {@code get()} loads the properties from the following locations:
@@ -39,14 +40,16 @@ public PrometheusProperties(
  ExporterProperties exporterProperties,
  ExporterFilterProperties exporterFilterProperties,
  ExporterHttpServerProperties httpServerConfig,
- ExporterOpenTelemetryProperties otelConfig) {
+ ExporterOpenTelemetryProperties otelConfig,
+ NamingProperties namingProperties) {
  this.defaultMetricsProperties = defaultMetricsProperties;
  this.metricProperties.putAll(metricProperties);
  this.exemplarProperties = exemplarProperties;
  this.exporterProperties = exporterProperties;
  this.exporterFilterProperties = exporterFilterProperties;
  this.exporterHttpServerProperties = httpServerConfig;
  this.exporterOpenTelemetryProperties = otelConfig;
+ this.namingProperties = namingProperties;
  }
 
  /**
@@ -83,4 +86,8 @@ public ExporterHttpServerProperties getExporterHttpServerProperties() {
  public ExporterOpenTelemetryProperties getExporterOpenTelemetryProperties() {
  return exporterOpenTelemetryProperties;
  }
+
+ public NamingProperties getNamingProperties() {
+ return namingProperties;
+ }
 }

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

@@ -33,8 +33,9 @@ public static PrometheusProperties load() throws PrometheusPropertiesException {
  ExporterFilterProperties exporterFilterProperties = ExporterFilterProperties.load("io.prometheus.exporter.filter", properties);
  ExporterHttpServerProperties exporterHttpServerProperties = ExporterHttpServerProperties.load("io.prometheus.exporter.httpServer", properties);
  ExporterOpenTelemetryProperties exporterOpenTelemetryProperties = ExporterOpenTelemetryProperties.load("io.prometheus.exporter.opentelemetry", properties);
+ NamingProperties namingProperties = NamingProperties.load("io.prometheus.naming", properties);
  validateAllPropertiesProcessed(properties);
- return new PrometheusProperties(defaultMetricsProperties, metricsConfigs, exemplarConfig, exporterProperties, exporterFilterProperties, exporterHttpServerProperties, exporterOpenTelemetryProperties);
+ return new PrometheusProperties(defaultMetricsProperties, metricsConfigs, exemplarConfig, exporterProperties, exporterFilterProperties, exporterHttpServerProperties, exporterOpenTelemetryProperties, namingProperties);
  }
 
  // This will remove entries from properties when they are processed.

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

@@ -1,17 +1,12 @@
 package io.prometheus.metrics.core.metrics;
 
+import io.prometheus.metrics.model.snapshots.*;
 import io.prometheus.metrics.shaded.com_google_protobuf_3_21_7.TextFormat;
 import io.prometheus.metrics.core.datapoints.DistributionDataPoint;
 import io.prometheus.metrics.core.exemplars.ExemplarSamplerConfigTestUtil;
 import io.prometheus.metrics.expositionformats.OpenMetricsTextFormatWriter;
 import io.prometheus.metrics.expositionformats.PrometheusProtobufWriter;
 import io.prometheus.metrics.expositionformats.generated.com_google_protobuf_3_21_7.Metrics;
-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.tracer.common.SpanContext;
 import io.prometheus.metrics.tracer.initializer.SpanContextSupplier;
 import org.junit.After;
@@ -723,7 +718,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);
  Assert.assertEquals(expectedTextFormat, out.toString());
  }
 

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

@@ -1,6 +1,7 @@
 package io.prometheus.metrics.core.metrics;
 
 import io.prometheus.metrics.expositionformats.OpenMetricsTextFormatWriter;
+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.shaded.com_google_protobuf_3_21_7.TextFormat;
@@ -98,7 +99,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);

prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusScrapeHandler.java

@@ -6,6 +6,7 @@
 import io.prometheus.metrics.expositionformats.ExpositionFormats;
 import io.prometheus.metrics.model.registry.MetricNameFilter;
 import io.prometheus.metrics.model.registry.PrometheusRegistry;
+import io.prometheus.metrics.model.snapshots.EscapingScheme;
 import io.prometheus.metrics.model.snapshots.MetricSnapshots;
 
 import java.io.ByteArrayOutputStream;
@@ -51,15 +52,16 @@ public void handleRequest(PrometheusHttpExchange exchange) throws IOException {
  PrometheusHttpRequest request = exchange.getRequest();
  PrometheusHttpResponse response = exchange.getResponse();
  MetricSnapshots snapshots = scrape(request);
- if (writeDebugResponse(snapshots, exchange)) {
+ String acceptHeader = request.getHeader("Accept");
+ EscapingScheme escapingScheme = EscapingScheme.fromAcceptHeader(acceptHeader);
+ if (writeDebugResponse(snapshots, exchange, escapingScheme)) {
  return;
  }
  ByteArrayOutputStream responseBuffer = new ByteArrayOutputStream(lastResponseSize.get() + 1024);
- String acceptHeader = request.getHeader("Accept");
  ExpositionFormatWriter writer = expositionFormats.findWriter(acceptHeader);
- writer.write(responseBuffer, snapshots);
+ writer.write(responseBuffer, snapshots, escapingScheme);
  lastResponseSize.set(responseBuffer.size());
- response.setHeader("Content-Type", writer.getContentType());
+ response.setHeader("Content-Type", writer.getContentType() + escapingScheme.toHeaderFormat());
 
  if (shouldUseCompression(request)) {
  response.setHeader("Content-Encoding", "gzip");
@@ -126,7 +128,7 @@ private Predicate<String> makeNameFilter(String[] includedNames) {
  return result;
  }
 
- private boolean writeDebugResponse(MetricSnapshots snapshots, PrometheusHttpExchange exchange) throws IOException {
+ private boolean writeDebugResponse(MetricSnapshots snapshots, PrometheusHttpExchange exchange, EscapingScheme escapingScheme) throws IOException {
  String debugParam = exchange.getRequest().getParameter("debug");
  PrometheusHttpResponse response = exchange.getResponse();
  if (debugParam == null) {
@@ -138,10 +140,10 @@ private boolean writeDebugResponse(MetricSnapshots snapshots, PrometheusHttpExch
  OutputStream body = response.sendHeadersAndGetBody(responseStatus, 0);
  switch (debugParam) {
  case "openmetrics":
- expositionFormats.getOpenMetricsTextFormatWriter().write(body, snapshots);
+ expositionFormats.getOpenMetricsTextFormatWriter().write(body, snapshots, escapingScheme);
  break;
  case "text":
- expositionFormats.getPrometheusTextFormatWriter().write(body, snapshots);
+ expositionFormats.getPrometheusTextFormatWriter().write(body, snapshots, escapingScheme);
  break;
  case "prometheus-protobuf":
  String debugString = expositionFormats.getPrometheusProtobufWriter().toDebugString(snapshots);

prometheus-metrics-exposition-formats/src/main/java/io/prometheus/metrics/expositionformats/ExpositionFormatWriter.java

@@ -1,5 +1,6 @@
 package io.prometheus.metrics.expositionformats;
 
+import io.prometheus.metrics.model.snapshots.EscapingScheme;
 import io.prometheus.metrics.model.snapshots.MetricSnapshots;
 
 import java.io.IOException;
@@ -11,6 +12,6 @@ public interface ExpositionFormatWriter {
  /**
  * Text formats use UTF-8 encoding.
  */
- void write(OutputStream out, MetricSnapshots metricSnapshots) throws IOException;
+ void write(OutputStream out, MetricSnapshots metricSnapshots, EscapingScheme escapingScheme) throws IOException;
  String getContentType();
 }

prometheus-metrics-exposition-formats/src/main/java/io/prometheus/metrics/expositionformats/OpenMetricsTextFormatWriter.java

@@ -1,34 +1,14 @@
 package io.prometheus.metrics.expositionformats;
 
-import io.prometheus.metrics.model.snapshots.ClassicHistogramBuckets;
-import io.prometheus.metrics.model.snapshots.CounterSnapshot;
-import io.prometheus.metrics.model.snapshots.DataPointSnapshot;
-import io.prometheus.metrics.model.snapshots.DistributionDataPointSnapshot;
-import io.prometheus.metrics.model.snapshots.Exemplar;
-import io.prometheus.metrics.model.snapshots.Exemplars;
-import io.prometheus.metrics.model.snapshots.GaugeSnapshot;
-import io.prometheus.metrics.model.snapshots.HistogramSnapshot;
-import io.prometheus.metrics.model.snapshots.InfoSnapshot;
-import io.prometheus.metrics.model.snapshots.Labels;
-import io.prometheus.metrics.model.snapshots.MetricMetadata;
-import io.prometheus.metrics.model.snapshots.MetricSnapshot;
-import io.prometheus.metrics.model.snapshots.MetricSnapshots;
-import io.prometheus.metrics.model.snapshots.Quantile;
-import io.prometheus.metrics.model.snapshots.StateSetSnapshot;
-import io.prometheus.metrics.model.snapshots.SummarySnapshot;
-import io.prometheus.metrics.model.snapshots.UnknownSnapshot;
+import io.prometheus.metrics.model.snapshots.*;
 
 import java.io.IOException;
 import java.io.OutputStream;
 import java.io.OutputStreamWriter;
 import java.nio.charset.StandardCharsets;
 import java.util.List;
 
-import static io.prometheus.metrics.expositionformats.TextFormatUtil.writeDouble;
-import static io.prometheus.metrics.expositionformats.TextFormatUtil.writeEscapedLabelValue;
-import static io.prometheus.metrics.expositionformats.TextFormatUtil.writeLabels;
-import static io.prometheus.metrics.expositionformats.TextFormatUtil.writeLong;
-import static io.prometheus.metrics.expositionformats.TextFormatUtil.writeTimestamp;
+import static io.prometheus.metrics.expositionformats.TextFormatUtil.*;
 
 /**
  * Write the OpenMetrics text format as defined on <a href="https://openmetrics.io/">https://openmetrics.io</a>.
@@ -60,9 +40,11 @@ public String getContentType() {
  return CONTENT_TYPE;
  }
 
- public void write(OutputStream out, MetricSnapshots metricSnapshots) throws IOException {
+ public void write(OutputStream out, MetricSnapshots metricSnapshots, EscapingScheme escapingScheme) throws IOException {
  OutputStreamWriter writer = new OutputStreamWriter(out, StandardCharsets.UTF_8);
- for (MetricSnapshot snapshot : metricSnapshots) {
+ for (MetricSnapshot s : metricSnapshots) {
+ MetricSnapshot snapshot = PrometheusNaming.escapeMetricSnapshot(s, escapingScheme);
+
  if (snapshot.getDataPoints().size() > 0) {
  if (snapshot instanceof CounterSnapshot) {
  writeCounter(writer, (CounterSnapshot) snapshot);
@@ -214,15 +196,15 @@ private void writeStateSet(OutputStreamWriter writer, StateSetSnapshot snapshot)
  }
  writer.write(data.getLabels().getPrometheusName(j));
  writer.write("=\"");
-writeEscapedLabelValue(writer, data.getLabels().getValue(j));
+writeEscapedString(writer, data.getLabels().getValue(j));
  writer.write("\"");
  }
  if (!data.getLabels().isEmpty()) {
  writer.write(",");
  }
  writer.write(metadata.getPrometheusName());
  writer.write("=\"");
-writeEscapedLabelValue(writer, data.getName(i));
+writeEscapedString(writer, data.getName(i));
  writer.write("\"} ");
  if (data.isTrue(i)) {
  writer.write("1");
@@ -289,13 +271,21 @@ private void writeNameAndLabels(OutputStreamWriter writer, String name, String s
 
  private void writeNameAndLabels(OutputStreamWriter writer, String name, String suffix, Labels labels,
  String additionalLabelName, double additionalLabelValue) throws IOException {
- writer.write(name);
- if (suffix != null) {
- writer.write(suffix);
+ boolean metricInsideBraces = false;
+ // If the name does not pass the legacy validity check, we must put the
+ // metric name inside the braces.
+ if (PrometheusNaming.validateLegacyMetricName(name) != null) {
+ metricInsideBraces = true;
+ writer.write('{');
  }
+ writeName(writer, name + (suffix != null ? suffix : ""), NameType.Metric);
+
  if (!labels.isEmpty() || additionalLabelName != null) {
- writeLabels(writer, labels, additionalLabelName, additionalLabelValue);
+ writeLabels(writer, labels, additionalLabelName, additionalLabelValue, metricInsideBraces);
+ } else if (metricInsideBraces) {
+ writer.write('}');
  }
+
  writer.write(' ');
  }
 
@@ -306,7 +296,7 @@ private void writeScrapeTimestampAndExemplar(OutputStreamWriter writer, DataPoin
  }
  if (exemplar != null) {
  writer.write(" # ");
- writeLabels(writer, exemplar.getLabels(), null, 0);
+ writeLabels(writer, exemplar.getLabels(), null, 0, false);
  writer.write(' ');
  writeDouble(writer, exemplar.getValue());
  if (exemplar.hasTimestamp()) {
@@ -319,22 +309,22 @@ private void writeScrapeTimestampAndExemplar(OutputStreamWriter writer, DataPoin
 
  private void writeMetadata(OutputStreamWriter writer, String typeName, MetricMetadata metadata) throws IOException {
  writer.write("# TYPE ");
-writer.write(metadata.getPrometheusName());
+writeName(writer, metadata.getPrometheusName(), NameType.Metric);
  writer.write(' ');
  writer.write(typeName);
  writer.write('\n');
  if (metadata.getUnit() != null) {
  writer.write("# UNIT ");
-writer.write(metadata.getPrometheusName());
+writeName(writer, metadata.getPrometheusName(), NameType.Metric);
  writer.write(' ');
-writeEscapedLabelValue(writer, metadata.getUnit().toString());
+writeEscapedString(writer, metadata.getUnit().toString());
  writer.write('\n');
  }
  if (metadata.getHelp() != null && !metadata.getHelp().isEmpty()) {
  writer.write("# HELP ");
-writer.write(metadata.getPrometheusName());
+writeName(writer, metadata.getPrometheusName(), NameType.Metric);
  writer.write(' ');
-writeEscapedLabelValue(writer, metadata.getHelp());
+writeEscapedString(writer, metadata.getHelp());
  writer.write('\n');
  }
  }

prometheus-metrics-exposition-formats/src/main/java/io/prometheus/metrics/expositionformats/PrometheusProtobufWriter.java

@@ -1,24 +1,9 @@
 package io.prometheus.metrics.expositionformats;
 
+import io.prometheus.metrics.model.snapshots.*;
 import io.prometheus.metrics.shaded.com_google_protobuf_3_21_7.TextFormat;
 import io.prometheus.metrics.expositionformats.generated.com_google_protobuf_3_21_7.Metrics;
-import io.prometheus.metrics.model.snapshots.ClassicHistogramBuckets;
-import io.prometheus.metrics.model.snapshots.CounterSnapshot;
 import io.prometheus.metrics.model.snapshots.CounterSnapshot.CounterDataPointSnapshot;
-import io.prometheus.metrics.model.snapshots.Exemplar;
-import io.prometheus.metrics.model.snapshots.GaugeSnapshot;
-import io.prometheus.metrics.model.snapshots.HistogramSnapshot;
-import io.prometheus.metrics.model.snapshots.InfoSnapshot;
-import io.prometheus.metrics.model.snapshots.Labels;
-import io.prometheus.metrics.model.snapshots.DataPointSnapshot;
-import io.prometheus.metrics.model.snapshots.MetricMetadata;
-import io.prometheus.metrics.model.snapshots.MetricSnapshot;
-import io.prometheus.metrics.model.snapshots.MetricSnapshots;
-import io.prometheus.metrics.model.snapshots.NativeHistogramBuckets;
-import io.prometheus.metrics.model.snapshots.Quantiles;
-import io.prometheus.metrics.model.snapshots.StateSetSnapshot;
-import io.prometheus.metrics.model.snapshots.SummarySnapshot;
-import io.prometheus.metrics.model.snapshots.UnknownSnapshot;
 
 import java.io.IOException;
 import java.io.OutputStream;
@@ -61,7 +46,7 @@ public String toDebugString(MetricSnapshots metricSnapshots) {
  }
 
  @Override
- public void write(OutputStream out, MetricSnapshots metricSnapshots) throws IOException {
+ public void write(OutputStream out, MetricSnapshots metricSnapshots, EscapingScheme escapingScheme) throws IOException {
  for (MetricSnapshot snapshot : metricSnapshots) {
  if (snapshot.getDataPoints().size() > 0) {
  convert(snapshot).writeDelimitedTo(out);