DataDog
diff --git a/‎dd-trace-api/src/main/java/datadog/trace/api/ConfigDefaults.java‎
Lines changed: 5 additions & 1 deletion b/‎dd-trace-api/src/main/java/datadog/trace/api/ConfigDefaults.java‎
Lines changed: 5 additions & 1 deletion
diff --git a/‎dd-trace-api/src/main/java/datadog/trace/api/config/GeneralConfig.java‎
Lines changed: 1 addition & 0 deletions b/‎dd-trace-api/src/main/java/datadog/trace/api/config/GeneralConfig.java‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎dd-trace-core/src/jmh/java/datadog/trace/common/metrics/AdditionalTagsMetricsBenchmark.java‎
Lines changed: 105 additions & 0 deletions b/‎dd-trace-core/src/jmh/java/datadog/trace/common/metrics/AdditionalTagsMetricsBenchmark.java‎
Lines changed: 105 additions & 0 deletions
diff --git a/‎dd-trace-core/src/jmh/java/datadog/trace/common/metrics/AdversarialMetricsBenchmark.java‎
Lines changed: 2 additions & 1 deletion b/‎dd-trace-core/src/jmh/java/datadog/trace/common/metrics/AdversarialMetricsBenchmark.java‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎dd-trace-core/src/jmh/java/datadog/trace/common/metrics/ClientStatsAggregatorBenchmark.java‎
Lines changed: 2 additions & 1 deletion b/‎dd-trace-core/src/jmh/java/datadog/trace/common/metrics/ClientStatsAggregatorBenchmark.java‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎dd-trace-core/src/jmh/java/datadog/trace/common/metrics/ClientStatsAggregatorDDSpanBenchmark.java‎
Lines changed: 2 additions & 1 deletion b/‎dd-trace-core/src/jmh/java/datadog/trace/common/metrics/ClientStatsAggregatorDDSpanBenchmark.java‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎dd-trace-core/src/jmh/java/datadog/trace/common/metrics/HighCardinalityPeerMetricsBenchmark.java‎
Lines changed: 2 additions & 1 deletion b/‎dd-trace-core/src/jmh/java/datadog/trace/common/metrics/HighCardinalityPeerMetricsBenchmark.java‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎dd-trace-core/src/jmh/java/datadog/trace/common/metrics/HighCardinalityResourceMetricsBenchmark.java‎
Lines changed: 2 additions & 1 deletion b/‎dd-trace-core/src/jmh/java/datadog/trace/common/metrics/HighCardinalityResourceMetricsBenchmark.java‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎dd-trace-core/src/main/java/datadog/trace/common/metrics/AdditionalTagsSchema.java‎
Lines changed: 132 additions & 0 deletions b/‎dd-trace-core/src/main/java/datadog/trace/common/metrics/AdditionalTagsSchema.java‎
Lines changed: 132 additions & 0 deletions
@@ -297,7 +297,11 @@ public final class ConfigDefaults {
 
   static final Set<String> DEFAULT_TRACE_EXPERIMENTAL_FEATURES_ENABLED =
       new HashSet<>(
-          asList("DD_TAGS", "DD_LOGS_INJECTION", "DD_EXPERIMENTAL_PROPAGATE_PROCESS_TAGS_ENABLED"));
+          asList(
+              "DD_TAGS",
+              "DD_LOGS_INJECTION",
+              "DD_EXPERIMENTAL_PROPAGATE_PROCESS_TAGS_ENABLED",
+              "DD_TRACE_STATS_ADDITIONAL_TAGS"));
 
   static final boolean DEFAULT_TRACE_128_BIT_TRACEID_GENERATION_ENABLED = true;
   static final boolean DEFAULT_TRACE_128_BIT_TRACEID_LOGGING_ENABLED = true;
 
