Pre-merge immutable tag sources to reduce tag-merge overhead in span creation

buildSpanContext() called setAllTags() 5 times per span, with two of
those sources (mergedTracerTags, localRootSpanTags) being immutable
across all spans. Every span redundantly re-merged them plus ran a
per-span removeTag(Tags.VERSION).

This change pre-merges those frozen tag sources into a
preMergedRootSpanBase template at ConfigSnapshot creation time and
initializes each span's TagMap via copy from the template. Root spans
go from 5 setAllTags + removeTag to 3 setAllTags; child spans go from
2 effective setAllTags to 1.

tag: no release note
tag: ai generated

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: dougqh

dd-trace-core/src/jmh/java/datadog/trace/core/TagMergeBenchmark.java

@@ -0,0 +1,43 @@
+package datadog.trace.core;
+
+import static java.util.concurrent.TimeUnit.MICROSECONDS;
+
+import datadog.trace.bootstrap.instrumentation.api.AgentSpan;
+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.Scope;
+import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.annotations.Threads;
+import org.openjdk.jmh.annotations.Warmup;
+
+/**
+ * Benchmark measuring the tag-merge optimization in buildSpanContext.
+ *
+ * <p>Compares root span creation (which uses the pre-merged template of mergedTracerTags +
+ * localRootSpanTags) versus child span creation (which uses mergedTracerTags as template).
+ */
+@State(Scope.Benchmark)
+@Warmup(iterations = 3)
+@Measurement(iterations = 5)
+@BenchmarkMode(Mode.Throughput)
+@Threads(8)
+@OutputTimeUnit(MICROSECONDS)
+@Fork(value = 1)
+public class TagMergeBenchmark {
+  static final CoreTracer TRACER = CoreTracer.builder().build();
+
+  @Benchmark
+  public AgentSpan rootSpan() {
+    return TRACER.startSpan("foo", "bar");
+  }
+
+  @Benchmark
+  public AgentSpan childSpan() {
+    AgentSpan root = TRACER.startSpan("foo", "bar");
+    return TRACER.startSpan("foo", "child", root.context());
+  }
+}

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

