Introduce SpanPrototype: baked-once constant span-tag descriptor

[dougqh]

Draft — increment 1 of a multi-step change. Abstraction + bake only, purely additive. Opening early for design review of the shape before the core-path wiring.

What this is

SpanPrototype is a baked-once, frozen descriptor of a span's constant initial tags — the per-decorator constants (component / span.kind / language / analytics rate) that BaseDecorator.afterStart otherwise stamps one entry at a time, per span.

The goal (across increments) is to move that constant stamping to span construction as a single seeded copy, so afterStart's N setTag calls collapse. It's the biggest per-span structural CPU lever in the decorator layer, and it doubles as a pit of success: writing buildPrototype(tags) is the same tags.set(key, value) you'd write on the span, except it runs once — the cheap-to-write path becomes the cheap-to-run path.

Increment 1 (this PR) — abstraction + bake, additive

• SpanPrototype (internal-api): a frozen TagMap holder (of / tags / NONE). Rides the existing TagMap API, so it's independent of the deeper TagMap/dense-store rework — the internal seed can get faster later without changing this surface.
• BaseDecorator.prototype(): baked once, lazily cached (same static-init caution as componentEntry()).
• buildPrototype(TagMap) contribute-chain: mirrors the afterStart super-chain (Base = component + analytics; Server = + span.kind + language; Client = + span.kind), but runs once at bake rather than per span. This is where the type/integration layering happens.
• Purely additive: afterStart is byte-for-byte unchanged and prototype() is not yet wired into span creation. Zero behavior change.
• SpanPrototypeTest (JUnit 5) verifies the composition (server prototype carries component + span.kind=server + language; client carries component + span.kind=client; baked once).

Planned next increments (for review context — NOT in this PR)

2. Wire into construction, API-first. Public startSpan(SpanPrototype, …) / buildSpan(SpanPrototype, …) (additive overloads; existing signatures delegate with SpanPrototype.NONE, so no call-site sweep). Internally the prototype threads through the builder exactly like tagLedger and is applied at buildSpanContext right after defaultSpanTags via setAllTags — layered under per-span withTags. afterStart's constant stamping is gated off (decorator-owned startSpan skips it) for migrated integrations; NONE keeps everyone else on today's path. One server integration migrated + micro-measured.
3. Optional deepening (pure internal, same API): setAllTags(putAll) → construction copy() for the true clone-at-birth copy-down; add constant span fields (spanType, integration name) to the prototype so afterStart fully collapses.

Design notes

• Constants-only, no speculative slots. Derivation / canonicalization / lifecycle hooks are deliberately out — the concept earns its extensibility by being simple and well-placed, to be grown when the work that needs each facet arrives.
• Independent of the extractor stack (Add TagContributor / TagExtractor span-tag APIs #11817–Peel dbUser out of DatabaseClientDecorator into a param-injected TagExtractor #11823) and the dense store; composes with both, gated on neither.

🤖 Generated with Claude Code

[dougqh]

I'm debating the shape of the SpanPrototype API.
I think what I want is a builder like API which has the notion of extension.

So something like...
SpanPrototype.builder().
extends_(baseProto).
initKind(...).
initTag(key, value).
initTag(entry).
build();

As much as possible, I don't want instrumentation devs to see TagMap or TagMap.Entry directly.

[datadog-datadog-prod-us1]

🎯 Code Coverage (details)
• Patch Coverage: 24.56%
• Overall Coverage: 54.94% (-2.02%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 54b4386 | Docs | Datadog PR Page | Give us feedback!}

[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.84 s	14.56 s	[+0.9%; +2.9%] (maybe worse)
startup:insecure-bank:tracing:Agent	13.59 s	13.71 s	[-1.8%; -0.0%] (maybe better)
startup:petclinic:appsec:Agent	17.50 s	17.26 s	[+0.4%; +2.4%] (maybe worse)
startup:petclinic:iast:Agent	16.64 s	17.40 s	[-8.5%; -0.2%] (maybe better)
startup:petclinic:profiling:Agent	17.33 s	17.39 s	[-1.5%; +0.8%] (no difference)
startup:petclinic:sca:Agent	17.44 s	17.33 s	[-0.3%; +1.6%] (no difference)
startup:petclinic:tracing:Agent	16.16 s	16.66 s	[-7.5%; +1.5%] (no difference)

Commit: 54b43863 · 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.