What

Tag inbound HTTP server spans with _dd.tt.extraction_sources listing the names of request headers and query-string parameters that match a remote-config-driven pattern list. Intended as the agent-side groundwork for the "transaction tracking made easy" workflow on the DSM side.

While the pattern list is empty (default), this feature is inert: a single volatile read + isEmpty() check on the request hot path, no allocations, no tag.

How

• Remote config carrier. New optional field tt_extraction_patterns (List<String>) on the existing APM_TRACING dynamic-config product. Wired through TracingConfigPoller.LibConfig → DynamicConfig → TraceConfig. No new RC product.
• Pattern matcher. New internal-api class TransactionTrackingPatterns. Hand-rolled *-glob (no java.util.regex): segment walker on *-split chunks, lowercased once at compile time, snapshot held in a volatile List<...>. Multiple * per pattern allowed; case-insensitive on the candidate name.
• Hook. HttpServerDecorator.onRequest(...) now calls a new forEachRequestHeaderName(REQUEST, Consumer<String>) extension point (default no-op) when the pattern snapshot is non-empty. Matching header names and matching query-string parameter names are collected and emitted as a CSV under _dd.tt.extraction_sources:
  • Format: header:<lowercased-name> / qs:<lowercased-name>, deduplicated per source bucket, sorted alphabetically within each bucket, headers first then qs (deterministic for log-based aggregation and test assertions).
• Free coverage. Servlet decorators (javax-servlet-3.0 and javax-servlet-2.2) override forEachRequestHeaderName via HttpServletRequest#getHeaderNames(), so Spring WebMVC (3.1 / 5.3 / 6.0) and other servlet-based stacks (Tomcat, Jetty, Undertow when used via servlet) get this transparently. Non-servlet stacks (Netty, Vert.x, WebFlux, …) fall back to the no-op default until per-decorator overrides are added — to be tracked separately.

Pattern syntax is intentionally minimal: * is the only metacharacter (zero-or-more chars). No ?, no character classes.

Why APM_TRACING

Per the design doc, this is the simplest route: zero new wiring on the agent side and zero new product binding on the backend side (the field is additive JSON). Migration to a dedicated APM_TT_* product is a code-only change for the agent and a small overlap window on the backend, deferrable until customer demand for independent targeting materialises.

Tests

• TransactionTrackingPatternsTest (JUnit5, internal-api): literal / *-prefix / *-suffix / *-middle / multi-* / case-insensitivity / no-match / empty.
• TracingConfigPollerTest (JUnit5, dd-trace-core): RC update with the field propagates and clears; absent field leaves config untouched.
• HttpServerDecoratorTtExtractionTest (Spock, agent-bootstrap): mock decorator subclass with canned header names + URL with query string asserts tag presence, exact CSV ordering, source-prefixing, and absence when patterns are empty (fast-path correctness).
• TtExtractionSpringBootTest (Spock, spring-webmvc-5.3): full Spring Boot test app, real request through Tomcat, asserts _dd.tt.extraction_sources on the resulting server span and asserts absence when patterns are empty.

Targeted Gradle commands (all green locally — see commits for the exact list):

:internal-api:test --tests TransactionTrackingPatternsTest
:dd-trace-core:test --tests TracingConfigPollerTest
:dd-java-agent:agent-bootstrap:test
:dd-java-agent:instrumentation:servlet:javax-servlet:javax-servlet-3.0:test
:dd-java-agent:instrumentation:servlet:javax-servlet:javax-servlet-2.2:test
:dd-java-agent:instrumentation:spring:spring-webmvc:spring-webmvc-5.3:test --tests test.tt.TtExtractionSpringBootTest

Rollout / kill switch

No agent-side feature flag. The feature is inert until the backend pushes a non-empty tt_extraction_patterns. Backend can target by org / service / env / canary; pushing an empty list at any time disables the feature on the next snapshot.

Plan deviations from the design doc

(Surfaced for reviewer awareness; documented in detail in the implementation report.)

1. The APM_TRACING DTO uses Moshi, not Jackson; I followed the existing pattern (@Json(name = "tt_extraction_patterns")).
2. There is no jakarta-servlet-5.0 server decorator in this repo — jakarta server flavours live in per-container modules (Tomcat-10, Jetty-11+, Liberty-23, …) and each uses container-specific request types. Out of scope for this PR; falls back to the no-op default. Tracked as a follow-up.
3. InstrumentationTags actually lives in internal-api, not agent-bootstrap; the new constant lives in the real file.
4. Skipped a ConfigDefaults constant — there is no env-var / system-property fallback in v1 (deferred to v2), so the constant would be dead code.
5. Skipped the JMH micro-benchmark — internal-api has no jmh source set. Empty-pattern fast-path correctness is exercised by the negative tests at every layer.
6. Skipped the defensive 32-name cap / catch-all WARN from the design doc's Risks section — those were "future hardening" suggestions, not part of v1.

Span tag spec

Set only when at least one match is found. Absent otherwise.