Adjust Cardinality Limit to Accommodate Internal Reserves

src/OpenTelemetry/Metrics/AggregatorStore.cs

@@ -14,7 +14,7 @@ internal sealed class AggregatorStore
     internal readonly HashSet<string>? TagKeysInteresting;
     internal readonly bool OutputDelta;
     internal readonly bool OutputDeltaWithUnusedMetricPointReclaimEnabled;
-    internal readonly int CardinalityLimit;
+    internal readonly int NumberOfReservedMetricPoints;
     internal readonly bool EmitOverflowAttribute;
     internal readonly ConcurrentDictionary<Tags, LookupData>? TagsToMetricPointIndexDictionaryDelta;
     internal readonly Func<ExemplarReservoir?>? ExemplarReservoirFactory;
@@ -64,11 +64,15 @@ internal AggregatorStore(
         Func<ExemplarReservoir?>? exemplarReservoirFactory = null)
     {
         this.name = metricStreamIdentity.InstrumentName;
-        this.CardinalityLimit = cardinalityLimit;
 
-        this.metricPointCapHitMessage = $"Maximum MetricPoints limit reached for this Metric stream. Configured limit: {this.CardinalityLimit}";
-        this.metricPoints = new MetricPoint[cardinalityLimit];
-        this.currentMetricPointBatch = new int[cardinalityLimit];
+        // Increase the CardinalityLimit by 2 to reserve additional space.
+        // This adjustment accounts for overflow attribute and a case where zero tags are provided.
+        // Previously, these were included within the original cardinalityLimit, but now they are explicitly added to enhance clarity.
+        this.NumberOfReservedMetricPoints = cardinalityLimit + 2;
+
+        this.metricPointCapHitMessage = $"Maximum MetricPoints limit reached for this Metric stream. Configured limit: {this.NumberOfReservedMetricPoints}";
+        this.metricPoints = new MetricPoint[this.NumberOfReservedMetricPoints];
+        this.currentMetricPointBatch = new int[this.NumberOfReservedMetricPoints];
         this.aggType = aggType;
         this.OutputDelta = temporality == AggregationTemporality.Delta;
         this.histogramBounds = metricStreamIdentity.HistogramBucketBounds ?? FindDefaultHistogramBounds(in metricStreamIdentity);
@@ -107,17 +111,17 @@ internal AggregatorStore(
 
         if (this.OutputDeltaWithUnusedMetricPointReclaimEnabled)
         {
-            this.availableMetricPoints = new Queue<int>(cardinalityLimit - reservedMetricPointsCount);
+            this.availableMetricPoints = new Queue<int>(this.NumberOfReservedMetricPoints - 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: (cardinalityLimit - reservedMetricPointsCount) * 2);
+                new ConcurrentDictionary<Tags, LookupData>(concurrencyLevel: Environment.ProcessorCount, capacity: (this.NumberOfReservedMetricPoints - 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.CardinalityLimit; i++)
+            for (int i = reservedMetricPointsCount; i < this.NumberOfReservedMetricPoints; i++)
             {
                 this.availableMetricPoints.Enqueue(i);
             }
@@ -166,12 +170,12 @@ internal int Snapshot()
         }
         else if (this.OutputDelta)
         {
-            var indexSnapshot = Math.Min(this.metricPointIndex, this.CardinalityLimit - 1);
+            var indexSnapshot = Math.Min(this.metricPointIndex, this.NumberOfReservedMetricPoints - 1);
             this.SnapshotDelta(indexSnapshot);
         }
         else
         {
-            var indexSnapshot = Math.Min(this.metricPointIndex, this.CardinalityLimit - 1);
+            var indexSnapshot = Math.Min(this.metricPointIndex, this.NumberOfReservedMetricPoints - 1);
             this.SnapshotCumulative(indexSnapshot);
         }
 
@@ -251,7 +255,7 @@ internal void SnapshotDeltaWithMetricPointReclaim()
             }
         }
 
-        for (int i = startIndexForReclaimableMetricPoints; i < this.CardinalityLimit; i++)
+        for (int i = startIndexForReclaimableMetricPoints; i < this.NumberOfReservedMetricPoints; i++)
         {
             ref var metricPoint = ref this.metricPoints[i];
 
@@ -442,7 +446,7 @@ private int LookupAggregatorStore(KeyValuePair<string, object?>[] tagKeysAndValu
                 if (!this.tagsToMetricPointIndexDictionary.TryGetValue(sortedTags, out aggregatorIndex))
                 {
                     aggregatorIndex = this.metricPointIndex;
-                    if (aggregatorIndex >= this.CardinalityLimit)
+                    if (aggregatorIndex >= this.NumberOfReservedMetricPoints)
                     {
                         // sorry! out of data points.
                         // TODO: Once we support cleanup of
@@ -471,7 +475,7 @@ private int LookupAggregatorStore(KeyValuePair<string, object?>[] tagKeysAndValu
                         if (!this.tagsToMetricPointIndexDictionary.TryGetValue(sortedTags, out aggregatorIndex))
                         {
                             aggregatorIndex = ++this.metricPointIndex;
-                            if (aggregatorIndex >= this.CardinalityLimit)
+                            if (aggregatorIndex >= this.NumberOfReservedMetricPoints)
                             {
                                 // sorry! out of data points.
                                 // TODO: Once we support cleanup of
@@ -498,7 +502,7 @@ private int LookupAggregatorStore(KeyValuePair<string, object?>[] tagKeysAndValu
             {
                 // This else block is for tag length = 1
                 aggregatorIndex = this.metricPointIndex;
-                if (aggregatorIndex >= this.CardinalityLimit)
+                if (aggregatorIndex >= this.NumberOfReservedMetricPoints)
                 {
                     // sorry! out of data points.
                     // TODO: Once we support cleanup of
@@ -520,7 +524,7 @@ private int LookupAggregatorStore(KeyValuePair<string, object?>[] tagKeysAndValu
                     if (!this.tagsToMetricPointIndexDictionary.TryGetValue(givenTags, out aggregatorIndex))
                     {
                         aggregatorIndex = ++this.metricPointIndex;
-                        if (aggregatorIndex >= this.CardinalityLimit)
+                        if (aggregatorIndex >= this.NumberOfReservedMetricPoints)
                         {
                             // sorry! out of data points.
                             // TODO: Once we support cleanup of

src/OpenTelemetry/Metrics/MetricStreamConfiguration.cs

@@ -109,8 +109,12 @@ public string[]? TagKeys
     /// <para>Spec reference: <see
     /// href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#cardinality-limits">Cardinality
     /// limits</see>.</para>
-    /// Note: If not set the default MeterProvider cardinality limit of 2000
-    /// will apply.
+    /// Note: The cardinality limit determines the maximum number of unique
+    /// dimension combinations for metrics.
+    /// Metrics with zero dimensions and overflow metrics are treated specially
+    /// and do not count against this limit.
+    /// If not set the default
+    /// MeterProvider cardinality limit of 2000 will apply.
     /// </remarks>
 #if NET8_0_OR_GREATER
     [Experimental(DiagnosticDefinitions.CardinalityLimitExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]

test/OpenTelemetry.Tests/Metrics/MetricApiTestsBase.cs

@@ -1391,6 +1391,8 @@ public void TestInstrumentDisposal(MetricReaderTemporalityPreference temporality
     [InlineData(MetricReaderTemporalityPreference.Delta)]
     public void TestMetricPointCap(MetricReaderTemporalityPreference temporality)
     {
+        // Constant to account for additional space for overflow attribute and a case with zero Tags.
+        var additionalReserve = 2;
         var exportedItems = new List<Metric>();
 
         int MetricPointCount()
@@ -1429,7 +1431,7 @@ int MetricPointCount()
         }
 
         meterProvider.ForceFlush(MaxTimeToAllowForFlush);
-        Assert.Equal(MeterProviderBuilderSdk.DefaultCardinalityLimit, MetricPointCount());
+        Assert.Equal(MeterProviderBuilderSdk.DefaultCardinalityLimit + additionalReserve, MetricPointCount());
 
         exportedItems.Clear();
         counterLong.Add(10);
@@ -1439,7 +1441,7 @@ int MetricPointCount()
         }
 
         meterProvider.ForceFlush(MaxTimeToAllowForFlush);
-        Assert.Equal(MeterProviderBuilderSdk.DefaultCardinalityLimit, MetricPointCount());
+        Assert.Equal(MeterProviderBuilderSdk.DefaultCardinalityLimit + additionalReserve, MetricPointCount());
 
         counterLong.Add(10);
         for (int i = 0; i < MeterProviderBuilderSdk.DefaultCardinalityLimit + 1; i++)
@@ -1453,7 +1455,7 @@ int MetricPointCount()
         counterLong.Add(10, new KeyValuePair<string, object>("key", "valueC"));
         exportedItems.Clear();
         meterProvider.ForceFlush(MaxTimeToAllowForFlush);
-        Assert.Equal(MeterProviderBuilderSdk.DefaultCardinalityLimit, MetricPointCount());
+        Assert.Equal(MeterProviderBuilderSdk.DefaultCardinalityLimit + additionalReserve, MetricPointCount());
     }
 
     [Fact]

test/OpenTelemetry.Tests/Metrics/MetricOverflowAttributeTestsBase.cs

@@ -158,7 +158,7 @@ public void MetricOverflowAttributeIsRecordedCorrectlyForCounter(MetricReaderTem
         counter.Add(10); // Record measurement for zero tags
 
         // Max number for MetricPoints available for use when emitted with tags
-        int maxMetricPointsForUse = MeterProviderBuilderSdk.DefaultCardinalityLimit - 2;
+        int maxMetricPointsForUse = MeterProviderBuilderSdk.DefaultCardinalityLimit;
 
         for (int i = 0; i < maxMetricPointsForUse; i++)
         {
@@ -186,7 +186,7 @@ public void MetricOverflowAttributeIsRecordedCorrectlyForCounter(MetricReaderTem
         exportedItems.Clear();
         metricPoints.Clear();
 
-        counter.Add(5, new KeyValuePair<string, object>("Key", 1998)); // Emit a metric to exceed the max MetricPoint limit
+        counter.Add(5, new KeyValuePair<string, object>("Key", 2000)); // Emit a metric to exceed the max MetricPoint limit
 
         meterProvider.ForceFlush();
         metric = exportedItems[0];
@@ -215,7 +215,7 @@ public void MetricOverflowAttributeIsRecordedCorrectlyForCounter(MetricReaderTem
         counter.Add(15); // Record another measurement for zero tags
 
         // Emit 2500 more newer MetricPoints with distinct dimension combinations
-        for (int i = 2000; i < 4500; i++)
+        for (int i = 2002; i < 4502; i++)
         {
             counter.Add(5, new KeyValuePair<string, object>("Key", i));
         }
@@ -236,11 +236,11 @@ public void MetricOverflowAttributeIsRecordedCorrectlyForCounter(MetricReaderTem
 
             int expectedSum;
 
-            // Number of metric points that were available before the 2500 measurements were made = 2000 (max MetricPoints) - 2 (reserved for zero tags and overflow) = 1998
+            // Number of metric points that were available before the 2500 measurements were made = 2000 (max MetricPoints)
             if (this.shouldReclaimUnusedMetricPoints)
             {
-                // If unused metric points are reclaimed, then number of metric points dropped = 2500 - 1998 = 502
-                expectedSum = 2510; // 502 * 5
+                // If unused metric points are reclaimed, then number of metric points dropped = 2500 - 2000 = 500
+                expectedSum = 2500; // 500 * 5
             }
             else
             {
@@ -309,7 +309,7 @@ public void MetricOverflowAttributeIsRecordedCorrectlyForHistogram(MetricReaderT
         histogram.Record(10); // Record measurement for zero tags
 
         // Max number for MetricPoints available for use when emitted with tags
-        int maxMetricPointsForUse = MeterProviderBuilderSdk.DefaultCardinalityLimit - 2;
+        int maxMetricPointsForUse = MeterProviderBuilderSdk.DefaultCardinalityLimit;
 
         for (int i = 0; i < maxMetricPointsForUse; i++)
         {
@@ -337,7 +337,7 @@ public void MetricOverflowAttributeIsRecordedCorrectlyForHistogram(MetricReaderT
         exportedItems.Clear();
         metricPoints.Clear();
 
-        histogram.Record(5, new KeyValuePair<string, object>("Key", 1998)); // Emit a metric to exceed the max MetricPoint limit
+        histogram.Record(5, new KeyValuePair<string, object>("Key", 2000)); // Emit a metric to exceed the max MetricPoint limit
 
         meterProvider.ForceFlush();
         metric = exportedItems[0];
@@ -366,7 +366,7 @@ public void MetricOverflowAttributeIsRecordedCorrectlyForHistogram(MetricReaderT
         histogram.Record(15); // Record another measurement for zero tags
 
         // Emit 2500 more newer MetricPoints with distinct dimension combinations
-        for (int i = 2000; i < 4500; i++)
+        for (int i = 2002; i < 4502; i++)
         {
             histogram.Record(5, new KeyValuePair<string, object>("Key", i));
         }
@@ -388,12 +388,12 @@ public void MetricOverflowAttributeIsRecordedCorrectlyForHistogram(MetricReaderT
             int expectedCount;
             int expectedSum;
 
-            // Number of metric points that were available before the 2500 measurements were made = 2000 (max MetricPoints) - 2 (reserved for zero tags and overflow) = 1998
+            // Number of metric points that were available before the 2500 measurements were made = 2000 (max MetricPoints)
             if (this.shouldReclaimUnusedMetricPoints)
             {
-                // If unused metric points are reclaimed, then number of metric points dropped = 2500 - 1998 = 502
-                expectedCount = 502;
-                expectedSum = 2510; // 502 * 5
+                // If unused metric points are reclaimed, then number of metric points dropped = 2500 - 2000 = 500
+                expectedCount = 500;
+                expectedSum = 2500; // 500 * 5
             }
             else
             {
@@ -407,7 +407,6 @@ public void MetricOverflowAttributeIsRecordedCorrectlyForHistogram(MetricReaderT
         else
         {
             Assert.Equal(25, zeroTagsMetricPoint.GetHistogramSum());
-
             Assert.Equal(2501, overflowMetricPoint.GetHistogramCount());
             Assert.Equal(12505, overflowMetricPoint.GetHistogramSum()); // 5 + (2500 * 5)
         }

test/OpenTelemetry.Tests/Metrics/MetricViewTests.cs

@@ -963,16 +963,16 @@ public void CardinalityLimitofMatchingViewTakesPrecedenceOverMeterProvider(bool
 
         Assert.Equal(3, exportedItems.Count);
 
-        Assert.Equal(10000, exportedItems[1].AggregatorStore.CardinalityLimit);
+        Assert.Equal(10002, exportedItems[1].AggregatorStore.NumberOfReservedMetricPoints);
         if (setDefault)
         {
-            Assert.Equal(3, exportedItems[0].AggregatorStore.CardinalityLimit);
-            Assert.Equal(3, exportedItems[2].AggregatorStore.CardinalityLimit);
+            Assert.Equal(5, exportedItems[0].AggregatorStore.NumberOfReservedMetricPoints);
+            Assert.Equal(5, exportedItems[2].AggregatorStore.NumberOfReservedMetricPoints);
         }
         else
         {
-            Assert.Equal(2000, exportedItems[0].AggregatorStore.CardinalityLimit);
-            Assert.Equal(2000, exportedItems[2].AggregatorStore.CardinalityLimit);
+            Assert.Equal(2002, exportedItems[0].AggregatorStore.NumberOfReservedMetricPoints);
+            Assert.Equal(2002, exportedItems[2].AggregatorStore.NumberOfReservedMetricPoints);
         }
     }
 
@@ -1015,15 +1015,15 @@ public void ViewConflict_TwoDistinctInstruments_ThreeStreams()
         var metricB = exportedItems[1];
         var metricC = exportedItems[2];
 
-        Assert.Equal(256, metricA.AggregatorStore.CardinalityLimit);
+        Assert.Equal(258, metricA.AggregatorStore.NumberOfReservedMetricPoints);
         Assert.Equal("MetricStreamA", metricA.Name);
         Assert.Equal(20, GetAggregatedValue(metricA));
 
-        Assert.Equal(3, metricB.AggregatorStore.CardinalityLimit);
+        Assert.Equal(5, metricB.AggregatorStore.NumberOfReservedMetricPoints);
         Assert.Equal("MetricStreamB", metricB.Name);
         Assert.Equal(10, GetAggregatedValue(metricB));
 
-        Assert.Equal(200000, metricC.AggregatorStore.CardinalityLimit);
+        Assert.Equal(200002, metricC.AggregatorStore.NumberOfReservedMetricPoints);
         Assert.Equal("MetricStreamC", metricC.Name);
         Assert.Equal(10, GetAggregatedValue(metricC));