Add TagMap read-through support - trace / span tag split mechanism (phase 1a)

[dougqh]

What Does This Do

Adds read-through support to TagMap - currently unused

A TagMap can now be constructed via createFromParent(TagMap) to resolve map queries against a frozen parent TagMap. The plan is to use this to separate trace-level tags from span-level tags without any semantic changes.

Motivation

When applied to the tracer core will enable lighter and faster span construction by removing some map-to-map copying.

Additional Notes

From Claude...

Pure mechanism — inert until a consumer attaches a parent. No map has a parent yet (parent == null for every existing map), so there is no behavior change off the read-through path. The consumer wiring lands in a stacked follow-up.

A child TagMap references a frozen parent (createFromParent) and reads through to it on a local miss, while local entries shadow the parent. This is the enabler for level-split phase 1 — a span will stop copying the shared trace-level tags (mergedTracerTags) down into every span; reads route through instead.

Design

• Single parent by design: the consumer needs one parent (mergedTracerTags). Written so generalizing to multiple flattened parents is additive (the bulk walk is already bucket-aligned, the degenerate single-parent case of the multi-parent merge).
• Removal via a lazy removedFromParent side-set, not inline tombstones. Inline-in-buckets kept breaking on the bare-Entry-vs-BucketGroup duality (re-type, per-group bitfield + single-Entry gap, two bitfields — all awkward). The side-set is shape-agnostic, keeps Entry/BucketGroupcompletely untouched, and the lazy null field doubles as the gate. Tombstones are rare (only when a parent-exposed key is removed).
• Bulk reads via a bucket-aligned merge: exploits universal hashing (fixed-size 16-bucket table, no resize) so a parent entry's shadow check is scoped to the same-index local bucket, reusing the entry's cached hash — no re-hash, no global seen-set, no Set/BloomFilter. forEach (×3) stays alloc-free; IteratorBase does a two-phase local-then-parent walk so iterator/entrySet/keySet/values/stream all emit the deduped union.

What's covered

• Read path: getEntry fall-through (the whole get*/containsKey family inherits it). isDefinitelyEmpty() + estimateSize() added as cheap conservative/upper-bound variants (mirroring Ledger); isEmpty()/size() stay exact (Map contract) and resolve the union.
• Removal: tombstone a parent-exposed key; re-setting clears it; remove() returns the prior visible value (Map contract holds via read-through).
• Bulk: forEach/iterators/collection views all emit the deduped, first-occurrence-wins union, skipping shadowed/tombstoned parent entries.
• copy() preserves read-through (shares the frozen parent + copies tombstones) — was dropping both.
• Behavior-identical-to-flat-map tests are the safety contract for the consumer flip.

TagMapReadThroughTest covers the read path, removal/tombstoning, the deduped bulk union, and copy() preservation; the full TagMap* suite stays green (inert when parent == null).

Deferred / follow-ups

• Inlining baseline for get/set across the parent != null branch — the perf-gate before marking this ready.
• Consumer PR (stacked): the !needsIntercept-gated mergedTracerTags → createFromParent wiring. Includes the removeTag(VERSION) cleanup — config version moves out of the read-through bundle so the existing InternalTagsAdder conditional-add works unchanged and no per-span tombstone is minted (the apply-then-remove dance is vestigial; read-through keeps config-in-parent / manual-in-local). Plus an audit of any other per-span parent-key removals and of read-through maps as a merge/clone source (only copy() handled here).
• Multi-parent + the cross-parent dedup clause — additive, with the dream.

---

tag: ai generated · pure mechanism, no behavior change until a consumer attaches a parent.

🤖 Generated with Claude Code

[dd-octo-sts]

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite	Status
Startup	🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Scenario	Candidate	master	Δ (95% CI of mean)
startup:insecure-bank:iast:Agent	14.79 s	14.65 s	[+0.2%; +1.7%] (maybe worse)
startup:insecure-bank:tracing:Agent	13.61 s	13.61 s	[-0.9%; +0.9%] (no difference)
startup:petclinic:appsec:Agent	16.83 s	17.36 s	[-7.5%; +1.4%] (no difference)
startup:petclinic:iast:Agent	17.41 s	17.00 s	[-2.1%; +7.0%] (no difference)
startup:petclinic:profiling:Agent	17.34 s	17.32 s	[-0.9%; +1.1%] (no difference)
startup:petclinic:sca:Agent	17.37 s	17.33 s	[-0.7%; +1.2%] (no difference)
startup:petclinic:tracing:Agent	16.55 s	16.65 s	[-1.7%; +0.5%] (no difference)

Commit:706437d0 · CI Pipeline · Benchmarking Platform UI

---

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.

[dougqh]

Inlining gate — off-path (parent == null) reads: parity confirmed

Ran -XX:+UnlockDiagnosticVMOptions -XX:+PrintInlining (no-fork, -f0) on UnsynchronizedMapBenchmark.get_tagMap / iterate_tagMap_forEach, master vs this branch, to verify the getEntry refactor + forEach parent loop don't regress hot-read inlining for the common parent == null case (every existing map).

Reads — parity, both fully inline hot:

	getEntry	decision
master	monolith, 90 B	inline (hot)
branch	getEntry 51 B → getLocalEntry 24 B → findInBucket 45 B	all inline (hot)

Same fully-inlined read — the branch inlines a 120 B chain of tiny methods where master inlines a 90 B monolith (+30 B for the parent != null check + framing, all far under FreqInlineSize 325). Cold-site "callee is too large" is identical on both (> the 35 B cold cutoff). So the split is inlining-neutral.

forEach: the read-through parent loop was extracted to per-variant forEachParent(...) (called only when parent != null), so off-path forEach is back to ~90 B (it had grown to 242 B inline) and compiles as its own loop unit exactly as before; the parent-loop code is out of line and dead when parent == null.

