[sdk-metrics] Obsolete SetMaxMetricPointsPerMetricStream + standarize on "Cardinality Limit" name

docs/diagnostics/experimental-apis/OTEL1003.md

@@ -4,21 +4,18 @@
 
 This is an Experimental API diagnostic covering the following API:
 
+* `MeterProviderBuilderExtensions.SetCardinalityLimit`
 * `MetricStreamConfiguration.CardinalityLimit.get`
 * `MetricStreamConfiguration.CardinalityLimit.set`
 
 Experimental APIs may be changed or removed in the future.
 
 ## Details
 
-The OpenTelemetry Specification defines the
-[cardinality limit](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#cardinality-limits)
-of a metric can be set by the matching view.
-
 From the specification:
 
-> The cardinality limit for an aggregation is defined in one of three ways:
-> A view with criteria matching the instrument an aggregation is created for has
+> The cardinality limit for an aggregation is defined in one of three ways: A
+> view with criteria matching the instrument an aggregation is created for has
 > an aggregation_cardinality_limit value defined for the stream, that value
 > SHOULD be used. If there is no matching view, but the MetricReader defines a
 > default cardinality limit value based on the instrument an aggregation is
@@ -27,3 +24,28 @@
 
 We are exposing these APIs experimentally until the specification declares them
 stable.
+
+### Setting the default cardinality limit for the MeterProvider:
+
+There is nothing in the OpenTelemetry Specification currently for defining the
+default cardinality limit for a MeterProvider.
+
+```csharp
+using var meterProvider = Sdk.CreateMeterProviderBuilder()
+    .SetCardinalityLimit(5000)
+    .Build();
+```
+
+### Setting cardinality limit for a specific Metric via the View API:
+
+The OpenTelemetry Specification defines the [cardinality
+limit](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#cardinality-limits)
+of a metric can be set by the matching view.
+
+```csharp
+using var meterProvider = Sdk.CreateMeterProviderBuilder()
+    .AddView(
+        instrumentName: "MyFruitCounter",
+        new MetricStreamConfiguration { CardinalityLimit = 10 })
+    .Build();
+```

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

@@ -31,6 +31,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.SetCardinalityLimit(this OpenTelemetry.Metrics.MeterProviderBuilder! meterProviderBuilder, int cardinalityLimit) -> OpenTelemetry.Metrics.MeterProviderBuilder!
 static OpenTelemetry.Metrics.MeterProviderBuilderExtensions.SetExemplarFilter(this OpenTelemetry.Metrics.MeterProviderBuilder! meterProviderBuilder, OpenTelemetry.Metrics.ExemplarFilter! 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!

src/OpenTelemetry/CHANGELOG.md

@@ -38,6 +38,12 @@
   [IMetricsListener](https://learn.microsoft.com/dotNet/api/microsoft.extensions.diagnostics.metrics.imetricslistener).
   ([#5265](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5265))
 
+* **Experimental (pre-release builds only):** Obsoleted
+  `MeterProviderBuilderExtensions.SetMaxMetricPointsPerMetricStream` and added
+  `MeterProviderBuilderExtensions.SetCardinalityLimit`. The new method does the
+  same thing but has a more spec-compliant name.
+  ([#XXXX](https://github.com/open-telemetry/opentelemetry-dotnet/pull/XXXX))
+
 ## 1.7.0
 
 Released 2023-Dec-08

src/OpenTelemetry/Metrics/AggregatorStore.cs

@@ -42,7 +42,7 @@ internal sealed class AggregatorStore
     private readonly int exponentialHistogramMaxScale;
     private readonly UpdateLongDelegate updateLongCallback;
     private readonly UpdateDoubleDelegate updateDoubleCallback;
-    private readonly int maxMetricPoints;
+    private readonly int cardinalityLimit;
     private readonly bool emitOverflowAttribute;
     private readonly ExemplarFilter exemplarFilter;
     private readonly Func<KeyValuePair<string, object?>[], int, int> lookupAggregatorStore;
@@ -57,17 +57,17 @@ internal AggregatorStore(
         MetricStreamIdentity metricStreamIdentity,
         AggregationType aggType,
         AggregationTemporality temporality,
-        int maxMetricPoints,
+        int cardinalityLimit,
         bool emitOverflowAttribute,
         bool shouldReclaimUnusedMetricPoints,
         ExemplarFilter? exemplarFilter = null)
     {
         this.name = metricStreamIdentity.InstrumentName;
-        this.maxMetricPoints = maxMetricPoints;
+        this.cardinalityLimit = cardinalityLimit;
 
-        this.metricPointCapHitMessage = $"Maximum MetricPoints limit reached for this Metric stream. Configured limit: {this.maxMetricPoints}";
-        this.metricPoints = new MetricPoint[maxMetricPoints];
-        this.currentMetricPointBatch = new int[maxMetricPoints];
+        this.metricPointCapHitMessage = $"Maximum MetricPoints limit reached for this Metric stream. Configured limit: {this.cardinalityLimit}";
+        this.metricPoints = new MetricPoint[cardinalityLimit];
+        this.currentMetricPointBatch = new int[cardinalityLimit];
         this.aggType = aggType;
         this.OutputDelta = temporality == AggregationTemporality.Delta;
         this.histogramBounds = metricStreamIdentity.HistogramBucketBounds ?? FindDefaultHistogramBounds(in metricStreamIdentity);
@@ -105,17 +105,17 @@ internal AggregatorStore(
 
         if (this.OutputDeltaWithUnusedMetricPointReclaimEnabled)
         {
-            this.availableMetricPoints = new Queue<int>(maxMetricPoints - reservedMetricPointsCount);
+            this.availableMetricPoints = new Queue<int>(cardinalityLimit - reservedMetricPointsCount);
 
             // There is no overload which only takes capacity as the parameter
             // Using the DefaultConcurrencyLevel defined in the ConcurrentDictionary class: https://github.com/dotnet/runtime/blob/v7.0.5/src/libraries/System.Collections.Concurrent/src/System/Collections/Concurrent/ConcurrentDictionary.cs#L2020
             // We expect at the most (maxMetricPoints - reservedMetricPointsCount) * 2 entries- one for sorted and one for unsorted input
             this.tagsToMetricPointIndexDictionaryDelta =
-                new ConcurrentDictionary<Tags, LookupData>(concurrencyLevel: Environment.ProcessorCount, capacity: (maxMetricPoints - reservedMetricPointsCount) * 2);
+                new ConcurrentDictionary<Tags, LookupData>(concurrencyLevel: Environment.ProcessorCount, capacity: (cardinalityLimit - reservedMetricPointsCount) * 2);
 
             // Add all the indices except for the reserved ones to the queue so that threads have
             // readily available access to these MetricPoints for their use.
-            for (int i = reservedMetricPointsCount; i < this.maxMetricPoints; i++)
+            for (int i = reservedMetricPointsCount; i < this.cardinalityLimit; i++)
             {
                 this.availableMetricPoints.Enqueue(i);
             }
@@ -164,12 +164,12 @@ internal int Snapshot()
         }
         else if (this.OutputDelta)
         {
-            var indexSnapshot = Math.Min(this.metricPointIndex, this.maxMetricPoints - 1);
+            var indexSnapshot = Math.Min(this.metricPointIndex, this.cardinalityLimit - 1);
             this.SnapshotDelta(indexSnapshot);
         }
         else
         {
-            var indexSnapshot = Math.Min(this.metricPointIndex, this.maxMetricPoints - 1);
+            var indexSnapshot = Math.Min(this.metricPointIndex, this.cardinalityLimit - 1);
             this.SnapshotCumulative(indexSnapshot);
         }
 
@@ -249,7 +249,7 @@ internal void SnapshotDeltaWithMetricPointReclaim()
             }
         }
 
-        for (int i = startIndexForReclaimableMetricPoints; i < this.maxMetricPoints; i++)
+        for (int i = startIndexForReclaimableMetricPoints; i < this.cardinalityLimit; i++)
         {
             ref var metricPoint = ref this.metricPoints[i];
 
@@ -440,7 +440,7 @@ private int LookupAggregatorStore(KeyValuePair<string, object?>[] tagKeysAndValu
                 if (!this.tagsToMetricPointIndexDictionary.TryGetValue(sortedTags, out aggregatorIndex))
                 {
                     aggregatorIndex = this.metricPointIndex;
-                    if (aggregatorIndex >= this.maxMetricPoints)
+                    if (aggregatorIndex >= this.cardinalityLimit)
                     {
                         // sorry! out of data points.
                         // TODO: Once we support cleanup of
@@ -469,7 +469,7 @@ private int LookupAggregatorStore(KeyValuePair<string, object?>[] tagKeysAndValu
                         if (!this.tagsToMetricPointIndexDictionary.TryGetValue(sortedTags, out aggregatorIndex))
                         {
                             aggregatorIndex = ++this.metricPointIndex;
-                            if (aggregatorIndex >= this.maxMetricPoints)
+                            if (aggregatorIndex >= this.cardinalityLimit)
                             {
                                 // sorry! out of data points.
                                 // TODO: Once we support cleanup of
@@ -496,7 +496,7 @@ private int LookupAggregatorStore(KeyValuePair<string, object?>[] tagKeysAndValu
             {
                 // This else block is for tag length = 1
                 aggregatorIndex = this.metricPointIndex;
-                if (aggregatorIndex >= this.maxMetricPoints)
+                if (aggregatorIndex >= this.cardinalityLimit)
                 {
                     // sorry! out of data points.
                     // TODO: Once we support cleanup of
@@ -518,7 +518,7 @@ private int LookupAggregatorStore(KeyValuePair<string, object?>[] tagKeysAndValu
                     if (!this.tagsToMetricPointIndexDictionary.TryGetValue(givenTags, out aggregatorIndex))
                     {
                         aggregatorIndex = ++this.metricPointIndex;
-                        if (aggregatorIndex >= this.maxMetricPoints)
+                        if (aggregatorIndex >= this.cardinalityLimit)
                         {
                             // sorry! out of data points.
                             // TODO: Once we support cleanup of

src/OpenTelemetry/Metrics/Builder/MeterProviderBuilderExtensions.cs

@@ -1,9 +1,12 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+#if EXPOSE_EXPERIMENTAL_FEATURES
+using System.ComponentModel;
 #if NET6_0_OR_GREATER
 using System.Diagnostics.CodeAnalysis;
 #endif
+#endif
 using System.Diagnostics.Metrics;
 using System.Text.RegularExpressions;
 using Microsoft.Extensions.DependencyInjection;
@@ -51,7 +54,7 @@
     /// <returns>The supplied <see cref="MeterProviderBuilder"/> for chaining.</returns>
     public static MeterProviderBuilder AddReader<
 #if NET6_0_OR_GREATER
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)]
 #endif
     T>(this MeterProviderBuilder meterProviderBuilder)
         where T : MetricReader
@@ -230,14 +233,14 @@
     /// This limits the number of unique combinations of key/value pairs used
     /// for reporting measurements.
     /// </summary>
-    /// <remarks>
-    /// If a particular key/value pair combination is used at least once,
-    /// it will contribute to the limit for the life of the process.
-    /// This may change in the future. See: https://github.com/open-telemetry/opentelemetry-dotnet/issues/2360.
-    /// </remarks>
+    /// <inheritdoc cref="SetCardinalityLimit(MeterProviderBuilder, int)"/>
     /// <param name="meterProviderBuilder"><see cref="MeterProviderBuilder"/>.</param>
     /// <param name="maxMetricPointsPerMetricStream">Maximum number of metric points allowed per metric stream.</param>
     /// <returns>The supplied <see cref="MeterProviderBuilder"/> for chaining.</returns>
+#if EXPOSE_EXPERIMENTAL_FEATURES
+    [Obsolete("Call SetCardinalityLimit instead this method will be removed in a future version.")]
+    [EditorBrowsable(EditorBrowsableState.Never)]
+#endif
     public static MeterProviderBuilder SetMaxMetricPointsPerMetricStream(this MeterProviderBuilder meterProviderBuilder, int maxMetricPointsPerMetricStream)
     {
         Guard.ThrowIfOutOfRange(maxMetricPointsPerMetricStream, min: 1);
@@ -253,6 +256,40 @@
         return meterProviderBuilder;
     }
 
+#if EXPOSE_EXPERIMENTAL_FEATURES
+    /// <summary>
+    /// Sets a positive integer value defining the maximum number of
+    /// data points allowed for metrics managed by the MeterProvider.
+    /// </summary>
+    /// <remarks>
+    /// <para><b>WARNING</b>: This is an experimental API which might change or
+    /// be removed in the future. Use at your own risk.</para>
+    /// </remarks>
+    /// <param name="meterProviderBuilder"><see cref="MeterProviderBuilder"/>.</param>
+    /// <param name="cardinalityLimit">Cardinality limit.</param>
+    /// <returns>The supplied <see cref="MeterProviderBuilder"/> for chaining.</returns>
+#if NET8_0_OR_GREATER
+    [Experimental(DiagnosticDefinitions.CardinalityLimitExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
+    public
+#else
+    internal
+#endif
+        static MeterProviderBuilder SetCardinalityLimit(this MeterProviderBuilder meterProviderBuilder, int cardinalityLimit)
+    {
+        Guard.ThrowIfOutOfRange(cardinalityLimit, min: 1, max: int.MaxValue);
+
+        meterProviderBuilder.ConfigureBuilder((sp, builder) =>
+        {
+            if (builder is MeterProviderBuilderSdk meterProviderBuilderSdk)
+            {
+                meterProviderBuilderSdk.SetCardinalityLimit(cardinalityLimit);
+            }
+        });
+
+        return meterProviderBuilder;
+    }
+
     /// <summary>
     /// Sets the <see cref="ResourceBuilder"/> from which the Resource associated with
     /// this provider is built from. Overwrites currently set ResourceBuilder.
@@ -262,7 +299,7 @@
     /// <param name="meterProviderBuilder"><see cref="MeterProviderBuilder"/>.</param>
     /// <param name="resourceBuilder"><see cref="ResourceBuilder"/> from which Resource will be built.</param>
     /// <returns>The supplied <see cref="MeterProviderBuilder"/> for chaining.</returns>
     public static MeterProviderBuilder SetResourceBuilder(this MeterProviderBuilder meterProviderBuilder, ResourceBuilder resourceBuilder)
     {
         Guard.ThrowIfNull(resourceBuilder);
 

src/OpenTelemetry/Metrics/Builder/MeterProviderBuilderSdk.cs

@@ -16,7 +16,7 @@ namespace OpenTelemetry.Metrics;
 internal sealed class MeterProviderBuilderSdk : MeterProviderBuilder, IMeterProviderBuilder
 {
     public const int MaxMetricsDefault = 1000;
-    public const int MaxMetricPointsPerMetricDefault = 2000;
+    public const int CardinalityLimitDefault = 2000;
     private const string DefaultInstrumentationVersion = "1.0.0.0";
 
     private readonly IServiceProvider serviceProvider;
@@ -51,7 +51,7 @@ public MeterProviderBuilderSdk(IServiceProvider serviceProvider)
 
     public int MaxMetricStreams { get; private set; } = MaxMetricsDefault;
 
-    public int MaxMetricPointsPerMetricStream { get; private set; } = MaxMetricPointsPerMetricDefault;
+    public int CardinalityLimit { get; private set; } = CardinalityLimitDefault;
 
     /// <summary>
     /// Returns whether the given instrument name is valid according to the specification.
@@ -193,9 +193,9 @@ public MeterProviderBuilder SetMaxMetricStreams(int maxMetricStreams)
         return this;
     }
 
-    public MeterProviderBuilder SetMaxMetricPointsPerMetricStream(int maxMetricPointsPerMetricStream)
+    public MeterProviderBuilder SetCardinalityLimit(int cardinalityLimit)
     {
-        this.MaxMetricPointsPerMetricStream = maxMetricPointsPerMetricStream;
+        this.CardinalityLimit = cardinalityLimit;
 
         return this;
     }

src/OpenTelemetry/Metrics/MeterProviderSdk.cs

@@ -76,9 +76,12 @@ internal MeterProviderSdk(
             Guard.ThrowIfNull(reader);
 
             reader.SetParentProvider(this);
-            reader.SetMaxMetricStreams(state.MaxMetricStreams);
-            reader.SetMaxMetricPointsPerMetricStream(state.MaxMetricPointsPerMetricStream, isEmitOverflowAttributeKeySet);
-            reader.SetExemplarFilter(state.ExemplarFilter);
+
+            reader.ApplyParentProviderSettings(
+                state.MaxMetricStreams,
+                state.CardinalityLimit,
+                state.ExemplarFilter,
+                isEmitOverflowAttributeKeySet);
 
             if (this.reader == null)
             {

src/OpenTelemetry/Metrics/Metric.cs

@@ -46,7 +46,7 @@ public sealed class Metric
     internal Metric(
         MetricStreamIdentity instrumentIdentity,
         AggregationTemporality temporality,
-        int maxMetricPointsPerMetricStream,
+        int cardinalityLimit,
         bool emitOverflowAttribute,
         bool shouldReclaimUnusedMetricPoints,
         ExemplarFilter? exemplarFilter = null)
@@ -155,7 +155,7 @@ internal Metric(
             throw new NotSupportedException($"Unsupported Instrument Type: {instrumentIdentity.InstrumentType.FullName}");
         }
 
-        this.aggStore = new AggregatorStore(instrumentIdentity, aggType, temporality, maxMetricPointsPerMetricStream, emitOverflowAttribute, shouldReclaimUnusedMetricPoints, exemplarFilter);
+        this.aggStore = new AggregatorStore(instrumentIdentity, aggType, temporality, cardinalityLimit, emitOverflowAttribute, shouldReclaimUnusedMetricPoints, exemplarFilter);
         this.Temporality = temporality;
     }