[sdk-metrics] Tweak SetExemplarFilter API and improve XML docs (#5578)

open-telemetry · Apr 26, 2024 · e25d128 · e25d128
1 parent 254f52f
commit e25d128
Show file tree

Hide file tree

Showing 2 changed files with 25 additions and 10 deletions.
diff --git a/src/OpenTelemetry/.publicApi/Experimental/PublicAPI.Unshipped.txt b/src/OpenTelemetry/.publicApi/Experimental/PublicAPI.Unshipped.txt
@@ -55,7 +55,7 @@ static OpenTelemetry.Logs.LoggerProviderBuilderExtensions.SetResourceBuilder(thi
 static OpenTelemetry.Logs.LoggerProviderExtensions.AddProcessor(this OpenTelemetry.Logs.LoggerProvider! provider, OpenTelemetry.BaseProcessor<OpenTelemetry.Logs.LogRecord!>! processor) -> OpenTelemetry.Logs.LoggerProvider!
 static OpenTelemetry.Logs.LoggerProviderExtensions.ForceFlush(this OpenTelemetry.Logs.LoggerProvider! provider, int timeoutMilliseconds = -1) -> bool
 static OpenTelemetry.Logs.LoggerProviderExtensions.Shutdown(this OpenTelemetry.Logs.LoggerProvider! provider, int timeoutMilliseconds = -1) -> bool
-static OpenTelemetry.Metrics.MeterProviderBuilderExtensions.SetExemplarFilter(this OpenTelemetry.Metrics.MeterProviderBuilder! meterProviderBuilder, OpenTelemetry.Metrics.ExemplarFilterType exemplarFilter = OpenTelemetry.Metrics.ExemplarFilterType.TraceBased) -> OpenTelemetry.Metrics.MeterProviderBuilder!
+static OpenTelemetry.Metrics.MeterProviderBuilderExtensions.SetExemplarFilter(this OpenTelemetry.Metrics.MeterProviderBuilder! meterProviderBuilder, OpenTelemetry.Metrics.ExemplarFilterType exemplarFilter) -> OpenTelemetry.Metrics.MeterProviderBuilder!
 static OpenTelemetry.OpenTelemetryBuilderSdkExtensions.WithLogging(this OpenTelemetry.IOpenTelemetryBuilder! builder) -> OpenTelemetry.IOpenTelemetryBuilder!
 static OpenTelemetry.OpenTelemetryBuilderSdkExtensions.WithLogging(this OpenTelemetry.IOpenTelemetryBuilder! builder, System.Action<OpenTelemetry.Logs.LoggerProviderBuilder!>! configure) -> OpenTelemetry.IOpenTelemetryBuilder!
 static OpenTelemetry.OpenTelemetryBuilderSdkExtensions.WithLogging(this OpenTelemetry.IOpenTelemetryBuilder! builder, System.Action<OpenTelemetry.Logs.LoggerProviderBuilder!>? configureBuilder, System.Action<OpenTelemetry.Logs.OpenTelemetryLoggerOptions!>? configureOptions) -> OpenTelemetry.IOpenTelemetryBuilder!

diff --git a/src/OpenTelemetry/Metrics/Builder/MeterProviderBuilderExtensions.cs b/src/OpenTelemetry/Metrics/Builder/MeterProviderBuilderExtensions.cs
@@ -319,16 +319,31 @@ public static MeterProvider Build(this MeterProviderBuilder meterProviderBuilder
 
 #if EXPOSE_EXPERIMENTAL_FEATURES
     /// <summary>
-    /// Sets the <see cref="ExemplarFilterType"/> to be used for this provider
-    /// which controls how measurements will be offered to exemplar reservoirs.
-    /// Default provider configuration: <see
-    /// cref="ExemplarFilterType.AlwaysOff"/>.
+    /// Sets the default <see cref="ExemplarFilterType"/> for the provider.
     /// </summary>
     /// <remarks>
     /// <inheritdoc cref="Exemplar"
     /// path="/remarks/para[@experimental-warning='true']"/>
-    /// <para>Note: Use <see cref="ExemplarFilterType.TraceBased"/> or <see
-    /// cref="ExemplarFilterType.AlwaysOn"/> to enable exemplars.</para>
+    /// <para>Notes:
+    /// <list type="bullet">
+    /// <item>The configured <see cref="ExemplarFilterType"/> controls how
+    /// measurements will be offered to <see cref="ExemplarReservoir"/>s which
+    /// are responsible for storing <see cref="Exemplar"/>s on metrics.</item>
+    /// <item>The default provider configuration is <see
+    /// cref="ExemplarFilterType.AlwaysOff"/>.</item>
+    /// <item>Use <see cref="ExemplarFilterType.TraceBased"/> or <see
+    /// cref="ExemplarFilterType.AlwaysOn"/> to enable <see cref="Exemplar"/>s
+    /// for all metrics managed by the provider.</item>
+    /// <item>If <see cref="Exemplar"/>s are enabled on the provider by the
+    /// configured <see cref="ExemplarFilterType"/> then <see
+    /// cref="ExemplarReservoir"/>s will be configured on metrics using the
+    /// defaults described in the specification: <see
+    /// href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#exemplar-defaults"
+    /// />. To change the <see cref="ExemplarReservoir"/> for a metric use the
+    /// <c>AddView</c> API and <see
+    /// cref="MetricStreamConfiguration.ExemplarReservoirFactory"/>.</item>
+    /// </list>
+    /// </para>
     /// <para>Specification: <see
     /// href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#exemplarfilter"/>.</para>
     /// </remarks>
@@ -345,9 +360,9 @@ public static MeterProvider Build(this MeterProviderBuilder meterProviderBuilder
 #else
     internal
 #endif
-            static MeterProviderBuilder SetExemplarFilter(
+        static MeterProviderBuilder SetExemplarFilter(
         this MeterProviderBuilder meterProviderBuilder,
-        ExemplarFilterType exemplarFilter = ExemplarFilterType.TraceBased)
+        ExemplarFilterType exemplarFilter)
     {
         meterProviderBuilder.ConfigureBuilder((sp, builder) =>
         {
@@ -361,7 +376,7 @@ static MeterProviderBuilder SetExemplarFilter(
                         meterProviderBuilderSdk.SetExemplarFilter(exemplarFilter);
                         break;
                     default:
-                        throw new NotSupportedException($"SdkExemplarFilter '{exemplarFilter}' is not supported.");
+                        throw new NotSupportedException($"ExemplarFilterType '{exemplarFilter}' is not supported.");
                 }
             }
         });