What Does This Do

Adds a JMH benchmark harness comparing the three UTF-8-encoding cache strategies available for tag-value encoding in trace serialization: the general-purpose DDCache, and the purpose-built SimpleUtf8Cache / GenerationalUtf8Cache.

• Utf8CacheSizeBenchmark (new): sweeps cache capacity (10 / 100 / 1000) across NOCACHE / DDCACHE / SIMPLE / GENERATIONAL against the same synthetic tag/value workload, run with -prof gc to capture allocation alongside throughput.
• Utf8Benchmark / Utf8ConcurrentBenchmark: added a DDCache arm alongside the existing Simple/Generational arms, plus doc comments clarifying the single-threaded-recalibrate contract these benchmarks assume (matches how the caches are actually driven in the writer today).

No production code changes — benchmark-only.

Motivation

We have three different caching implementations doing effectively the same job (string → UTF-8 bytes) with no head-to-head data on how they compare across capacities, or against not caching at all. This gives us that data so future decisions about which cache to use/keep can be evidence-based rather than assumed.

Results (capacity sweep, -prof gc, normalized)

Throughput in ops/s, allocation in bytes/op, GC rate normalized to counts/sec (raw gc.count/gc.time are cumulative sums over the run and aren't comparable across different fork/iteration counts without this normalization).

GC/s and GC time % are gc.count/gc.time normalized by total measurement time (NOCACHE: 1 fork × 5 × 10s = 50s; the three caches: 5 forks × 5 × 10s = 250s) — the raw JMH sums aren't comparable across runs with different fork counts without this.

Key findings

• All three caches lose on raw throughput to the uncached baseline at every capacity tested. String.getBytes(UTF_8) is intrinsified, so a cache lookup is strictly more expensive per-op than just re-encoding — these caches only pay off on allocation, not throughput. This confirms the "bump-pointer bar": any cache meant to reduce app-thread allocation has to beat a TLAB bump-pointer allocation, which is a very cheap operation to beat.
• Allocation reduction is real but smaller than naively expected — at capacity 1000 all three caches reduce allocation by only ~17-23%, not the ~90% you'd guess from hit rate alone. Root cause: the synthetic workload builds each value via tag + int string concatenation on every lookup (Utf8Workload.nextStandardValue/nextCustomValue), which allocates a fresh String regardless of whether the subsequent UTF-8 encoding is cached. For ASCII-compact strings, getBytes(UTF_8) is itself just a copy of the existing byte array, so a cache hit only saves that one array copy — not the string-construction cost. This structurally caps the max possible allocation win for any UTF8 cache on this workload.
• DDCache has a small but consistent allocation disadvantage vs. Simple/Generational, from its generic Pair.of(key, value) wrapper allocated on every stored miss (FixedSizeCache.produceAndStoreValue). Simple/Generational avoid this on one-off values via a marker/bloom-style gate (Caching.mark) that defers the wrapper allocation (CacheEntry) to a value's second observed touch — same immutable-wrapper-for-lock-freedom pattern as DDCache, but with the wrapper cost paid only for values that actually recur. The marker itself is advisory rather than authoritative: a wrong mark only costs a redundant allocation on the next touch, it can never cause the cache to return incorrect data, which is what keeps the design simple to reason about.
• DDCache's disadvantage at very small capacity (10) is smaller than expected, since at that capacity all caches thrash heavily regardless of strategy.
• Simple and Generational are close to equal at capacity 100, with Generational pulling ahead at capacity 1000 — worth a follow-up look at what capacity the caches actually run at in production before considering whether Simple's extra complexity over Generational is still earning its keep.

Additional Notes

Opened as a standalone side task, decoupled from #12474 (the @ForegroundSafe/@BackgroundOnly annotation-checker PR).

Contributor Checklist

• Format the title according to the contribution guidelines
• Assign the type: and (comp: or inst:) labels in addition to any other useful labels
• Avoid using close, fix, or any linking keywords when referencing an issue
• Update the CODEOWNERS file on source file addition, migration, or deletion (n/a — no new module/package)
• Update public documentation with any new configuration flags or behaviors (n/a — benchmark-only, no config/behavior change)
• Once approved, use merge queue to merge the PR

Test plan

• Ran Utf8CacheSizeBenchmark locally (./gradlew :dd-trace-core:jmh -Pjmh.include=Utf8CacheSizeBenchmark -Pjmh.profilers=gc) across all capacity/kind combinations plus a NOCACHE-only baseline run.
• Benchmark-only change; no functional code touched, so no other automated test coverage applies.

🤖 Generated with Claude Code