Bound configurable trace-stats cardinality limit

A mis-set trace.stats.<tag>.cardinality.limit flowed straight into
TagCardinalityHandler, which eagerly allocates four reference arrays of
nextPow2(limit * 2) slots. A large value could exhaust the heap while the
aggregator is constructed, before the tracer finished starting.

Cap the accepted value at 1 << 16 (~2 MB per handler worst case, far above
the largest built-in default of 1024) and fall back to the default with a
warning when it is exceeded, mirroring the existing <= 0 fallback.

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

Author: dougqh

internal-api/src/main/java/datadog/trace/api/Config.java

@@ -3895,6 +3895,17 @@ public int getTraceStatsInterval() {
     return traceStatsInterval;
   }
 
+  /**
+   * Upper bound for a configured stats cardinality limit. Each limit sizes a {@code
+   * TagCardinalityHandler} that eagerly allocates four reference arrays of {@code nextPow2(limit *
+   * 2)} slots, so an unbounded value (e.g. a mis-set env var) can exhaust the heap while the
+   * aggregator is constructed, before the tracer finishes starting. {@code 1 << 16} caps a single
+   * handler near ~2 MB while staying far above any useful setting -- the highest built-in default
+   * is 1024, and the aggregate table itself caps at a few thousand rows, so a larger per-key budget
+   * cannot produce more aggregate rows anyway.
+   */
+  private static final int MAX_TRACE_STATS_CARDINALITY_LIMIT = 1 << 16;
+
   /**
    * Returns the per-cycle cardinality limit for the named stats field, following the RFC naming
    * pattern {@code DD_TRACE_STATS_{tagName}_CARDINALITY_LIMIT} (e.g. {@code
@@ -3903,7 +3914,9 @@ public int getTraceStatsInterval() {
    *
    * <p>A non-positive configured value is invalid -- each limit sizes a fixed-capacity handler
    * table that requires a positive size -- so it falls back to {@code defaultLimit}, logged at
-   * debug.
+   * debug. A value above {@link #MAX_TRACE_STATS_CARDINALITY_LIMIT} would eagerly allocate handler
+   * tables large enough to exhaust the heap at startup, so it likewise falls back to {@code
+   * defaultLimit}, logged at warn.
    */
   public int getTraceStatsCardinalityLimit(String tagName, int defaultLimit) {
     int limit =
@@ -3916,6 +3929,15 @@ public int getTraceStatsCardinalityLimit(String tagName, int defaultLimit) {
           defaultLimit);
       return defaultLimit;
     }
+    if (limit > MAX_TRACE_STATS_CARDINALITY_LIMIT) {
+      log.warn(
+          "trace.stats.{}.cardinality.limit={} exceeds the maximum of {}; using default {} to avoid excessive memory use.",
+          tagName,
+          limit,
+          MAX_TRACE_STATS_CARDINALITY_LIMIT,
+          defaultLimit);
+      return defaultLimit;
+    }
     return limit;
   }
 

internal-api/src/test/java/datadog/trace/api/TraceStatsCardinalityLimitTest.java

@@ -8,6 +8,8 @@
 class TraceStatsCardinalityLimitTest {
 
   private static final int DEFAULT = 1024;
+  // Mirrors Config.MAX_TRACE_STATS_CARDINALITY_LIMIT (package-private, not visible here).
+  private static final int MAX = 1 << 16;
 
   private static Config configWith(String limit) {
     Properties props = new Properties();
@@ -29,4 +31,27 @@ void zeroFallsBackToDefault() {
   void negativeFallsBackToDefault() {
     assertEquals(DEFAULT, configWith("-5").getTraceStatsCardinalityLimit("resource", DEFAULT));
   }
+
+  @Test
+  void valueAtMaxIsUsed() {
+    // 1 << 16 is the largest accepted value; it is used verbatim.
+    assertEquals(
+        MAX, configWith(Integer.toString(MAX)).getTraceStatsCardinalityLimit("resource", DEFAULT));
+  }
+
+  @Test
+  void valueAboveMaxFallsBackToDefault() {
+    // One past the cap falls back rather than sizing an oversized handler table.
+    assertEquals(
+        DEFAULT,
+        configWith(Integer.toString(MAX + 1)).getTraceStatsCardinalityLimit("resource", DEFAULT));
+  }
+
+  @Test
+  void heapExhaustingValueFallsBackToDefault() {
+    // A value below TagCardinalityHandler's own 1<<29 guard but large enough to allocate
+    // multi-gigabyte handler tables must not reach the handler; it falls back to the default.
+    assertEquals(
+        DEFAULT, configWith("500000000").getTraceStatsCardinalityLimit("resource", DEFAULT));
+  }
 }