Report stats cardinality collapses under protobuf field names (RFC §5)

The approved Cardinality Limits RFC keys collapse telemetry by the
lowercased protobuf field name. Two core-handler tags didn't match:

- operation is carried on the wire as the field "name", so its health
  tag is now collapsed:name (the human-facing CardinalityLimitReporter
  still says "operation"). PropertyCardinalityHandler gains a decoupled
  statsDField for this case.
- peer tags now aggregate into a single collapsed:peer_tags health
  metric across all configured peer tags (mirroring AdditionalTagsSchema),
  instead of emitting a per-tag-name collapsed:<tag> metric. Per-name
  detail is preserved in the human-facing reporter.

TagCardinalityHandler.statsDTag() is now unused and removed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dougqh

dd-trace-core/src/main/java/datadog/trace/common/metrics/CoreHandlers.java

@@ -43,9 +43,12 @@ final class CoreHandlers {
             "service",
             MetricCardinalityLimits.SERVICE,
             MetricCardinalityLimits.USE_BLOCKED_SENTINEL);
+    // operation is carried on the stats wire as the protobuf field "name", so its telemetry tag is
+    // collapsed:name (RFC section 5) while the human-facing reporter keeps the clearer "operation".
     this.operation =
         new PropertyCardinalityHandler(
             "operation",
+            "name",
             MetricCardinalityLimits.OPERATION,
             MetricCardinalityLimits.USE_BLOCKED_SENTINEL);
     this.serviceSource =

dd-trace-core/src/main/java/datadog/trace/common/metrics/PeerTagSchema.java

