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

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

@@ -40,6 +40,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;
@@ -656,6 +657,14 @@ private CoreTracer(
     // preload this enum to avoid triggering classloading on the hot path
     TraceCollector.PublishState.values();
 
+    // Dense known-tag store (experimental, OFF by default): registering the KnownTagCodec resolver
+    // flips the dense store live so known tags store without a per-tag Entry. Gated by a system
+    // property for A/B benchmarking; when off, keyOf stays a no-op and tag storage is byte-identical
+    // to today. Promote to a Config flag if this becomes a permanent rollout.
+    if (Boolean.getBoolean("dd.trace.dense.tags.enabled")) {
+      KnownTags.init();
+    }
+
     if (reportInTracerFlare) {
       TracerFlare.addReporter(this);
     }
@@ -2206,18 +2215,31 @@ protected static final DDSpanContext buildSpanContext(
               propagationTags,
               tracer.profilingContextIntegration,
               tracer.injectBaggageAsTags,
-              tracer.injectLinksAsTags);
+              tracer.injectLinksAsTags,
+              mergedTracerTagsNeedsIntercept ? null : mergedTracerTags);
 
       // By setting the tags on the context we apply decorators to any tags that have been set via
       // the builder. This is the order that the tags were added previously, but maybe the `tags`
       // set in the builder should come last, so that they override other tags.
-      context.setAllTags(mergedTracerTags, mergedTracerTagsNeedsIntercept);
+      //
+      // mergedTracerTags is trace-level shared state and the precedence floor (everything below
+      // overrides it). When it carries no interceptable tags it is attached as a read-through
+      // PARENT at construction (shared by reference, no per-span copy). When it does need
+      // interception, copy its entries in (the interceptor's per-span side-effects can't be
+      // shared by reference).
+      if (mergedTracerTagsNeedsIntercept) {
+        context.setAllTags(mergedTracerTags, true);
+      }
       context.setAllTags(tagLedger);
       context.setAllTags(coreTags, coreTagsNeedsIntercept);
       context.setAllTags(rootSpanTags, rootSpanTagsNeedsIntercept);
       context.setAllTags(contextualTags);
-      // remove version here since will be done later on the postProcessor.
-      // it will allow knowing if it will be set manually or not
+      // Version is added later by the postProcessor (InternalTagsAdder), only if not already set
+      // during the request. Config version is kept out of the trace-level bundle (see
+      // withTracerTags), so this removal now only wipes a version set via the span builder —
+      // keeping
+      // the existing semantics where a builder-set version is replaced by the config version. Under
+      // read-through this is a cheap local removal (version isn't in the parent, so no tombstone).
       context.removeTag(Tags.VERSION);
       return context;
     }
@@ -2448,6 +2470,13 @@ static TagMap withTracerTags(
       Map<String, ?> userSpanTags, Config config, TraceConfig traceConfig) {
     final TagMap result = TagMap.create(userSpanTags.size() + 5);
     result.putAll(userSpanTags);
+    // Version is conditionally managed by InternalTagsAdder (added only when service == DD_SERVICE
+    // and not set during the request), so keep it OUT of the trace-level bundle. This matters under
+    // read-through: the bundle becomes a shared parent, and a per-span removeTag(VERSION) on a key
+    // that lived in the parent would mint a per-span tombstone. With version excluded here, the
+    // per-span removeTag (retained, to wipe a builder-set version) is a cheap local op, never a
+    // tombstone. Behavior is unchanged: version was applied-then-removed at build today.
+    result.remove(Tags.VERSION);
     if (null != config) { // static
       if (!config.getEnv().isEmpty()) {
         result.set("env", config.getEnv());

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

@@ -243,7 +243,8 @@ public DDSpanContext(
         propagationTags,
         ProfilingContextIntegration.NoOp.INSTANCE,
         true,
-        true);
+        true,
+        null);
   }
 
   public DDSpanContext(
@@ -293,9 +294,11 @@ public DDSpanContext(
         propagationTags,
         ProfilingContextIntegration.NoOp.INSTANCE,
         injectBaggageAsTags,
-        injectLinksAsTags);
+        injectLinksAsTags,
+        null);
   }
 
