Adjust Cardinality Limit to Accommodate Internal Reserves

src/OpenTelemetry/Metrics/AggregatorStore.cs

@@ -11,6 +11,8 @@ namespace OpenTelemetry.Metrics;
 
 internal sealed class AggregatorStore
 {
+    // Constant to account for additional space for overflow attribute and a case with no dimensions.
+    internal const int AdditionalReserve = 2;
     internal readonly HashSet<string>? TagKeysInteresting;
     internal readonly bool OutputDelta;
     internal readonly bool OutputDeltaWithUnusedMetricPointReclaimEnabled;
@@ -62,11 +64,15 @@ internal AggregatorStore(
         ExemplarFilter? exemplarFilter = null)
     {
         this.name = metricStreamIdentity.InstrumentName;
-        this.CardinalityLimit = cardinalityLimit;
+
+        // Increase the CardinalityLimit by 2 (AdditionalReserve) to reserve additional space.
+        // This adjustment accounts for overflow attribute and a case where no dimensions are provided.
+        // Previously, these were included within the original cardinalityLimit, but now they are explicitly added to enhance clarity.
+        this.CardinalityLimit = cardinalityLimit + AdditionalReserve;
 
         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.metricPoints = new MetricPoint[this.CardinalityLimit];
+        this.currentMetricPointBatch = new int[this.CardinalityLimit];
         this.aggType = aggType;
         this.OutputDelta = temporality == AggregationTemporality.Delta;
         this.histogramBounds = metricStreamIdentity.HistogramBucketBounds ?? FindDefaultHistogramBounds(in metricStreamIdentity);
@@ -104,13 +110,13 @@ internal AggregatorStore(
 
         if (this.OutputDeltaWithUnusedMetricPointReclaimEnabled)
         {
-            this.availableMetricPoints = new Queue<int>(cardinalityLimit - reservedMetricPointsCount);
+            this.availableMetricPoints = new Queue<int>(this.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: (cardinalityLimit - reservedMetricPointsCount) * 2);
+                new ConcurrentDictionary<Tags, LookupData>(concurrencyLevel: Environment.ProcessorCount, capacity: (this.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.

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

@@ -1429,7 +1429,7 @@ int MetricPointCount()
         }
 
         meterProvider.ForceFlush(MaxTimeToAllowForFlush);
-        Assert.Equal(MeterProviderBuilderSdk.DefaultCardinalityLimit, MetricPointCount());
+        Assert.Equal(MeterProviderBuilderSdk.DefaultCardinalityLimit + AggregatorStore.AdditionalReserve, MetricPointCount());
 
         exportedItems.Clear();
         counterLong.Add(10);
@@ -1439,7 +1439,7 @@ int MetricPointCount()
         }
 
         meterProvider.ForceFlush(MaxTimeToAllowForFlush);
-        Assert.Equal(MeterProviderBuilderSdk.DefaultCardinalityLimit, MetricPointCount());
+        Assert.Equal(MeterProviderBuilderSdk.DefaultCardinalityLimit + AggregatorStore.AdditionalReserve, MetricPointCount());
 
         counterLong.Add(10);
         for (int i = 0; i < MeterProviderBuilderSdk.DefaultCardinalityLimit + 1; i++)
@@ -1453,7 +1453,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 + AggregatorStore.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,17 @@ public void CardinalityLimitofMatchingViewTakesPrecedenceOverMeterProvider(bool
 
         Assert.Equal(3, exportedItems.Count);
 
-        Assert.Equal(10000, exportedItems[1].AggregatorStore.CardinalityLimit);
+        // CardinalityLimit + 2 (reserved for zero tags and overflow)
+        Assert.Equal(10002, exportedItems[1].AggregatorStore.CardinalityLimit);
         if (setDefault)
         {
-            Assert.Equal(3, exportedItems[0].AggregatorStore.CardinalityLimit);
-            Assert.Equal(3, exportedItems[2].AggregatorStore.CardinalityLimit);
+            Assert.Equal(5, exportedItems[0].AggregatorStore.CardinalityLimit);
+            Assert.Equal(5, exportedItems[2].AggregatorStore.CardinalityLimit);
         }
         else
         {
-            Assert.Equal(2000, exportedItems[0].AggregatorStore.CardinalityLimit);
-            Assert.Equal(2000, exportedItems[2].AggregatorStore.CardinalityLimit);
+            Assert.Equal(2002, exportedItems[0].AggregatorStore.CardinalityLimit);
+            Assert.Equal(2002, exportedItems[2].AggregatorStore.CardinalityLimit);
         }
     }
 
@@ -1015,15 +1016,16 @@ public void ViewConflict_TwoDistinctInstruments_ThreeStreams()
         var metricB = exportedItems[1];
         var metricC = exportedItems[2];
 
-        Assert.Equal(256, metricA.AggregatorStore.CardinalityLimit);
+        // CardinalityLimit + 2 (reserved for zero tags and overflow)
+        Assert.Equal(258, metricA.AggregatorStore.CardinalityLimit);
         Assert.Equal("MetricStreamA", metricA.Name);
         Assert.Equal(20, GetAggregatedValue(metricA));
 
-        Assert.Equal(3, metricB.AggregatorStore.CardinalityLimit);
+        Assert.Equal(5, metricB.AggregatorStore.CardinalityLimit);
         Assert.Equal("MetricStreamB", metricB.Name);
         Assert.Equal(10, GetAggregatedValue(metricB));
 
-        Assert.Equal(200000, metricC.AggregatorStore.CardinalityLimit);
+        Assert.Equal(200002, metricC.AggregatorStore.CardinalityLimit);
         Assert.Equal("MetricStreamC", metricC.Name);
         Assert.Equal(10, GetAggregatedValue(metricC));