Store known span tags densely in TagMap by tag-id (phase 2)

dd-trace-api/src/main/java/datadog/trace/api/config/TracerConfig.java

@@ -182,5 +182,12 @@ public final class TracerConfig {
   public static final String TRACE_ORG_GUARD_STRICT = "trace.org.guard.strict";
   public static final String TRACE_ORG_GUARD_TRUSTED_OPMS = "trace.org.guard.trusted.opms";
 
+  /**
+   * Routes known tags through the dense (id-keyed) tag store instead of per-tag entries.
+   * Experimental, OFF by default. The {@code KnownTagCodec} is registered regardless; this flag
+   * only selects whether tags take the dense storage path.
+   */
+  public static final String TRACE_DENSE_TAGS_ENABLED = "trace.experimental.dense.tags.enabled";
+
   private TracerConfig() {}
 }

dd-trace-core/src/main/java/datadog/trace/core/CoreTracer.java

@@ -41,6 +41,7 @@
 import datadog.trace.api.EndpointTracker;
 import datadog.trace.api.IdGenerationStrategy;
 import datadog.trace.api.InstrumenterConfig;
+import datadog.trace.api.KnownTags;
 import datadog.trace.api.Pair;
 import datadog.trace.api.TagMap;
 import datadog.trace.api.TraceConfig;