+  /** Back-compat ctor (no read-through parent); delegates with a null parent. */
   public DDSpanContext(
       final DDTraceId traceId,
       final long spanId,
@@ -322,6 +325,62 @@ public DDSpanContext(
       final ProfilingContextIntegration profilingContextIntegration,
       final boolean injectBaggageAsTags,
       final boolean injectLinksAsTags) {
+    this(
+        traceId,
+        spanId,
+        parentId,
+        parentServiceName,
+        serviceNameSource,
+        serviceName,
+        operationName,
+        resourceName,
+        samplingPriority,
+        origin,
+        baggageItems,
+        w3cBaggage,
+        errorFlag,
+        spanType,
+        tagsSize,
+        traceCollector,
+        requestContextDataAppSec,
+        requestContextDataIast,
+        CiVisibilityContextData,
+        pathwayContext,
+        disableSamplingMechanismValidation,
+        propagationTags,
+        profilingContextIntegration,
+        injectBaggageAsTags,
+        injectLinksAsTags,
+        null);
+  }
+
+  public DDSpanContext(
+      final DDTraceId traceId,
+      final long spanId,
+      final long parentId,
+      final CharSequence parentServiceName,
+      final CharSequence serviceNameSource,
+      final String serviceName,
+      final CharSequence operationName,
+      final CharSequence resourceName,
+      final int samplingPriority,
+      final CharSequence origin,
+      final Map<String, String> baggageItems,
+      final Baggage w3cBaggage,
+      final boolean errorFlag,
+      final CharSequence spanType,
+      final int tagsSize,
+      final TraceCollector traceCollector,
+      final Object requestContextDataAppSec,
+      final Object requestContextDataIast,
+      final Object CiVisibilityContextData,
+      final PathwayContext pathwayContext,
+      final boolean disableSamplingMechanismValidation,
+      final PropagationTags propagationTags,
+      final ProfilingContextIntegration profilingContextIntegration,
+      final boolean injectBaggageAsTags,
+      final boolean injectLinksAsTags,
+      final TagMap readThroughParent) {
 
     assert traceCollector != null;
     this.traceCollector = traceCollector;
@@ -350,7 +409,10 @@ public DDSpanContext(
     // The +1 is the magic number from the tags below that we set at the end,
     // and "* 4 / 3" is to make sure that we don't resize immediately
     final int capacity = Math.max((tagsSize <= 0 ? 3 : (tagsSize + 1)) * 4 / 3, 8);
-    this.unsafeTags = TagMap.create(capacity);
+    this.unsafeTags =
+        readThroughParent != null
+            ? TagMap.createFromParent(readThroughParent)
+            : TagMap.create(capacity);
 
     // must set this before setting the service and resource names below
     this.profilingContextIntegration = profilingContextIntegration;

gradle/libs.versions.toml

@@ -42,6 +42,7 @@ jmh = "1.37"
 # Profiling
 jmc = "8.1.0"
 jafar = "0.16.0"
+jol = "0.17"
 
 # Web & Network
 jnr-unixsocket = "0.38.25"
@@ -125,6 +126,7 @@ instrument-java = { module = "com.datadoghq:dd-instrument-java", version.ref = "
 jmc-common = { module = "org.openjdk.jmc:common", version.ref = "jmc" }
 jmc-flightrecorder = { module = "org.openjdk.jmc:flightrecorder", version.ref = "jmc" }
 jafar-tools = { module = "io.btrace:jafar-tools", version.ref = "jafar" }
+jol-core = { module = "org.openjdk.jol:jol-core", version.ref = "jol" }
 
 # Web & Network
 okio = { module = "com.datadoghq.okio:okio", version.ref = "okio" }

internal-api/build.gradle.kts

@@ -282,6 +282,7 @@ dependencies {
   testImplementation("org.junit.vintage:junit-vintage-engine:${libs.versions.junit5.get()}")
   testImplementation(libs.commons.math)
   testImplementation(libs.bundles.mockito)
+  testImplementation(libs.jol.core)
 }
 
 jmh {

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

@@ -0,0 +1,148 @@
+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(1)
+@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);
+  }
+}