Wire mergedTracerTags as a read-through parent at span build (level-split phase 1)

Attach the trace's merged tracer tags to each span's TagMap as a frozen
read-through parent (via TagMap.createFromParent) at span construction,
instead of copying them into every span. The span sees the shared tags on
read and only stores its own local tags, so the common trace-level bundle
is held once per trace rather than duplicated per span.

- CoreTracer builds the frozen merged-tracer-tags parent once; config
  version is kept out of that bundle.
- DDSpanContext attaches the parent at construction (fixed, no re-parenting).
- Adds TagMapReadThroughBenchmark (copy-down vs read-through, -prof gc).

Stacked on the read-through mechanism (#11789), which builds on the folded
final-class TagMap (#11967).

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

Author: dougqh

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

@@ -2206,18 +2206,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 +2461,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;

internal-api/src/jmh/java/datadog/trace/util/TagMapReadThroughBenchmark.java

@@ -0,0 +1,84 @@
+package datadog.trace.util;
+
+import datadog.trace.api.TagMap;
+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;
+
+/**
+ * Models span-build tag assembly with vs without read-through of the shared trace-level bundle.
+ *
+ * <ul>
+ *   <li><b>copyDown</b> — today's path: {@code putAll} the (frozen) trace-level bundle into the
+ *       fresh span map, then set the span-specific tags. {@code putAll}-into-empty shares the
+ *       frozen entry references (bucket-clone), so this does NOT allocate new Entry objects for the
+ *       trace tags — its cost is cloned {@code BucketGroup}s plus the collisions caused by the
+ *       trace tags sharing the local buckets with the span tags.
+ *   <li><b>readThrough</b> — attach the frozen bundle as a read-through parent; only the
+ *       span-specific tags are stored locally.
+ * </ul>
+ *
+ * <p>Run with {@code -prof gc}; the B/op delta is the per-span allocation read-through saves. Both
+ * arms set the same span tags, so the delta isolates the trace-bundle handling. {@code
+ * traceTagCount} sweeps the bundle size — the win scales with it (more trace tags → more cloned
+ * BucketGroups and local collisions avoided). {@code traceTagCount = 7} ≈ a realistic
+ * mergedTracerTags (env, version, language, runtime-id, a propagation tag, a couple global tags).
+ */
+@State(Scope.Benchmark)
+@BenchmarkMode(Mode.Throughput)
+@OutputTimeUnit(TimeUnit.SECONDS)
+@Warmup(iterations = 5, time = 2)
+@Measurement(iterations = 5, time = 2)
+@Fork(3)
+@Threads(8)
+public class TagMapReadThroughBenchmark {
+
+  @Param({"3", "7", "15"})
+  int traceTagCount;
+
+  private TagMap traceTags;
+
+  @Setup(Level.Trial)
+  public void setup() {
+    TagMap m = TagMap.create(Math.max(16, traceTagCount * 2));
+    for (int i = 0; i < traceTagCount; i++) {
+      m.set("_dd.trace.tag." + i, "trace-value-" + i);
+    }
+    this.traceTags = m.freeze();
+  }
+
+  @Benchmark
+  public TagMap copyDown() {
+    TagMap m = TagMap.create(16);
+    m.putAll(traceTags); // putAll-into-empty: shares frozen entries, clones BucketGroups
+    setSpanTags(m);
+    return m;
+  }
+
+  @Benchmark
+  public TagMap readThrough() {
+    // no copy; trace tags read through the shared frozen parent (fixed at construction)
+    TagMap m = TagMap.createFromParent(traceTags);
+    setSpanTags(m);
+    return m;
+  }
+
+  private static void setSpanTags(TagMap m) {
+    m.set("http.method", "GET");
+    m.set("http.url", "/api/checkout/cart");
+    m.set("component", "spring-web-controller");
+    m.set("span.kind", "server");
+    m.set("http.status_code", 200);
+  }
+}