@@ -688,6 +688,17 @@ private CoreTracer(
     this.defaultSpanTags = defaultSpanTags;
     this.defaultSpanTagsNeedsIntercept = this.tagInterceptor.needsIntercept(this.defaultSpanTags);
 
+    // Initialize localRootSpanTags before dynamicConfig so ConfigSnapshot can pre-merge them
+    if (profilingContextIntegration != ProfilingContextIntegration.NoOp.INSTANCE) {
+      TagMap tmp = TagMap.fromMap(localRootSpanTags);
+      tmp.put(PROFILING_CONTEXT_ENGINE, profilingContextIntegration.name());
+      this.localRootSpanTags = tmp.freeze();
+    } else {
+      this.localRootSpanTags = TagMap.fromMapImmutable(localRootSpanTags);
+    }
+    this.localRootSpanTagsNeedIntercept =
+        this.tagInterceptor.needsIntercept(this.localRootSpanTags);
+
     this.dynamicConfig =
         DynamicConfig.create(ConfigSnapshot::new)
             .setTracingEnabled(true) // implied by installation of CoreTracer
@@ -866,16 +877,7 @@ private CoreTracer(
     this.injectBaggageAsTags = injectBaggageAsTags;
     this.flushOnClose = flushOnClose;
     this.allowInferredServices = SpanNaming.instance().namingSchema().allowInferredServices();
-    if (profilingContextIntegration != ProfilingContextIntegration.NoOp.INSTANCE) {
-      TagMap tmp = TagMap.fromMap(localRootSpanTags);
-      tmp.put(PROFILING_CONTEXT_ENGINE, profilingContextIntegration.name());
-      this.localRootSpanTags = tmp.freeze();
-    } else {
-      this.localRootSpanTags = TagMap.fromMapImmutable(localRootSpanTags);
-    }
-
-    this.localRootSpanTagsNeedIntercept =
-        this.tagInterceptor.needsIntercept(this.localRootSpanTags);
+    // localRootSpanTags already initialized above (before dynamicConfig)
     if (serviceDiscoveryFactory != null) {
       AgentTaskScheduler.get()
           .schedule(
@@ -2073,14 +2075,23 @@ protected static final DDSpanContext buildSpanContext(
         operationName = resourceName;
       }
 
-      final TagMap mergedTracerTags = traceConfig.mergedTracerTags;
-      boolean mergedTracerTagsNeedsIntercept = traceConfig.mergedTracerTagsNeedsIntercept;
+      // Use pre-merged template for root spans, mergedTracerTags template for child spans
+      final TagMap tagBase;
+      final boolean tagBaseNeedsIntercept;
+      if (rootSpanTags != null) {
+        // Root span: use pre-merged template (mergedTracerTags + rootSpanTags - Tags.VERSION)
+        tagBase = traceConfig.preMergedRootSpanBase;
+        tagBaseNeedsIntercept = traceConfig.preMergedRootSpanBaseNeedsIntercept;
+      } else {
+        // Child span: use mergedTracerTags as template
+        tagBase = traceConfig.mergedTracerTags;
+        tagBaseNeedsIntercept = traceConfig.mergedTracerTagsNeedsIntercept;
+      }
 
       final int tagsSize =
-          mergedTracerTags.size()
+          tagBase.size()
               + (null == tagLedger ? 0 : tagLedger.estimateSize())
               + (null == coreTags ? 0 : coreTags.size())
-              + (null == rootSpanTags ? 0 : rootSpanTags.size())
               + (null == contextualTags ? 0 : contextualTags.size());
 
       if (builderRequestContextDataAppSec != null) {
@@ -2111,6 +2122,7 @@ protected static final DDSpanContext buildSpanContext(
               errorFlag,
               spanType,
               tagsSize,
+              tagBase,
               parentTraceCollector,
               requestContextDataAppSec,
               requestContextDataIast,
@@ -2121,17 +2133,16 @@ protected static final DDSpanContext buildSpanContext(
               tracer.profilingContextIntegration,
               tracer.injectBaggageAsTags);
 
+      // Apply tag intercept for the template tags if needed
+      if (tagBaseNeedsIntercept) {
+        context.interceptAllTags(tagBase);
+      }
       // 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);
       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
-      context.removeTag(Tags.VERSION);
       return context;
     }
   }
@@ -2327,6 +2338,11 @@ protected class ConfigSnapshot extends DynamicConfig.Snapshot {
     final TagMap mergedTracerTags;
     final boolean mergedTracerTagsNeedsIntercept;
 
+    /** Pre-merged template for root spans: mergedTracerTags + localRootSpanTags - Tags.VERSION */
+    final TagMap preMergedRootSpanBase;
+
+    final boolean preMergedRootSpanBaseNeedsIntercept;
+
     protected ConfigSnapshot(
         DynamicConfig<ConfigSnapshot>.Builder builder, ConfigSnapshot oldSnapshot) {
       super(builder, oldSnapshot);
@@ -2351,6 +2367,14 @@ protected ConfigSnapshot(
         mergedTracerTagsNeedsIntercept =
             CoreTracer.this.tagInterceptor.needsIntercept(mergedTracerTags);
       }
+
+      // Pre-merge root span base: mergedTracerTags + localRootSpanTags - Tags.VERSION
+      TagMap rootBase = mergedTracerTags.copy();
+      rootBase.putAll(CoreTracer.this.localRootSpanTags);
+      rootBase.remove(Tags.VERSION);
+      preMergedRootSpanBase = rootBase.freeze();
+      preMergedRootSpanBaseNeedsIntercept =
+          mergedTracerTagsNeedsIntercept || CoreTracer.this.localRootSpanTagsNeedIntercept;
     }
   }
 

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

@@ -288,6 +288,60 @@ public DDSpanContext(
       final PropagationTags propagationTags,
       final ProfilingContextIntegration profilingContextIntegration,
       final boolean injectBaggageAsTags) {
+    this(
+        traceId,
+        spanId,
+        parentId,
+        parentServiceName,
+        serviceNameSource,
+        serviceName,
+        operationName,
+        resourceName,
+        samplingPriority,
+        origin,
+        baggageItems,
+        w3cBaggage,
+        errorFlag,
+        spanType,
+        tagsSize,
+        null, // tagBase
+        traceCollector,
+        requestContextDataAppSec,
+        requestContextDataIast,
+        CiVisibilityContextData,
+        pathwayContext,
+        disableSamplingMechanismValidation,
+        propagationTags,
+        profilingContextIntegration,
+        injectBaggageAsTags);
+  }
+
+  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 TagMap tagBase,
+      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) {
 
     assert traceCollector != null;
     this.traceCollector = traceCollector;
@@ -313,10 +367,14 @@ public DDSpanContext(
     assert pathwayContext != null;
     this.pathwayContext = pathwayContext;
 
-    // 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);
+    if (tagBase != null) {
+      this.unsafeTags = tagBase.copy();
+    } else {
+      // 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);
+    }
 
     // must set this before setting the service and resource names below
     this.profilingContextIntegration = profilingContextIntegration;
@@ -990,6 +1048,26 @@ void setAllTags(final Map<String, ?> map) {
     }
   }
 
+  /**
+   * Runs the tag interceptor over tags already present in unsafeTags (from a template copy). Tags
+   * that are intercepted are removed from unsafeTags and processed by the interceptor. This avoids
+   * re-adding tags that are already present from the template.
+   */
+  void interceptAllTags(final TagMap templateTags) {
+    synchronized (unsafeTags) {
+      templateTags.forEach(
+          this,
+          (ctx, tagEntry) -> {
+            String tag = tagEntry.tag();
+            Object value = tagEntry.objectValue();
+
+            if (ctx.tagInterceptor.interceptTag(ctx, tag, value)) {
+              ctx.unsafeTags.remove(tag);
+            }
+          });
+    }
+  }
+
   void unsafeSetTag(final String tag, final Object value) {
     unsafeTags.set(tag, value);
   }