@@ -87,6 +87,7 @@ public final class GeneralConfig {
   public static final String TRACER_METRICS_MAX_PENDING = "trace.tracer.metrics.max.pending";
   public static final String TRACER_METRICS_IGNORED_RESOURCES =
       "trace.tracer.metrics.ignored.resources";
+  public static final String TRACE_STATS_ADDITIONAL_TAGS = "trace.stats.additional.tags";
 
   public static final String AZURE_APP_SERVICES = "azure.app.services";
   public static final String INTERNAL_EXIT_ON_FAILURE = "trace.internal.exit.on.failure";
 
@@ -0,0 +1,105 @@
+package datadog.trace.common.metrics;
+
+import static datadog.trace.bootstrap.instrumentation.api.Tags.SPAN_KIND;
+import static datadog.trace.bootstrap.instrumentation.api.Tags.SPAN_KIND_CLIENT;
+import static java.util.concurrent.TimeUnit.SECONDS;
+
+import datadog.trace.api.WellKnownTags;
+import datadog.trace.core.CoreSpan;
+import de.thetaphi.forbiddenapis.SuppressForbidden;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.concurrent.ThreadLocalRandom;
+import org.openjdk.jmh.annotations.Benchmark;
+import org.openjdk.jmh.annotations.BenchmarkMode;
+import org.openjdk.jmh.annotations.Fork;
+import org.openjdk.jmh.annotations.Measurement;
+import org.openjdk.jmh.annotations.Mode;
+import org.openjdk.jmh.annotations.OutputTimeUnit;
+import org.openjdk.jmh.annotations.Param;
+import org.openjdk.jmh.annotations.Scope;
+import org.openjdk.jmh.annotations.Setup;
+import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.annotations.TearDown;
+import org.openjdk.jmh.annotations.Threads;
+import org.openjdk.jmh.annotations.Warmup;
+import org.openjdk.jmh.infra.Blackhole;
+
+/**
+ * Regression benchmark for the additional-tags hot path; {@code limitsEnabled=true} is slower here
+ * because it records more (sentinel collapses), not because limiting is expensive.
+ */
+@State(Scope.Benchmark)
+@Warmup(iterations = 2, time = 15, timeUnit = SECONDS)
+@Measurement(iterations = 5, time = 15, timeUnit = SECONDS)
+@BenchmarkMode(Mode.Throughput)
+@OutputTimeUnit(SECONDS)
+@Threads(8)
+@Fork(1)
+public class AdditionalTagsMetricsBenchmark {
+
+  private ClientStatsAggregator aggregator;
+  private AdversarialMetricsBenchmark.CountingHealthMetrics health;
+
+  @Param({"false", "true"})
+  public boolean limitsEnabled;
+
+  @State(Scope.Thread)
+  public static class ThreadState {
+    int cursor;
+  }
+
+  @Setup
+  public void setup() {
+    this.health = new AdversarialMetricsBenchmark.CountingHealthMetrics();
+    AdditionalTagsSchema additionalTagsSchema =
+        AdditionalTagsSchema.from(
+            new LinkedHashSet<>(Arrays.asList("region", "tenant_id")),
+            MetricCardinalityLimits.ADDITIONAL_TAG_VALUE,
+            limitsEnabled);
+    this.aggregator =
+        new ClientStatsAggregator(
+            new WellKnownTags("", "", "", "", "", ""),
+            Collections.emptySet(),
+            additionalTagsSchema,
+            new ClientStatsAggregatorBenchmark.FixedAgentFeaturesDiscovery(
+                Collections.singleton("peer.hostname"), Collections.emptySet()),
+            this.health,
+            new ClientStatsAggregatorBenchmark.NullSink(),
+            2048,
+            2048,
+            false);
+    this.aggregator.start();
+  }
+
+  @TearDown
+  @SuppressForbidden
+  public void tearDown() {
+    aggregator.close();
+    System.err.println("[ADDITIONAL-TAGS] counters (across all threads, single fork):");
+    System.err.println("  onStatsInboxFull         = " + health.inboxFull.sum());
+    System.err.println("  onStatsAggregateDropped  = " + health.aggregateDropped.sum());
+  }
+
+  @Benchmark
+  public void publish(ThreadState ts, Blackhole blackhole) {
+    int idx = ts.cursor++;
+    ThreadLocalRandom rng = ThreadLocalRandom.current();
+
+    int scrambled = idx * 0x9E3779B1;
+    String region = "region-" + ((scrambled >>> 4) & 0xFFFF);
+    String tenant = "tenant-" + ((scrambled >>> 16) & 0xFFFF);
+    long durationNanos = 1L + (rng.nextLong() & 0x3FFFFFFFL);
+
+    SimpleSpan span =
+        new SimpleSpan("svc", "op", "res", "web", true, true, false, 0, durationNanos, 200);
+    span.setTag(SPAN_KIND, SPAN_KIND_CLIENT);
+    span.setTag("region", region);
+    span.setTag("tenant_id", tenant);
+
+    List<CoreSpan<?>> trace = Collections.singletonList(span);
+    blackhole.consume(aggregator.publish(trace));
+  }
+}
@@ -57,7 +57,7 @@
 @BenchmarkMode(Mode.Throughput)
 @OutputTimeUnit(SECONDS)
 @Threads(8)
-@Fork(value = 1)
+@Fork(1)
 public class AdversarialMetricsBenchmark {
 
   private ClientStatsAggregator aggregator;
@@ -75,6 +75,7 @@ public void setup() {
         new ClientStatsAggregator(
             new WellKnownTags("", "", "", "", "", ""),
             Collections.emptySet(),
+            AdditionalTagsSchema.EMPTY,
             new ClientStatsAggregatorBenchmark.FixedAgentFeaturesDiscovery(
                 Collections.singleton("peer.hostname"), Collections.emptySet()),
             this.health,
 
@@ -33,7 +33,7 @@
 @Measurement(iterations = 3, time = 30, timeUnit = SECONDS)
 @BenchmarkMode(Mode.AverageTime)
 @OutputTimeUnit(MICROSECONDS)
-@Fork(value = 1)
+@Fork(1)
 public class ClientStatsAggregatorBenchmark {
   private final DDAgentFeaturesDiscovery featuresDiscovery =
       new FixedAgentFeaturesDiscovery(
@@ -42,6 +42,7 @@ public class ClientStatsAggregatorBenchmark {
       new ClientStatsAggregator(
           new WellKnownTags("", "", "", "", "", ""),
           Collections.emptySet(),
+          AdditionalTagsSchema.EMPTY,
           featuresDiscovery,
           HealthMetrics.NO_OP,
           new NullSink(),
 
@@ -49,7 +49,7 @@
 @Measurement(iterations = 3, time = 30, timeUnit = SECONDS)
 @BenchmarkMode(Mode.AverageTime)
 @OutputTimeUnit(MICROSECONDS)
-@Fork(value = 1)
+@Fork(1)
 public class ClientStatsAggregatorDDSpanBenchmark {
 
   private static final CoreTracer TRACER =
@@ -62,6 +62,7 @@ public class ClientStatsAggregatorDDSpanBenchmark {
       new ClientStatsAggregator(
           new WellKnownTags("", "", "", "", "", ""),
           Collections.emptySet(),
+          AdditionalTagsSchema.EMPTY,
           featuresDiscovery,
           HealthMetrics.NO_OP,
           new ClientStatsAggregatorBenchmark.NullSink(),
 
@@ -47,7 +47,7 @@
 @BenchmarkMode(Mode.Throughput)
 @OutputTimeUnit(SECONDS)
 @Threads(8)
-@Fork(value = 1)
+@Fork(1)
 public class HighCardinalityPeerMetricsBenchmark {
 
   private ClientStatsAggregator aggregator;
@@ -65,6 +65,7 @@ public void setup() {
         new ClientStatsAggregator(
             new WellKnownTags("", "", "", "", "", ""),
             Collections.emptySet(),
+            AdditionalTagsSchema.EMPTY,
             new ClientStatsAggregatorBenchmark.FixedAgentFeaturesDiscovery(
                 Collections.singleton("peer.hostname"), Collections.emptySet()),
             this.health,
 
@@ -43,7 +43,7 @@
 @BenchmarkMode(Mode.Throughput)
 @OutputTimeUnit(SECONDS)
 @Threads(8)
-@Fork(value = 1)
+@Fork(1)
 public class HighCardinalityResourceMetricsBenchmark {
 
   private ClientStatsAggregator aggregator;
@@ -61,6 +61,7 @@ public void setup() {
         new ClientStatsAggregator(
             new WellKnownTags("", "", "", "", "", ""),
             Collections.emptySet(),
+            AdditionalTagsSchema.EMPTY,
             new ClientStatsAggregatorBenchmark.FixedAgentFeaturesDiscovery(
                 Collections.singleton("peer.hostname"), Collections.emptySet()),
             this.health,
 
@@ -0,0 +1,132 @@
+package datadog.trace.common.metrics;
+
+import datadog.trace.bootstrap.instrumentation.api.UTF8BytesString;
+import datadog.trace.core.monitor.HealthMetrics;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Set;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Immutable schema of configured span-derived primary tag keys; built once at aggregator
+ * construction.
+ */
+final class AdditionalTagsSchema {
+
+  private static final Logger log = LoggerFactory.getLogger(AdditionalTagsSchema.class);
+
+  // Backend stats pipeline only supports a few primary tag dimensions; drop overflow at startup.
+  static final int MAX_ADDITIONAL_TAG_KEYS = 4;
+
+  // Health-metric statsD tags per the approved Cardinality Limits RFC (section 5): collapses are
+  // reported under the lowercased protobuf field name additional_metric_tags, with cardinality-
+  // collapses (collapsed:) and per-value length-collapses (oversized:) tagged distinctly.
+  private static final String[] COLLAPSED_STATSD_TAG = {"collapsed:additional_metric_tags"};
+  private static final String[] OVERSIZED_STATSD_TAG = {"oversized:additional_metric_tags"};
+
+  /** Singleton empty schema returned when no additional tags are configured. */
+  static final AdditionalTagsSchema EMPTY =
+      new AdditionalTagsSchema(new String[0], new TagCardinalityHandler[0]);
+
+  final String[] names;
+
+  /** Per-key handlers providing UTF8 caching and per-cycle cardinality limiting. */
+  private final TagCardinalityHandler[] handlers;
+
+  private AdditionalTagsSchema(String[] names, TagCardinalityHandler[] handlers) {
+    this.names = names;
+    this.handlers = handlers;
+  }
+
+  /** Test convenience: limits enabled. */
+  static AdditionalTagsSchema from(Set<String> configured) {
+    return from(
+        configured,
+        MetricCardinalityLimits.ADDITIONAL_TAG_VALUE,
+        MetricCardinalityLimits.USE_BLOCKED_SENTINEL);
+  }
+
+  static AdditionalTagsSchema from(Set<String> configured, int limit, boolean useBlockedSentinel) {
+    if (configured == null || configured.isEmpty()) {
+      return EMPTY;
+    }
+    List<String> valid = new ArrayList<>();
+    for (String key : configured) {
+      if (key == null || key.isEmpty()) {
+        log.warn("Ignoring empty additional metric tag key");
+        continue;
+      }
+      if (key.contains(":")) {
+        log.warn("Ignoring additional metric tag key '{}': keys must not contain ':'", key);
+        continue;
+      }
+      valid.add(key);
+    }
+    if (valid.isEmpty()) {
+      return EMPTY;
+    }
+    Collections.sort(valid);
+    // Keys arrive as a Set, so they are already distinct — no dedup needed.
+    if (valid.size() > MAX_ADDITIONAL_TAG_KEYS) {
+      log.warn(
+          "Configured additional metric tag keys ({}) exceeds the supported limit of {}; "
+              + "dropping extra keys: {}",
+          valid.size(),
+          MAX_ADDITIONAL_TAG_KEYS,
+          valid.subList(MAX_ADDITIONAL_TAG_KEYS, valid.size()));
+      valid = valid.subList(0, MAX_ADDITIONAL_TAG_KEYS);
+    }
+    String[] namesArr = valid.toArray(new String[0]);
+    TagCardinalityHandler[] handlersArr = new TagCardinalityHandler[namesArr.length];
+    for (int i = 0; i < namesArr.length; i++) {
+      handlersArr[i] =
+          new TagCardinalityHandler(
+              namesArr[i],
+              limit,
+              useBlockedSentinel,
+              MetricCardinalityLimits.ADDITIONAL_TAG_MAX_VALUE_LENGTH);
+    }
+    return new AdditionalTagsSchema(namesArr, handlersArr);
+  }
+
+  int size() {
+    return names.length;
+  }
+
+  String name(int i) {
+    return names[i];
+  }
+
+  UTF8BytesString register(int i, String value) {
+    return handlers[i].register(value);
+  }
+
+  void resetHandlers(HealthMetrics healthMetrics, CardinalityLimitReporter reporter) {
+    long totalCollapsed = 0;
+    long totalOversized = 0;
+    for (int i = 0; i < handlers.length; i++) {
+      // oversizedCount() must be read before reset(), which zeroes both per-cycle counts.
+      long oversized = handlers[i].oversizedCount();
+      long collapsed = handlers[i].reset();
+      // The human-facing reporter names the specific tag that triggered the block, so it records
+      // both collapse kinds under the tag's own name.
+      long blocked = collapsed + oversized;
+      if (blocked > 0) {
+        reporter.record(names[i], blocked);
+      }
+      totalCollapsed += collapsed;
+      totalOversized += oversized;
+    }
+    // The health metric is reported at the additional_metric_tags field granularity (not per tag
+    // name), with cardinality-collapses and length-collapses ("oversized") tagged distinctly per
+    // the approved Cardinality Limits RFC.
+    if (totalCollapsed > 0) {
+      healthMetrics.onTagCardinalityBlocked(COLLAPSED_STATSD_TAG, totalCollapsed);
+    }
+    if (totalOversized > 0) {
+      healthMetrics.onTagCardinalityBlocked(OVERSIZED_STATSD_TAG, totalOversized);
+    }
+  }
+}