[Exporter.Prometheus] Add allow-utf-8 escaping

src/OpenTelemetry.Exporter.Prometheus.AspNetCore/CHANGELOG.md

@@ -31,6 +31,10 @@ Notes](../../RELEASENOTES.md).
   disable the `target_info` metric in Prometheus metrics. Defaults to `true`.
   ([#7438](https://github.com/open-telemetry/opentelemetry-dotnet/pull/7438))
 
+* Added support for the `allow-utf-8` Prometheus UTF-8 name escaping scheme
+  when negotiated via the `Accept` header.
+  ([#7440](https://github.com/open-telemetry/opentelemetry-dotnet/pull/7440))
+
 ## 1.16.0-beta.1
 
 Released 2026-Jun-10

src/OpenTelemetry.Exporter.Prometheus.AspNetCore/PrometheusExporterMiddleware.cs

@@ -248,24 +248,11 @@ private static bool TryParse(
 
                 if (escapedValue == null || !supportedEscapingSchemes.Contains(escapedValue))
                 {
-                    // TODO Support other escaping schemes, including at least "allow-utf-8".
-                    // For now we treat "allow-utf-8" as if it were "underscores" to avoid fallback
-                    // to PrometheusText0.0.4 where it would previously match to OpenMetricsText1.0.0.
-                    // See https://github.com/open-telemetry/opentelemetry-dotnet/issues/7246.
-                    if (string.Equals(escapedValue, PrometheusProtocol.AllowUtf8Escaping, StringComparison.Ordinal))
-                    {
-                        escaping = PrometheusProtocol.UnderscoresEscaping;
-                    }
-                    else
-                    {
-                        // Unsupported escaping scheme
-                        return false;
-                    }
-                }
-                else
-                {
-                    escaping = escapedValue;
+                    // Unsupported escaping scheme
+                    return false;
                 }
+
+                escaping = escapedValue;
             }
         }
 

src/OpenTelemetry.Exporter.Prometheus.HttpListener/CHANGELOG.md

@@ -37,6 +37,10 @@ Notes](../../RELEASENOTES.md).
 * Added the `PrometheusHttpListenerOptions.ConfigureHttpListener` option.
   ([#7448](https://github.com/open-telemetry/opentelemetry-dotnet/pull/7448))
 
+* Added support for the `allow-utf-8` Prometheus UTF-8 name escaping scheme
+  when negotiated via the `Accept` header.
+  ([#7440](https://github.com/open-telemetry/opentelemetry-dotnet/pull/7440))
+
 ## 1.16.0-beta.1
 
 Released 2026-Jun-10

src/OpenTelemetry.Exporter.Prometheus.HttpListener/Internal/PrometheusHeadersParser.cs

@@ -160,18 +160,7 @@ internal static PrometheusProtocol Negotiate(string? contentType)
         var trimmed = TrimQuotes(value);
         var escaping = trimmed.ToString();
 
-        if (PrometheusProtocol.SupportedEscapingSchemes.Contains(escaping))
-        {
-            return escaping;
-        }
-
-        // TODO Support other escaping schemes, including at least "allow-utf-8".
-        // For now we treat "allow-utf-8" as if it were "underscores" to avoid fallback
-        // to PrometheusText0.0.4 where it would previously match to OpenMetricsText1.0.0.
-        // See https://github.com/open-telemetry/opentelemetry-dotnet/issues/7246.
-        return string.Equals(escaping, PrometheusProtocol.AllowUtf8Escaping, StringComparison.Ordinal)
-            ? PrometheusProtocol.UnderscoresEscaping
-            : null;
+        return PrometheusProtocol.SupportedEscapingSchemes.Contains(escaping) ? escaping : null;
     }
 
     private static ReadOnlySpan<char> SplitNext(ref ReadOnlySpan<char> span, char character)

src/OpenTelemetry.Exporter.Prometheus.HttpListener/Internal/Shared/EscapingScheme.cs

@@ -27,4 +27,11 @@ internal enum EscapingScheme
     /// characters are encoded as their hexadecimal Unicode code point.
     /// </summary>
     Values,
+
+    /// <summary>
+    /// Names are not escaped and are emitted as UTF-8. Names that are not valid legacy
+    /// names are written using the quoted exposition format (the name is moved inside
+    /// the label braces as a double-quoted string and non-legacy label names are quoted).
+    /// </summary>
+    AllowUtf8,
 }

src/OpenTelemetry.Exporter.Prometheus.HttpListener/Internal/Shared/PrometheusEscaping.cs

@@ -25,6 +25,7 @@ internal static class PrometheusEscaping
 
     public static EscapingScheme FromString(string? escaping) => escaping switch
     {
+        PrometheusProtocol.AllowUtf8Escaping => EscapingScheme.AllowUtf8,
         PrometheusProtocol.DotsEscaping => EscapingScheme.Dots,
         PrometheusProtocol.ValuesEscaping => EscapingScheme.Values,
         _ => EscapingScheme.Underscores,
@@ -45,7 +46,9 @@ internal static class PrometheusEscaping
     /// <returns>The escaped name. Always a valid legacy (ASCII) name for the dots and values schemes.</returns>
     public static string EscapeName(string name, EscapingScheme scheme, bool isMetricName = true)
     {
-        if (string.IsNullOrEmpty(name) || scheme == EscapingScheme.Underscores)
+        // The underscores scheme is handled by the OpenTelemetry sanitization, and the allow-utf-8
+        // scheme keeps the name unchanged, so neither is escaped here.
+        if (string.IsNullOrEmpty(name) || scheme is EscapingScheme.AllowUtf8 or EscapingScheme.Underscores)
         {
             return name;
         }
@@ -148,15 +151,31 @@ public static int EscapeName(byte[] buffer, int cursor, string name, EscapingSch
         return cursor;
     }
 
-    private static bool CanWriteValuesNameUnchanged(string name, bool isMetricName)
-    {
-        // A pre-existing "U__" prefix must itself be encoded; otherwise a name such as
-        // "U__foo_2e_bar" collides with the values encoding of "foo.bar".
-        return IsValidLegacyName(name, isMetricName) && !name.StartsWith(ValuesPrefix, StringComparison.Ordinal);
-    }
+    /// <summary>
+    /// Returns whether the specified metric name matches the legacy metric name pattern <c>[a-zA-Z_:][a-zA-Z0-9_:]*</c>.
+    /// </summary>
+    /// <param name="name">The metric name to validate.</param>
+    /// <returns>
+    /// <see langword="true"/> if the name is a valid legacy metric name; otherwise, <see langword="false"/>.
+    /// </returns>
+    internal static bool IsValidLegacyName(string name) => IsValidLegacyName(name, isMetricName: true);
+
+    /// <summary>
+    /// Returns whether the specified label name matches the legacy label name pattern <c>[a-zA-Z_][a-zA-Z0-9_]*</c>.
+    /// </summary>
+    /// <param name="name">The label name to validate.</param>
+    /// <returns>
+    /// <see langword="true"/> if the name is a valid legacy label name; otherwise, <see langword="false"/>.
+    /// </returns>
+    internal static bool IsValidLegacyLabelName(string name) => IsValidLegacyName(name, isMetricName: false);
 
     private static bool IsValidLegacyName(string name, bool isMetricName)
     {
+        if (name.Length == 0)
+        {
+            return false;
+        }
+
         var index = 0;
 
         while (index < name.Length)
@@ -219,6 +238,11 @@ private static int GetCodePoint(string value, int index, out int charsConsumed,
 #endif
     }
 
+    // A pre-existing "U__" prefix must itself be encoded; otherwise a name such as
+    // "U__foo_2e_bar" collides with the values encoding of "foo.bar".
+    private static bool CanWriteValuesNameUnchanged(string name, bool isMetricName)
+        => IsValidLegacyName(name, isMetricName) && !name.StartsWith(ValuesPrefix, StringComparison.Ordinal);
+
     private static int WriteAscii(byte[] buffer, int cursor, string value)
     {
         for (var i = 0; i < value.Length; i++)

src/OpenTelemetry.Exporter.Prometheus.HttpListener/Internal/Shared/PrometheusMetric.cs

@@ -12,6 +12,7 @@ internal sealed class PrometheusMetric
     private readonly string rawName;
     private readonly bool disableTotalNameSuffixForCounters;
     private readonly NameSet underscoreNames;
+    private NameSet? allowUtf8Names;
     private NameSet? dotsNames;
     private NameSet? valuesNames;
 
@@ -235,6 +236,7 @@ UpDownCounter becomes gauge
     /// <returns>The metric name set for the requested escaping scheme.</returns>
     internal NameSet GetNameSet(EscapingScheme escaping) => escaping switch
     {
+        EscapingScheme.AllowUtf8 => this.allowUtf8Names ??= BuildAllowUtf8Names(this.rawName, this.Unit, this.Type, this.disableTotalNameSuffixForCounters),
         EscapingScheme.Dots => this.dotsNames ??= BuildEscapedNames(this.rawName, this.Unit, this.Type, this.disableTotalNameSuffixForCounters, EscapingScheme.Dots),
         EscapingScheme.Values => this.valuesNames ??= BuildEscapedNames(this.rawName, this.Unit, this.Type, this.disableTotalNameSuffixForCounters, EscapingScheme.Values),
         _ => this.underscoreNames,
@@ -367,6 +369,51 @@ private static NameSet BuildEscapedNames(
         return new(escapedName, openMetricsName, openMetricsMetadataName);
     }
 
+    private static NameSet BuildAllowUtf8Names(string name, string? sanitizedUnit, PrometheusType type, bool disableTotalNameSuffixForCounters)
+    {
+        // The allow-utf-8 scheme does not escape the name; the original UTF-8 name is kept and only
+        // the unit and the structural '_total' suffix are appended. The family name determines
+        // whether the quoted exposition format is required (the structural suffixes are legacy
+        // characters and so do not affect the legacy validity of the family).
+        var nameFamily = name;
+        var openMetricsFamily = type == PrometheusType.Counter
+            ? RemoveOpenMetricsCounterNameSuffix(name)
+            : name;
+
+        if (sanitizedUnit != null)
+        {
+            // Each name is checked independently: openMetricsFamily has the _total counter
+            // suffix stripped, so it may already end with the unit even when nameFamily
+            // (which still carries _total) does not. For counter nameFamily, also check for
+            // the unit immediately before _total (e.g. "db_bytes_total" with unit "bytes").
+            if (!nameFamily.EndsWith(sanitizedUnit, StringComparison.Ordinal) &&
+                (type != PrometheusType.Counter || !nameFamily.EndsWith($"{sanitizedUnit}_total", StringComparison.Ordinal)))
+            {
+                nameFamily += $"_{sanitizedUnit}";
+            }
+
+            if (!openMetricsFamily.EndsWith(sanitizedUnit, StringComparison.Ordinal))
+            {
+                openMetricsFamily += $"_{sanitizedUnit}";
+            }
+        }
+
+        var metricName = nameFamily;
+
+        if (type == PrometheusType.Counter && !nameFamily.EndsWith("_total", StringComparison.Ordinal) && !disableTotalNameSuffixForCounters)
+        {
+            metricName += "_total";
+        }
+
+        var openMetricsName = type == PrometheusType.Counter && !openMetricsFamily.EndsWith("_total", StringComparison.Ordinal)
+            ? openMetricsFamily + "_total"
+            : openMetricsFamily;
+
+        var isLegacyValid = PrometheusEscaping.IsValidLegacyName(nameFamily);
+
+        return new(metricName, openMetricsName, openMetricsFamily, isLegacyValid, encodeUtf8: true);
+    }
+
     private static string RemoveOpenMetricsCounterNameSuffix(string metricName)
         => metricName.EndsWith("_total", StringComparison.Ordinal) ? metricName.Substring(0, metricName.Length - 6) : metricName;
 
@@ -482,14 +529,15 @@ private static bool TryProcessRateUnits(string updatedUnit, [NotNullWhen(true)]
     /// </summary>
     internal sealed class NameSet
     {
-        public NameSet(string name, string openMetricsName, string openMetricsMetadataName)
+        public NameSet(string name, string openMetricsName, string openMetricsMetadataName, bool isLegacyValid = true, bool encodeUtf8 = false)
         {
             this.Name = name;
             this.OpenMetricsName = openMetricsName;
             this.OpenMetricsMetadataName = openMetricsMetadataName;
-            this.NameBytes = ConvertToBytes(name);
-            this.OpenMetricsNameBytes = ConvertToBytes(openMetricsName);
-            this.OpenMetricsMetadataNameBytes = ConvertToBytes(openMetricsMetadataName);
+            this.IsLegacyValid = isLegacyValid;
+            this.NameBytes = ToBytes(name, encodeUtf8);
+            this.OpenMetricsNameBytes = ToBytes(openMetricsName, encodeUtf8);
+            this.OpenMetricsMetadataNameBytes = ToBytes(openMetricsMetadataName, encodeUtf8);
         }
 
         public string Name { get; }
@@ -498,10 +546,22 @@ public NameSet(string name, string openMetricsName, string openMetricsMetadataNa
 
         public string OpenMetricsMetadataName { get; }
 
+        /// <summary>
+        /// Gets a value indicating whether the metric name is a valid legacy name.
+        /// </summary>
+        /// <remarks>
+        /// When <see langword="false"/> (only possible for the <c>allow-utf-8 scheme</c>)
+        /// the quoted exposition format is required.
+        /// </remarks>
+        public bool IsLegacyValid { get; }
+
         public byte[] NameBytes { get; }
 
         public byte[] OpenMetricsNameBytes { get; }
 
         public byte[] OpenMetricsMetadataNameBytes { get; }
+
+        private static byte[] ToBytes(string value, bool encodeUtf8)
+            => encodeUtf8 ? Encoding.UTF8.GetBytes(value) : ConvertToBytes(value);
     }
 }

src/OpenTelemetry.Exporter.Prometheus.HttpListener/Internal/Shared/PrometheusProtocol.cs

@@ -32,10 +32,9 @@ namespace OpenTelemetry.Exporter.Prometheus;
 
     public static readonly PrometheusProtocol Fallback = new(PrometheusTextMediaType, null, PrometheusV0, false);
 
-    // TODO Support the "allow-utf-8" escaping scheme.
-    // See https://github.com/open-telemetry/opentelemetry-dotnet/issues/7246.
     internal static readonly SupportedEscapingSchemes SupportedEscapingSchemes =
     [
+        AllowUtf8Escaping,
         DotsEscaping,
         UnderscoresEscaping,
         ValuesEscaping,

src/OpenTelemetry.Exporter.Prometheus.HttpListener/Internal/Shared/Serialization/OpenMetricsSerializer.cs

@@ -164,8 +164,7 @@ private int WriteCreatedMetric(
         in TextFormatSerializerOptions options,
         IReadOnlyCollection<string>? reservedOutputKeys = null)
     {
-        cursor = this.WriteMetricNameWithSuffix(buffer, cursor, prometheusMetric, "_created");
-        cursor = this.WriteTags(buffer, cursor, metric, metricPoint.Tags, options, reservedOutputKeys: reservedOutputKeys);
+        cursor = this.WriteSeriesAndTags(buffer, cursor, metric, prometheusMetric, metricPoint.Tags, options, "_created", reservedOutputKeys);
 
         buffer[cursor++] = unchecked((byte)' ');
 

src/OpenTelemetry.Exporter.Prometheus.HttpListener/Internal/Shared/Serialization/OpenMetricsV1Serializer.cs

@@ -1,9 +1,37 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+using OpenTelemetry.Metrics;
+
 namespace OpenTelemetry.Exporter.Prometheus.Serialization;
 
 internal sealed class OpenMetricsV1Serializer : OpenMetricsSerializer
 {
-    // Version-specific behaviour will be added here later
+    internal override int WriteMetricMetadataName(byte[] buffer, int cursor, PrometheusMetric metric) =>
+        this.RequiresQuotedName(metric)
+            ? WriteQuotedMetadataName(buffer, cursor, this.GetMetricMetadataNameBytes(metric))
+            : base.WriteMetricMetadataName(buffer, cursor, metric);
+
+    internal override int WriteSeriesAndTags(
+        byte[] buffer,
+        int cursor,
+        Metric metric,
+        PrometheusMetric prometheusMetric,
+        ReadOnlyTagCollection tags,
+        in TextFormatSerializerOptions options,
+        string? suffix,
+        IReadOnlyCollection<string>? reservedOutputKeys) =>
+        this.RequiresQuotedName(prometheusMetric)
+            ? this.WriteQuotedSeriesAndTags(buffer, cursor, metric, prometheusMetric, tags, options, suffix, reservedOutputKeys)
+            : base.WriteSeriesAndTags(buffer, cursor, metric, prometheusMetric, tags, options, suffix, reservedOutputKeys);
+
+    internal override int WriteHistogramBucketName(byte[] buffer, int cursor, PrometheusMetric metric) =>
+        this.RequiresQuotedName(metric)
+            ? WriteQuotedBucketName(buffer, cursor, this.GetMetricMetadataNameBytes(metric))
+            : base.WriteHistogramBucketName(buffer, cursor, metric);
+
+    internal override int WriteSeriesNameAndSerializedTags(byte[] buffer, int cursor, PrometheusMetric metric, string suffix, ReadOnlySpan<byte> serializedTags) =>
+        this.RequiresQuotedName(metric)
+            ? WriteQuotedSeriesNameAndSerializedTags(buffer, cursor, this.GetMetricMetadataNameBytes(metric), suffix, serializedTags)
+            : base.WriteSeriesNameAndSerializedTags(buffer, cursor, metric, suffix, serializedTags);
 }

src/OpenTelemetry.Exporter.Prometheus.HttpListener/Internal/Shared/Serialization/PrometheusTextV1Serializer.cs

@@ -1,9 +1,37 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+using OpenTelemetry.Metrics;
+
 namespace OpenTelemetry.Exporter.Prometheus.Serialization;
 
 internal sealed class PrometheusTextV1Serializer : PrometheusTextSerializer
 {
-    // Version-specific behaviour will be added here later
+    internal override int WriteMetricMetadataName(byte[] buffer, int cursor, PrometheusMetric metric) =>
+        this.RequiresQuotedName(metric)
+            ? WriteQuotedMetadataName(buffer, cursor, this.GetMetricMetadataNameBytes(metric))
+            : base.WriteMetricMetadataName(buffer, cursor, metric);
+
+    internal override int WriteSeriesAndTags(
+        byte[] buffer,
+        int cursor,
+        Metric metric,
+        PrometheusMetric prometheusMetric,
+        ReadOnlyTagCollection tags,
+        in TextFormatSerializerOptions options,
+        string? suffix,
+        IReadOnlyCollection<string>? reservedOutputKeys) =>
+        this.RequiresQuotedName(prometheusMetric)
+            ? this.WriteQuotedSeriesAndTags(buffer, cursor, metric, prometheusMetric, tags, options, suffix, reservedOutputKeys)
+            : base.WriteSeriesAndTags(buffer, cursor, metric, prometheusMetric, tags, options, suffix, reservedOutputKeys);
+
+    internal override int WriteHistogramBucketName(byte[] buffer, int cursor, PrometheusMetric metric) =>
+        this.RequiresQuotedName(metric)
+            ? WriteQuotedBucketName(buffer, cursor, this.GetMetricMetadataNameBytes(metric))
+            : base.WriteHistogramBucketName(buffer, cursor, metric);
+
+    internal override int WriteSeriesNameAndSerializedTags(byte[] buffer, int cursor, PrometheusMetric metric, string suffix, ReadOnlySpan<byte> serializedTags) =>
+        this.RequiresQuotedName(metric)
+            ? WriteQuotedSeriesNameAndSerializedTags(buffer, cursor, this.GetMetricMetadataNameBytes(metric), suffix, serializedTags)
+            : base.WriteSeriesNameAndSerializedTags(buffer, cursor, metric, suffix, serializedTags);
 }