[sdk-metrics] Expose ExemplarReservoir and support configuration via views (#5542)

src/OpenTelemetry/.publicApi/Experimental/PublicAPI.Unshipped.txt

@@ -1,3 +1,6 @@
+abstract OpenTelemetry.Metrics.ExemplarReservoir.Collect() -> OpenTelemetry.Metrics.ReadOnlyExemplarCollection
+abstract OpenTelemetry.Metrics.ExemplarReservoir.Offer(in OpenTelemetry.Metrics.ExemplarMeasurement<double> measurement) -> void
+abstract OpenTelemetry.Metrics.ExemplarReservoir.Offer(in OpenTelemetry.Metrics.ExemplarMeasurement<long> measurement) -> void
 OpenTelemetry.Logs.LoggerProviderBuilderExtensions
 OpenTelemetry.Logs.LoggerProviderExtensions
 OpenTelemetry.Logs.LogRecord.Logger.get -> OpenTelemetry.Logs.Logger!
@@ -21,9 +24,14 @@ OpenTelemetry.Metrics.ExemplarMeasurement<T>
 OpenTelemetry.Metrics.ExemplarMeasurement<T>.ExemplarMeasurement() -> void
 OpenTelemetry.Metrics.ExemplarMeasurement<T>.Tags.get -> System.ReadOnlySpan<System.Collections.Generic.KeyValuePair<string!, object?>>
 OpenTelemetry.Metrics.ExemplarMeasurement<T>.Value.get -> T
+OpenTelemetry.Metrics.ExemplarReservoir
+OpenTelemetry.Metrics.ExemplarReservoir.ExemplarReservoir() -> void
+OpenTelemetry.Metrics.ExemplarReservoir.ResetOnCollect.get -> bool
 OpenTelemetry.Metrics.MetricPoint.TryGetExemplars(out OpenTelemetry.Metrics.ReadOnlyExemplarCollection exemplars) -> bool
 OpenTelemetry.Metrics.MetricStreamConfiguration.CardinalityLimit.get -> int?
 OpenTelemetry.Metrics.MetricStreamConfiguration.CardinalityLimit.set -> void
+OpenTelemetry.Metrics.MetricStreamConfiguration.ExemplarReservoirFactory.get -> System.Func<OpenTelemetry.Metrics.ExemplarReservoir?>?
+OpenTelemetry.Metrics.MetricStreamConfiguration.ExemplarReservoirFactory.set -> void
 OpenTelemetry.Metrics.ReadOnlyExemplarCollection
 OpenTelemetry.Metrics.ReadOnlyExemplarCollection.Enumerator
 OpenTelemetry.Metrics.ReadOnlyExemplarCollection.Enumerator.Current.get -> OpenTelemetry.Metrics.Exemplar

src/OpenTelemetry/CHANGELOG.md

@@ -7,6 +7,11 @@
   during configuration reload.
   ([#5514](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5514))
 
+* **Experimental (pre-release builds only):** Exposed `ExemplarReservoir` as a
+  public API and added support for setting an `ExemplarReservoir` factory
+  function when configuring a view (applies to individual metrics).
+  ([#5542](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5542))
+
 ## 1.8.0
 
 Released 2024-Apr-02

src/OpenTelemetry/Internal/OpenTelemetrySdkEventSource.cs

@@ -158,6 +158,15 @@ internal sealed class OpenTelemetrySdkEventSource : EventSource, IConfigurationE
         }
     }
 
+    [NonEvent]
+    public void MetricViewException(string source, Exception ex)
+    {
+        if (this.IsEnabled(EventLevel.Error, EventKeywords.All))
+        {
+            this.MetricViewException(source, ex.ToInvariantString());
+        }
+    }
+
     [Event(4, Message = "Unknown error in SpanProcessor event '{0}': '{1}'.", Level = EventLevel.Error)]
     public void SpanProcessorException(string evnt, string ex)
     {
@@ -359,6 +368,12 @@ internal sealed class OpenTelemetrySdkEventSource : EventSource, IConfigurationE
         this.WriteEvent(55, configValue);
     }
 
+    [Event(56, Message = "Exception thrown by user code supplied on metric view ('{0}'): '{1}'.", Level = EventLevel.Error)]
+    public void MetricViewException(string source, string ex)
+    {
+        this.WriteEvent(56, source, ex);
+    }
+
     void IConfigurationExtensionsLogger.LogInvalidConfigurationValue(string key, string value)
     {
         this.InvalidConfigurationValue(key, value);

src/OpenTelemetry/Metrics/Exemplar/ExemplarReservoir.cs

@@ -1,16 +1,30 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+using OpenTelemetry.Internal;
+#endif
+
 namespace OpenTelemetry.Metrics;
 
+#if EXPOSE_EXPERIMENTAL_FEATURES
 /// <summary>
 /// ExemplarReservoir base implementation and contract.
 /// </summary>
 /// <remarks>
+/// <remarks><inheritdoc cref="Exemplar" path="/remarks/para[@experimental-warning='true']"/></remarks>
 /// Specification: <see
 /// href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#exemplarreservoir"/>.
 /// </remarks>
-internal abstract class ExemplarReservoir
+#if NET8_0_OR_GREATER
+[Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
+public
+#else
+internal
+#endif
+    abstract class ExemplarReservoir
 {
     /// <summary>
     /// Gets a value indicating whether or not the <see

src/OpenTelemetry/Metrics/MetricPoint.cs

@@ -62,11 +62,13 @@ public struct MetricPoint
         ExemplarReservoir? reservoir;
         try
         {
-            reservoir = aggregatorStore.ExemplarReservoirFactory?.Invoke();
+            reservoir = isExemplarEnabled
+                ? aggregatorStore.ExemplarReservoirFactory?.Invoke()
+                : null;
         }
-        catch
+        catch (Exception ex)
         {
-            // TODO : Log that the factory on view threw an exception, once view exposes that capability
+            OpenTelemetrySdkEventSource.Log.MetricViewException("ExemplarReservoirFactory", ex);
             reservoir = null;
         }
 

src/OpenTelemetry/Metrics/MetricStreamConfiguration.cs

@@ -137,9 +137,27 @@ public class MetricStreamConfiguration
         }
     }
 
-    // TODO: Expose this to be complaint with the spec:
-    // https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#stream-configuration
+#if EXPOSE_EXPERIMENTAL_FEATURES
+    /// <summary>
+    /// Gets or sets a factory function used to generate an <see
+    /// cref="ExemplarReservoir"/> for the metric managed by the view to use
+    /// when storing <see cref="Exemplar"/>s.
+    /// </summary>
+    /// <remarks>
+    /// <remarks><inheritdoc cref="Exemplar" path="/remarks/para[@experimental-warning='true']"/></remarks>
+    /// <para>Note: Returning <see langword="null"/> from the factory function will
+    /// result in the default <see cref="ExemplarReservoir"/> being chosen by
+    /// the SDK based on the type of metric.</para>
+    /// Specification: <see
+    /// href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#stream-configuration"/>.
+    /// </remarks>
+#if NET8_0_OR_GREATER
+    [Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
+    public Func<ExemplarReservoir?>? ExemplarReservoirFactory { get; set; }
+#else
     internal Func<ExemplarReservoir?>? ExemplarReservoirFactory { get; set; }
+#endif
 
     internal string[]? CopiedTagKeys { get; private set; }