@@ -54,6 +54,11 @@ final class PeerTagSchema {
   /** Singleton schema for internal-kind spans -- only {@code base.service}. */
   static final PeerTagSchema INTERNAL = new PeerTagSchema(new String[] {BASE_SERVICE}, NO_STATE);
 
+  // Health/telemetry statsD tag per the approved Cardinality Limits RFC (section 5): peer-tag
+  // collapses are reported under the lowercased protobuf field name peer_tags, aggregated across
+  // every configured peer tag rather than per individual tag name.
+  private static final String[] COLLAPSED_STATSD_TAG = {"collapsed:peer_tags"};
+
   final String[] names;
   final TagCardinalityHandler[] handlers;
 
@@ -121,12 +126,19 @@ UTF8BytesString register(int i, String value) {
    * handlers are not thread-safe.
    */
   void resetHandlers(HealthMetrics healthMetrics, CardinalityLimitReporter reporter) {
+    long totalCollapsed = 0;
     for (int i = 0; i < handlers.length; i++) {
       long numBlocked = handlers[i].reset();
       if (numBlocked > 0) {
-        healthMetrics.onTagCardinalityBlocked(handlers[i].statsDTag(), numBlocked);
+        // The human-facing reporter names the specific peer tag that triggered the block.
         reporter.record(names[i], numBlocked);
       }
+      totalCollapsed += numBlocked;
+    }
+    // The health metric is reported at the peer_tags field granularity (not per tag name) per the
+    // approved Cardinality Limits RFC.
+    if (totalCollapsed > 0) {
+      healthMetrics.onTagCardinalityBlocked(COLLAPSED_STATSD_TAG, totalCollapsed);
     }
   }
 

dd-trace-core/src/main/java/datadog/trace/common/metrics/PropertyCardinalityHandler.java

@@ -31,6 +31,17 @@ final class PropertyCardinalityHandler {
   private static final int MAX_CARDINALITY_LIMIT = 1 << 29;
 
   final String name;
+
+  /**
+   * Protobuf field name this handler reports under in the {@code collapsed:} health/telemetry tag,
+   * per the approved Cardinality Limits RFC (section 5), which keys collapses by the lowercased
+   * protobuf field name. Usually equal to {@link #name}, but decoupled where the field's
+   * human-facing name differs from its wire name -- e.g. {@code operation} is carried on the wire
+   * as {@code name}, so its telemetry tag is {@code collapsed:name} while the human-facing {@link
+   * CardinalityLimitReporter} still says {@code operation}.
+   */
+  private final String statsDField;
+
   private final int cardinalityLimit;
   private final int capacityMask;
 
@@ -67,7 +78,13 @@ final class PropertyCardinalityHandler {
   }
 
   PropertyCardinalityHandler(String name, int cardinalityLimit, boolean useBlockedSentinel) {
+    this(name, name, cardinalityLimit, useBlockedSentinel);
+  }
+
+  PropertyCardinalityHandler(
+      String name, String statsDField, int cardinalityLimit, boolean useBlockedSentinel) {
     this.name = name;
+    this.statsDField = statsDField;
     if (cardinalityLimit <= 0) {
       throw new IllegalArgumentException("cardinalityLimit must be positive: " + cardinalityLimit);
     }
@@ -159,7 +176,7 @@ private UTF8BytesString tracerBlockedValue() {
    */
   String[] statsDTag() {
     if (statsDTag == null) {
-      statsDTag = new String[] {"collapsed:" + name};
+      statsDTag = new String[] {"collapsed:" + statsDField};
     }
     return statsDTag;
   }

dd-trace-core/src/main/java/datadog/trace/common/metrics/TagCardinalityHandler.java

@@ -19,7 +19,6 @@ final class TagCardinalityHandler {
   private static final int MAX_CARDINALITY_LIMIT = 1 << 29;
 
   private final String tag;
-  private String[] statsDTag = null;
   private final int cardinalityLimit;
   private final int maxValueLength;
   private final int capacityMask;
@@ -167,13 +166,6 @@ private UTF8BytesString tracerBlockedValue() {
     return cacheBlocked;
   }
 
-  String[] statsDTag() {
-    if (statsDTag == null) {
-      statsDTag = new String[] {"collapsed:" + tag};
-    }
-    return statsDTag;
-  }
-
   /**
    * Number of values collapsed by the per-value length cap in the current cycle. Must be read
    * before {@link #reset()}, which zeroes it along with the cardinality count.

dd-trace-core/src/test/java/datadog/trace/common/metrics/CoreHandlersTest.java

@@ -46,7 +46,9 @@ void resetReportsBlockedCountForAllNineHandlers() {
 
     verify(metrics).onTagCardinalityBlocked(new String[] {"collapsed:resource"}, 1L);
     verify(metrics).onTagCardinalityBlocked(new String[] {"collapsed:service"}, 1L);
-    verify(metrics).onTagCardinalityBlocked(new String[] {"collapsed:operation"}, 1L);
+    // operation is carried on the wire as the protobuf field "name", so it reports as
+    // collapsed:name
+    verify(metrics).onTagCardinalityBlocked(new String[] {"collapsed:name"}, 1L);
     verify(metrics).onTagCardinalityBlocked(new String[] {"collapsed:service_source"}, 1L);
     verify(metrics).onTagCardinalityBlocked(new String[] {"collapsed:type"}, 1L);
     verify(metrics).onTagCardinalityBlocked(new String[] {"collapsed:span_kind"}, 1L);

dd-trace-core/src/test/java/datadog/trace/common/metrics/PeerTagSchemaTest.java

@@ -6,10 +6,12 @@
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import datadog.trace.core.monitor.HealthMetrics;
+import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.HashSet;
 import java.util.LinkedHashSet;
+import java.util.List;
 import java.util.Set;
 import org.junit.jupiter.api.Test;
 
@@ -115,4 +117,38 @@ public void onTagCardinalityBlocked(String[] tag, long count) {
     schema.resetHandlers(hm, new CardinalityLimitReporter());
     assertEquals(0, recorded[0]);
   }
+
+  @Test
+  void resetHandlersAggregatesAllPeerTagsUnderSinglePeerTagsField() {
+    // The Cardinality Limits RFC reports peer-tag collapses under the protobuf field name peer_tags
+    // aggregated across every configured peer tag, not per individual tag name.
+    PeerTagSchema schema =
+        new PeerTagSchema(new String[] {"peer.hostname", "peer.service"}, PeerTagSchema.NO_STATE);
+    schema.handlers[0] = new TagCardinalityHandler("peer.hostname", 1, true);
+    schema.handlers[1] = new TagCardinalityHandler("peer.service", 1, true);
+
+    schema.register(0, "host-a"); // within limit
+    schema.register(0, "host-b"); // blocked
+    schema.register(1, "svc-a"); // within limit
+    schema.register(1, "svc-b"); // blocked
+    schema.register(1, "svc-c"); // blocked
+
+    List<String[]> tags = new ArrayList<>();
+    long[] total = {0};
+    HealthMetrics hm =
+        new HealthMetrics() {
+          @Override
+          public void onTagCardinalityBlocked(String[] tag, long count) {
+            tags.add(tag);
+            total[0] += count;
+          }
+        };
+
+    schema.resetHandlers(hm, new CardinalityLimitReporter());
+
+    // One health-metric call, tagged at the field granularity, summing both handlers' blocks.
+    assertEquals(1, tags.size());
+    assertArrayEquals(new String[] {"collapsed:peer_tags"}, tags.get(0));
+    assertEquals(3, total[0]);
+  }
 }