Add TagContributor / TagExtractor span-tag APIs (otlp - phase 4 & span api)

[dougqh]

What Does This Do

Adds two span-tag APIs and a benchmark that justifies them. This is the API contract only (draft).

The APIs:

• TagContributor (intrinsic): a typed POJO we own projects its own state onto a span via addTo(AgentSpan). DBInfo, git metadata and ExtractedContext are the precedents.
• TagExtractor<T> (extrinsic, @FunctionalInterface): extracts tags from a foreign object we don't own (InetSocketAddress, Request) onto a span. It's a @Strategy preferably an inline non-capturing or a single instance held in a static final field.
• AgentSpan.setTagsFrom(...): the span-first, product-facing forms, span.setTagsFrom(connection, EXTRACTOR) for an extractor and span.setTagsFrom(dbInfo) for a contributor. Named setTagsFrom rather than setTags because the source isn't itself a tag value: setTag(name, value) stores one value, while these derive any number of tags from the source. The extra indirection inlines away at a monomorphic site; it's also the seam an implementer can override to coarse-lock the whole extraction.
• TagProjectionBenchmark: compares decorator, extractor and contributor dispatch.

Motivation

This is the foundation for incrementally dissolving the span decorators, a deep virtual hierarchy (BaseDecorator → {Client,Server}Decorator → {Http,Database,…}* → ~149 concrete), into composable, JIT-friendly tag projection.

It establishes a style we know compiles well (call-time binding, one dispatch, a small consumer) ahead of setTag itself inlining well. Today setTag goes through DDSpan, DDSpanContext, TagInterceptor's name switch and TagMap's lookup, which limits the end-to-end gain. That's why the benchmark uses a lightweight sink: it isolates dispatch rather than letting setTag's cost swamp it. The payoff compounds as the write path gets cheaper: id-keyed setters, id-keyed interception, the dense store.

The template-method decorator makes one dynamic dispatch per hook; an extractor or contributor makes one in total. Benchmark (@Threads(8) @Fork(3), throughput, -prof gc):

arm	mono	mega
decorator	1525M	426M (−72%)
extractor	1256M	914M (−27%)
contributor	1655M	1026M (−38%)

• mono (one type): everything inlines, so it's roughly a tie. The abstraction is free at the decorator's best case.
• mega (8 equivalent loaded types, megamorphic): the decorator collapses; the extractor and contributor degrade far less. Zero allocation in all arms (pure dispatch).
• -XX:+PrintInlining confirms the mechanism: decorator-mega leaves all 4 template calls as virtual call (megamorphic, not inlined); extractor-mega is one virtual call plus an inlined body.
• These numbers were taken with @Threads(8), which adds noise to a benchmark that allocates nothing: the three mono arms should nearly tie but spread about 30%. So the extractor and contributor aren't ranked against each other here; only the decorator's mega drop clearly stands out.

What the benchmark supports is a robust floor: fewer dynamic dispatches (N→1), which holds on the interpreter, C1 and the cold path with no JIT needed. That's what the mega arm shows, and it models the failure mode where the binding isn't visible to the JIT. When it is visible, both shapes can compile to straight-line code: an extractor bound as a static final through the tiny setTagsFrom devirtualizes on its exact type once setTagsFrom inlines, and a decorator's template calls devirtualize the same way if its larger template method inlines (see Strategy). The extractor's practical edge there is that its consumer is small enough to inline reliably.

The arms read receivers from arrays at a private call site, so they measure profile-driven dispatch rather than the shape that ships (a static final constant through a shared, inlined consumer). The mono-vs-mega ratios are illustrative, not a prediction of production gains.

Additional Notes

• Both interfaces target AgentSpan for now, so they can also drive span-level state (resource name, error, status) during the transition. The sink narrows toward TagMap as those fields migrate into the tag model.
• Convention for extractors: extractors are promoted to named singleton classes (XExtractor implements TagExtractor<T> with a private-constructor INSTANCE) rather than inline lambdas. That gives a name at the call site, a home for pure statics and caches (class statics, not lambda captures, so it stays non-capturing), and the composability the inheritance chain lacked. The one rubric line: no capturing lambdas (they allocate per call and break memoization in any lazy variant).
• /techdebt is deferred until the PR is ready for review.

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
  Use solves instead, and assign the PR milestone to the issue
• Update the CODEOWNERS file on source file addition, migration, or deletion
• Update public documentation with any new configuration flags or behaviors
• Once approved, use merge queue to merge the PR

Jira ticket: N/A

🤖 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.89 s	14.72 s	[+0.2%; +2.2%] (maybe worse)
startup:insecure-bank:tracing:Agent	13.75 s	13.78 s	[-1.1%; +0.7%] (no difference)
startup:petclinic:appsec:Agent	17.16 s	17.04 s	[-0.1%; +1.5%] (no difference)
startup:petclinic:iast:Agent	16.45 s	17.00 s	[-7.3%; +0.8%] (no difference)
startup:petclinic:profiling:Agent	16.57 s	16.87 s	[-3.0%; -0.4%] (maybe better)
startup:petclinic:sca:Agent	16.63 s	17.00 s	[-6.2%; +2.0%] (no difference)
startup:petclinic:tracing:Agent	16.16 s	16.21 s	[-1.2%; +0.6%] (no difference)

Commit: 6956c7dd · 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.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-06T13:58:53.994355Z	8af312e	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8af312ebf1

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[datadog-datadog-prod-us1]

More details

Immutable spans still discard projected tag writes. Callback execution matches the new methods’ documented delegation behavior, so the reviewer’s no-op callback concern does not establish a correctness regression.

Was this helpful? React 👍 or 👎

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit 8af312e · @DataDog review to ask questions}

[mcculls]

LGTM