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

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

@@ -10,6 +10,14 @@ Notes](../../RELEASENOTES.md).
 * Added a verbose-level diagnostic event for ignored metrics.
   ([#7429](https://github.com/open-telemetry/opentelemetry-dotnet/pull/7429))
 
+* Added support for the `dots` and `values` Prometheus UTF-8 name escaping
+  schemes when negotiated via the `Accept` header.
+  ([#7439](https://github.com/open-telemetry/opentelemetry-dotnet/pull/7439))
+
+* Added support for the `allow-utf-8` Prometheus UTF-8 name escaping scheme
+  when negotiated via the `Accept` header.
+  ([#TODO](https://github.com/open-telemetry/opentelemetry-dotnet/pull/TODO))
+
 ## 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

@@ -10,6 +10,14 @@ Notes](../../RELEASENOTES.md).
 * Added a verbose-level diagnostic event for ignored metrics.
   ([#7429](https://github.com/open-telemetry/opentelemetry-dotnet/pull/7429))
 
+* Added support for the `dots` and `values` Prometheus UTF-8 name escaping
+  schemes when negotiated via the `Accept` header.
+  ([#7439](https://github.com/open-telemetry/opentelemetry-dotnet/pull/7439))
+
+* Added support for the `allow-utf-8` Prometheus UTF-8 name escaping scheme
+  when negotiated via the `Accept` header.
+  ([#TODO](https://github.com/open-telemetry/opentelemetry-dotnet/pull/TODO))
+
 ## 1.16.0-beta.1
 
 Released 2026-Jun-10

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

@@ -165,18 +165,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

@@ -0,0 +1,37 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+namespace OpenTelemetry.Exporter.Prometheus;
+
+/// <summary>
+/// The Prometheus UTF-8 name escaping scheme used when rendering metric and label names.
+/// See https://prometheus.io/docs/instrumenting/escaping_schemes/.
+/// </summary>
+internal enum EscapingScheme
+{
+    /// <summary>
+    /// Discouraged characters are replaced with the <c>_</c> character. This is the
+    /// OpenTelemetry default and also covers the legacy (pre-1.0.0) text formats which
+    /// have no negotiated escaping scheme.
+    /// </summary>
+    Underscores = 0,
+
+    /// <summary>
+    /// Dots are replaced with <c>_dot_</c> and underscores are doubled, allowing the
+    /// original name to be recovered by a Prometheus client.
+    /// </summary>
+    Dots,
+
+    /// <summary>
+    /// Names that are not valid legacy names are prefixed with <c>U__</c> and discouraged
+    /// 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/PrometheusCollectionManager.cs

@@ -40,9 +40,9 @@ public PrometheusCollectionManager(PrometheusExporter exporter)
     internal Func<TimeSpan> GetElapsedTime { get; set; }
 
 #if NET
-    public ValueTask<CollectionResponse> EnterCollect(PrometheusProtocol protocol)
+    public ValueTask<CollectionResponse> EnterCollect(in PrometheusProtocol protocol)
 #else
-    public Task<CollectionResponse> EnterCollect(PrometheusProtocol protocol)
+    public Task<CollectionResponse> EnterCollect(in PrometheusProtocol protocol)
 #endif
     {
         CollectionResponse? cachedResponse = null;
@@ -211,7 +211,7 @@ public Task<CollectionResponse> EnterCollect(PrometheusProtocol protocol)
     }
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public void ExitCollect(PrometheusProtocol protocol)
+    public void ExitCollect(in PrometheusProtocol protocol)
         => this.GetProtocolState(protocol).DecrementReaderCount();
 
 #if NET
@@ -257,15 +257,15 @@ private void ExitGlobalLock()
         => Interlocked.Exchange(ref this.globalLockState, 0);
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    private void IncrementReaderCount(PrometheusProtocol protocol)
+    private void IncrementReaderCount(in PrometheusProtocol protocol)
         => this.GetProtocolState(protocol).IncrementReaderCount();
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    private bool HasActiveReaders(PrometheusProtocol protocol)
+    private bool HasActiveReaders(in PrometheusProtocol protocol)
         => this.protocolStates.TryGetValue(protocol, out var state) && state.HasActiveReaders();
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    private bool WaitForReadersToComplete(PrometheusProtocol protocol)
+    private bool WaitForReadersToComplete(in PrometheusProtocol protocol)
     {
         var state = this.GetProtocolState(protocol);
         var didSpin = false;
@@ -345,7 +345,7 @@ private ExportResult OnCollect(in Batch<Metric> metrics)
             : ExportResult.Failure;
     }
 
-    private bool TryWriteResponse(PrometheusProtocol protocol, PrometheusProtocolState state, in Batch<Metric> metrics)
+    private bool TryWriteResponse(in PrometheusProtocol protocol, PrometheusProtocolState state, in Batch<Metric> metrics)
     {
         try
         {
@@ -451,7 +451,7 @@ private CollectionResult CreateCollectionResult(CollectionContext collectionCont
         return new CollectionResult(responses);
     }
 
-    private bool TryGetCachedResponse(PrometheusProtocol protocol, out CollectionResponse response)
+    private bool TryGetCachedResponse(in PrometheusProtocol protocol, out CollectionResponse response)
     {
         if (this.protocolStates.TryGetValue(protocol, out var state) &&
             state.GeneratedAt is { } generatedAt &&
@@ -468,7 +468,7 @@ state.GeneratedAtElapsed is { } generatedAtElapsed &&
     }
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    private PrometheusProtocolState GetProtocolState(PrometheusProtocol protocol)
+    private PrometheusProtocolState GetProtocolState(in PrometheusProtocol protocol)
         => this.protocolStates.GetOrAdd(protocol, static _ => new());
 
     private int WriteTargetInfo(TextFormatSerializer serializer, PrometheusProtocolState state)
@@ -633,7 +633,7 @@ public CollectionResult(IReadOnlyDictionary<PrometheusProtocol, CollectionRespon
             this.responses = responses;
         }
 
-        public bool TryGetResponse(PrometheusProtocol protocol, out CollectionResponse response)
+        public bool TryGetResponse(in PrometheusProtocol protocol, out CollectionResponse response)
         {
             if (this.responses?.TryGetValue(protocol, out response) == true)
             {
@@ -732,7 +732,7 @@ private sealed class CollectionContext
         private readonly TaskCompletionSource<CollectionResult> tcs = new(TaskCreationOptions.RunContinuationsAsynchronously);
         private bool frozen;
 
-        public CollectionContext(PrometheusProtocol protocol)
+        public CollectionContext(in PrometheusProtocol protocol)
         {
             this.protocols.Add(protocol);
         }
@@ -751,7 +751,7 @@ public PrometheusProtocol[] FreezeProtocols()
         public void SetResult(CollectionResult result)
             => this.tcs.SetResult(result);
 
-        public bool TryRegisterProtocol(PrometheusProtocol protocol, bool hasActiveReaders)
+        public bool TryRegisterProtocol(in PrometheusProtocol protocol, bool hasActiveReaders)
         {
             lock (this.gate)
             {