@@ -663,6 +664,13 @@ private CoreTracer(
     // preload this enum to avoid triggering classloading on the hot path
     TraceCollector.PublishState.values();
 
+    // Register the KnownTagCodec resolver unconditionally so tag-id name resolution (keyOf/nameOf,
+    // OTel name mapping) is always live. Whether known tags actually take the dense store is a
+    // separate, const-folded decision (KnownTagCodec.DENSE_STORE, from
+    // trace.experimental.dense.tags.enabled); when that flag is off, tag storage is byte-identical
+    // to the bucket-only behavior.
+    KnownTags.init();
+
     if (reportInTracerFlare) {
       TracerFlare.addReporter(this);
     }

internal-api/src/jmh/java/datadog/trace/api/DenseStoreAllocBenchmark.java

@@ -0,0 +1,150 @@
+package datadog.trace.api;
+
+import datadog.trace.bootstrap.instrumentation.api.Tags;
+import java.util.concurrent.TimeUnit;
+import org.openjdk.jmh.annotations.Benchmark;
+import org.openjdk.jmh.annotations.BenchmarkMode;
+import org.openjdk.jmh.annotations.Fork;
+import org.openjdk.jmh.annotations.Level;
+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.Threads;
+import org.openjdk.jmh.annotations.Warmup;
+import org.openjdk.jmh.infra.Blackhole;
+
+/**
+ * Deterministic allocation A/B for the dense known-tag store, using the REAL {@link KnownTags}
+ * resolver (a {@code StringIndex} probe + a constant-returning {@code switch} — allocation-free,
+ * exactly like production). An earlier synthetic prefix resolver allocated in {@code keyOf}
+ * (substring) and {@code nameOf} (concat), contaminating the dense arm; this measures the store,
+ * not the resolver.
+ *
+ * <p>Models how a real span's tags route: {@code today} = all custom (what ships now — every tag
+ * buckets, since nothing is registered as known), {@code dense} = the same tag count with a
+ * realistic fraction routed to the dense store (real known tag names) and the rest custom. Run with
+ * {@code -prof gc}; the {@code gc.alloc.rate.norm} (B/op) delta at the same {@code tagCount} is
+ * what enabling the dense store does to a real span's per-build allocation.
+ *
+ * <p><b>Results — buildMap, JDK 17 (Zulu 17.0.7, Apple Silicon), {@code -prof gc -f 1 -wi 2 -i 3},
+ * 2026-07-08.</b> Allocation is deterministic (±0.001 B/op); throughput on this run is NOT
+ * trustworthy (single fork, short) — read B/op only.
+ *
+ * <pre>{@code
+ * scenario    tagCount=7   tagCount=12
+ * today          408 B/op     704 B/op
+ * dense          376 B/op     416 B/op
+ * allKnown       176 B/op     400 B/op
+ * }</pre>
+ *
+ * <p>Gate met: {@code dense < today} at both counts (the over-provision artifact is gone). The
+ * Entry-less win scales with the known-tag fraction — ~8% at 7 tags (~70% known), ~41% at 12;
+ * {@code allKnown} (the codegen endgame / read-through parent shape) reaches ~57% at 7.
+ *
+ * <p><b>Serialize paths (same run, B/op).</b> {@code buildAndSerialize} (alloc-free {@code forEach}
+ * flyweight) adds a flat +16 B/op over {@code buildMap} in every scenario (7: 392, 12: 432 dense).
+ * {@code buildAndSerializeViaIterator} — the {@code EntryReader} enhanced-for modeling the count
+ * pre-pass at {@code TraceMapperV0_4:95} — adds a CONSTANT per-call cost (+56 custom / +80 dense,
+ * identical at 7 and 12 tags): that flat-vs-tagCount signature is the {@code EntryReaderIterator}
+ * OBJECT, NOT per-tag Entry — the iterator reuses a dense flyweight (TagMap:2182/2652). So the
+ * dense win SURVIVES serialization; the only nit is {@code iterator()} allocating one Iterator per
+ * call, which {@code forEach} avoids and which can be recycled away.
+ */
+@State(Scope.Benchmark)
+@BenchmarkMode(Mode.Throughput)
+@OutputTimeUnit(TimeUnit.SECONDS)
+@Warmup(iterations = 2, time = 2)
+@Measurement(iterations = 3, time = 2)
+@Fork(
+    value = 1,
+    jvmArgsAppend = {"-Ddd.trace.experimental.dense.tags.enabled=true"})
+@Threads(1)
+public class DenseStoreAllocBenchmark {
+
+  // Real stored (dense-routed) tag names — a realistic web/db span's known set.
+  static final String[] KNOWN =
+      new String[] {
+        DDTags.BASE_SERVICE,
+        Tags.VERSION,
+        Tags.COMPONENT,
+        Tags.SPAN_KIND,
+        Tags.HTTP_METHOD,
+        Tags.HTTP_ROUTE,
+        Tags.DB_TYPE,
+        Tags.DB_INSTANCE,
+        Tags.PEER_HOSTNAME,
+        Tags.DB_USER,
+        DDTags.LANGUAGE_TAG_KEY,
+        Tags.PEER_PORT,
+      };
+
+  // today = all custom (all bucket, what ships now); dense = ~70% known + custom (a real span);
+  // allKnown = 100% known (the trace-tier read-through parent's shape — exercises lazy buckets).
+  @Param({"today", "dense", "allKnown"})
+  String scenario;
+
+  @Param({"7", "12"})
+  int tagCount;
+
+  private String[] keys;
+  private String[] values;
+
+  @Setup(Level.Trial)
+  public void setup() {
+    KnownTags.init(); // registers the real (allocation-free) resolver
+    int knownCount;
+    if ("allKnown".equals(scenario)) {
+      knownCount = tagCount; // 100% known (<= KNOWN.length)
+    } else if ("dense".equals(scenario)) {
+      knownCount = (tagCount * 7) / 10; // ~70% known + custom
+    } else {
+      knownCount = 0; // today: all custom (all bucket)
+    }
+    this.keys = new String[tagCount];
+    this.values = new String[tagCount];
+    for (int i = 0; i < tagCount; i++) {
+      this.keys[i] = i < knownCount ? KNOWN[i] : "custom.tag." + i;
+      this.values[i] = "value-" + i;
+    }
+  }
+
+  @Benchmark
+  public TagMap buildMap() {
+    TagMap m = TagMap.create(16);
+    for (int i = 0; i < tagCount; i++) {
+      m.set(keys[i], values[i]);
+    }
+    return m;
+  }
+
+  @Benchmark
+  public void buildAndSerialize(Blackhole bh) {
+    TagMap m = TagMap.create(16);
+    for (int i = 0; i < tagCount; i++) {
+      m.set(keys[i], values[i]);
+    }
+    // forEach: the alloc-free flyweight emit for dense
+    m.forEach(reader -> bh.consume(reader.objectValue()));
+    bh.consume(m);
+  }
+
+  @Benchmark
+  public void buildAndSerializeViaIterator(Blackhole bh) {
+    TagMap m = TagMap.create(16);
+    for (int i = 0; i < tagCount; i++) {
+      m.set(keys[i], values[i]);
+    }
+    // models the REAL serializer's count pre-pass (TraceMapperV0_4:95). The EntryReader iterator
+    // uses a reused dense flyweight (NO per-tag Entry alloc — TagMap:2182/2652), so the dense win
+    // SURVIVES; the only extra cost vs forEach is the EntryReaderIterator object itself (a fixed
+    // per-call cost, constant across tagCount — not per-tag). forEach avoids even that.
+    for (TagMap.EntryReader reader : m) {
+      bh.consume(reader.objectValue());
+    }
+    bh.consume(m);
+  }
+}

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

@@ -1447,6 +1447,7 @@ public static String getHostName() {
   private final boolean jdkSocketEnabled;
 
   private final boolean spanBuilderReuseEnabled;
+  private final boolean traceDenseTagsEnabled;
   private final int tagNameUtf8CacheSize;
   private final int tagValueUtf8CacheSize;
   private final int stackTraceLengthLimit;
@@ -3414,6 +3415,8 @@ PROFILING_DATADOG_PROFILER_ENABLED, isDatadogProfilerSafeInCurrentEnvironment())
 
     this.spanBuilderReuseEnabled =
         configProvider.getBoolean(GeneralConfig.SPAN_BUILDER_REUSE_ENABLED, true);
+    this.traceDenseTagsEnabled =
+        configProvider.getBoolean(TracerConfig.TRACE_DENSE_TAGS_ENABLED, false);
     this.tagNameUtf8CacheSize =
         Math.max(configProvider.getInteger(GeneralConfig.TAG_NAME_UTF8_CACHE_SIZE, 128), 0);
     this.tagValueUtf8CacheSize =
@@ -5338,6 +5341,10 @@ public boolean isSpanBuilderReuseEnabled() {
     return spanBuilderReuseEnabled;
   }
 
+  public boolean isTraceDenseTagsEnabled() {
+    return traceDenseTagsEnabled;
+  }
+
   public int getTagNameUtf8CacheSize() {
     return tagNameUtf8CacheSize;
   }