Writes: descoped — setTag → TagInterceptor → getAndSet is already a non-inlinable big method due to the interceptor cascade, so a write-side inlining measurement is confounded. The one gated removedFromParent != null field-check is noise against that; meaningful write-path inlining waits on interceptor retirement.

Not yet measured: the with-parent hot path (read-through active) — there's no benchmark with a parent attached yet. That belongs on the consumer PR's span-level -prof gc benchmark, which also demonstrates the per-span allocation win.

[dougqh]

Measured read-through win (quiet box, firmed)

TagMapReadThroughBenchmark (on the stacked consumer branch, where the wiring lands) models span-build tag assembly — copyDown (today: putAll the frozen trace-level bundle + span tags) vs readThrough (attach the bundle as a read-through parent, span tags local) — swept by trace-bundle size. 5 forks, @Threads(8), -prof gc, 25 measurements/point.

traceTagCount	copyDown alloc	readThrough alloc	saved	copyDown thrpt	readThrough thrpt	speedup
3	360 B/op	312 B/op	−13%	170.8M ops/s	213.7M	1.25×
7 (realistic)	456 B/op	312 B/op	−32%	133.0M ops/s	215.0M	1.62×
15	600 B/op	312 B/op	−48%	101.1M ops/s	207.3M	2.05×

The headline is the shape, not a single number:

• read-through is invariant to bundle size — 312 B/op and ~210M ops/s flat across 3/7/15 trace tags. A span no longer pays anything for the trace-level bundle; its cost is O(its own tags).
• copyDown grows with the bundle (more BucketGroup clones + collisions to copy), so the win scales with mergedTracerTags size: −13%/1.25× at 3 tags → −48%/2.05× at 15.

Reliability: alloc deterministic (±0.001 over 25 samples); throughput tight (±2–5M).

Honest attribution / scope: the alloc delta is bucket structure (BucketGroup clones + fewer local collisions), notEntry objects — putAll-into-empty already shares the frozen entries. Bucket structures are ~3% of tracer alloc, so absolute macro impact at roomy heap is modest; the win matters most under GC pressure and on the app/request thread (the throughput column). The structural point is the invariance — read-through decouples per-span cost from trace-bundle size, which is the level-split thesis (trace tags paid once, not per span).

[dd-octo-sts]

Hi! 👋 Thanks for your pull request! 🎉

To help us review it, please make sure to:

• Remove the issue linking keyword

If you need help, please check our contributing guidelines.

[datadog-datadog-prod-us1-2]

More details

This PR adds read-through support to TagMap, enabling span-level maps to read through a frozen parent (trace-level) map on local misses. The mechanism is inert when no parent is attached (parent == null), ensuring no behavioral change for existing code. Comprehensive testing verifies read-through correctness, tombstone handling, iterator deduplication, and equivalence to flat-map semantics. No production bugs detected.

Was this helpful? React 👍 or 👎

_{Open Bits AI session}

_{🤖 Datadog Autotest · Commit 50cf53d · What is Autotest? · Any feedback? Reach out in #autotest}

[dougqh]

Span-creation allocation benchmark — do-no-harm gate

This PR adds the read-through mechanism to TagMap but doesn't wire it into the span-creation path, so the bar here is no regression on the existing (parentless) paths. Ran SpanCreationBenchmark before/after, isolated to just this PR's 3 commits on one lineage (before = parent of the first commit, after = PR head — not the stale merge-base).

gc.alloc.rate.norm (B/op) — primary signal

Arm	before	after	Δ B/op	Δ%
bareStartSpan	904.0 ±0.0	897.1 ±12.5	−6.9	−0.8%
bareBuildSpan	924.3 ±47.9	930.7 ±49.2	+6.4	+0.7%
jdbcClientSpan	1290.7 ±29.2	1298.7 ±29.2	+8.0	+0.6%
webServerSpan	1586.7 ±41.7	1618.7 ±41.7	+32.0	+2.0%
webServerSpanViaBuilder	1688.0 ±12.5	1730.7 ±41.7	+42.7	+2.5%

Verdict: flat within noise — do-no-harm pass. Every delta sits inside overlapping confidence intervals; none is a statistically defensible regression.

Two reasons it reads as variance, not a real cost:

• Not systematic. A real cost would come from TagMap gaining ~2 ref fields (~16 B/op) and would show on every TagMap-allocating arm. Instead the bare arms are flat (one dropped), and the tagged deltas don't scale with tag count (jdbc sets more tags than web but moved less: +8 vs +32).
• Wide error bars = per-fork inlining bimodality — what @Fork(3) exists to expose (bareBuild is ±48 on both sides; viaBuilder's error swung 12→42 between runs). The point estimates ride fork-to-fork JIT variance.

Throughput (directional only, laptop): mostly up on the after side (+1.6%…+6.5%), one arm down — no regression signal.

Methodology

SpanCreationBenchmark trimmed to the drift-stable arms (no SpanPrototype, which doesn't exist at these commits). @Threads(8) @Fork(3) @Warmup(5) @Measurement(5), -prof gc, finished against a no-op DropWriter so only front-half (create/tag/finish) allocation is measured. Read gc.alloc.rate.norm (deterministic) as the signal; throughput is thermal/bimodality-fragile.

[dd-octo-sts]

/merge

[gh-worker-devflow-routing-ef8351]

View all feedbacks in Devflow UI.

2026-08-17 19:10:48 UTC ℹ️ Start processing command /merge

---

2026-08-17 19:10:52 UTC ℹ️ MergeQueue: pull request added to the queue

The expected merge time in master is approximately 2h (p90).

---

2026-08-17 20:22:14 UTC ℹ️ MergeQueue: This merge request was merged