Set known tags by id on TagMap and spans (otlp - tag registry - phase 2)

[dougqh]

What Does This Do

Adds setting a known tag by its id to TagMap and the span API, on top of the tag registry from #12354 (stacked on it; the diff here is only this PR).

• TagMap.set(long tagId, value) for Object, CharSequence, and the primitives. The entry is built under the tag's canonical name from KnownTagCodec.nameOf, skipping the canonicalizing name lookup the String setters pay on every new entry. An id that names no known tag is rejected.
• TagMap.Entry.create(long tagId, value), the public way to build an entry ahead of time (as decorators do for cached entries), at the same layer as AgentSpan.setTag. It has the same contract as the name-keyed create: a null or empty value yields no entry.
• AgentSpan.setTag(long tagId, value), as default methods that resolve the id to its name and delegate to the String setter, so every AgentSpan implementation stays correct with no changes.
• DDSpan / DDSpanContext overrides with the same behavior as the String family: TagInterceptor still runs on the tag's name (it is name-keyed), primitives still box only when the tag might be intercepted, and the http.status_code quirk is kept. The difference is that a stored tag is set by id.
• TagMap hashes entries by tag id. TagMap.Entry holds a 64-bit tag hash, computed once at construction: a known tag's id, or a custom tag's name hash in the low 32 bits. An id's serial sits in bits 63-48, so the two can never collide.
  • tagId() becomes a field read instead of a keyOf lookup.
  • Name lookups (getEntry, getAndRemove) take one keyOf, instead of canonicalizing and then hashing the name separately.
  • Buckets fold the hash from bit 48, so known tags spread by serial. A custom tag's bucket hash is unchanged.
  • BucketGroup keeps its int hashes, so only Entry grows: int to long costs 8 bytes per entry because of alignment. That is an accepted temporary cost until the dense store.
• First caller: BaseDecorator.onPeerConnection / setPeerPort, which run on every client span, now set peer.hostname, peer.ipv4/ipv6 and peer.port by KnownTags id.

Motivation

Under the OTLP <-> Datadog mapping, an ID identifies one tag exactly, where a name may not. #12713 is making the tag registry direction-aware, and there peer.port becomes two tags (the server's port on outbound spans, the client's on inbound ones) that share a Datadog name. Writers then need to set the specific tag, which is what an id expresses. This PR provides that API, independent of the direction work:

            ┌──► #12713  (registry: span directions)  ──┐
#12354 ─────┤                                           ├──► next: writers resolve to ids by direction
            └──► this PR (set tags by id)  ─────────────┘

It follows the API shape of #11901, but implemented on the current TagMap rather than the dense store, which #11901 is stacked on. The dense store can later swap the implementation behind the same signatures.

Additional Notes

• Not in this PR: Ledger/builder support, which will arrive with a caller. Id-keyed TagMap.getEntry(long) / getAndRemove(long) are included, so clearing a tag by id removes it by id rather than round-tripping through its name.
• Map contract unchanged, deliberately: Entry.hashCode() still returns the bucket hash rather than key.hashCode() ^ value.hashCode(), and TagMap still compares by identity. Both were already the case before this PR; changing them is a separate behavior change.
• Shared names after Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713: an entry set by a per-direction id (for example PEER_PORT_OUTBOUND_ID) hashes by that id, so on this PR alone a lookup by the shared name "peer.port" will not find it. Phase 3 (Resolve direction-dependent tag names by the span's kind (otlp - tag registry - phase 3) #12731) handles both sides: spans resolve the name by their direction, and a TagMap lookup by the shared name probes its per-direction ids.
• Merge order with Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713: once Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713 splits peer.port, KnownTags.PEER_PORT_ID no longer exists, so BaseDecorator.setPeerPort stops compiling until it picks a direction. That is intended: it forces the direction to be chosen explicitly.
• Open for reviewers — how much of the decorator change to keep:
  1. All of it (as is): a real hot caller for the id API, but it couples this PR to Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713 through PEER_PORT_ID.
  2. Drop only setPeerPort: peer.hostname/ipv4/ipv6 keep the same ids in Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713, so onPeerConnection stays a real caller with no coupling. peer.port, which server decorators also set for the client's port, moves to the direction-aware follow-up.
  3. Drop the decorator change entirely: this PR becomes purely core, but has no production caller yet.
• Behavior coupling with Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713 (affects option 1): once Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713 splits peer.port into a tag per direction, a tag stored under a per-direction id hashes by that id, but the shared name "peer.port" resolves to no id, so a lookup by name misses it. If setPeerPort switched to PEER_PORT_OUTBOUND_ID, a later getTag("peer.port") would come back empty. Until direction-aware reads land, setPeerPort therefore has to keep setting peer.port by name, which stores it as a custom tag that name lookups still find. So whichever of the two PRs merges second keeps setPeerPort name-keyed; onPeerConnection's peer.hostname/ipv4/ipv6 keep the same ids in Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713 and are unaffected.
• Spock tests that mock AgentSpan would see the id-keyed call directly, since a mock intercepts the default method, so every call site moved to ids would break its test's expectations. Instead, the decorator specs now mock NameKeyedAgentSpan, a test-only AgentSpan whose id-keyed overloads are final and delegate to the name-keyed ones. A mock can't override a final method, so it only sees setTag(name, value). BaseDecoratorTest.mockSpan() creates one. The specs' expectations are unchanged from master, and moving further call sites to ids needs no test change. (Spock only allows Mock() inside a spec class, so the factory lives on the base spec rather than in a trait. Other modules' 50-odd Mock(AgentSpan) sites can adopt it as they migrate.)
• Tags.PEER_PORT and friends stay as they are; a @Deprecated pointing at the ids comes once callers have migrated.

Contributor Checklist

• :internal-api:test (TagMap* incl. TagMapFuzzTest, 384 tests; KnownTags*; new TagMapSetByIdTest, TagMapTagHashTest, TagMapEntryCreateByIdTest), :internal-api:spotlessCheck

• :dd-trace-core:test (DDSpan* incl. new DDSpanSetTagByIdTest, *taginterceptor*, *otlp*, common.writer.*, common.metrics.*; 1279 tests), :dd-trace-core:spotlessCheck. DDAgentWriterCombinedTest.unixSocketTimeoutKeepsWorkerAliveAndReconnects failed once and passed on rerun here and on the base branch; it's a timing test.

• New TagMapInsertBenchmark, before vs. after hashing entries by tag id. MacBook, JDK 21, default flags, @Fork(2) triage; 12 tags per op:

  Benchmark	before ns/op	after ns/op	change	B/op
  knownByName	130.9 ± 1.8	121.1 ± 3.8	−7.5%	688 → 736
  knownById	100.7 ± 5.5	94.7 ± 1.7	−5.9%	688 → 736
  customByName	82.2 ± 2.7	80.6 ± 2.4	−1.9% (noise)	640 → 736

  The first run caught a regression: knownById was +17%, because the id constructor resolved the name twice. That is fixed in 62f1026. Known tags net only +48 B because spreading them by serial removed a bucket collision.

• :dd-java-agent:agent-bootstrap:test (*Decorator*, 413 tests), :dd-java-agent:agent-bootstrap:spotlessCheck

Jira ticket

N/A

🤖 Generated with Claude Code

[dougqh]

These are included because eventually we'll need to use ID to disambiguate some of these concepts for OTLP, and I wanted to illustrate usage.

That said, I'm happy to leave these to another PR if others prefer.

[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.74 s	14.57 s	[+0.4%; +2.0%] (maybe worse)
startup:insecure-bank:tracing:Agent	13.54 s	13.67 s	[-1.9%; -0.1%] (maybe better)
startup:petclinic:appsec:Agent	17.16 s	17.05 s	[-0.1%; +1.2%] (no difference)
startup:petclinic:iast:Agent	17.02 s	16.99 s	[-0.5%; +0.7%] (no difference)
startup:petclinic:profiling:Agent	16.77 s	16.57 s	[+0.2%; +2.2%] (maybe worse)
startup:petclinic:sca:Agent	17.06 s	17.10 s	[-0.9%; +0.5%] (no difference)
startup:petclinic:tracing:Agent	16.05 s	15.73 s	[-2.4%; +6.4%] (no difference)

Commit: 2d87cde8 · 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

Here are some automated review suggestions for this pull request.

Reviewed commit: f38b1f88fe

ℹ️ 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-official]

The new hash fold maps _dd.djm.enabled to the reserved zero sentinel, allowing bucket collisions to lose the tag or cause lookup failures.

_{Open Bits AI session}

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

[datadog-official]

Clearing an unknown tag id with a null or empty String throws instead of following the other overloads’ no-op behavior. The alias-splitting candidate was excluded because it already exists at the supplied base commit.

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit 55ab351 · @DataDog review to ask questions}

[datadog-official]

Alias-based service splitting breaks for builder and default tags: db.system becomes db.type before interception, so a split-by-tags=db.system rule no longer matches.

_{Open Bits AI session}

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

[datadog-official]

Preserve alias-based split-service rules for builder tags

With dd.trace.split-by-tags=db.system, a span built with withTag("db.system", "postgresql") should use postgresql as its service name. Entry construction instead canonicalizes the key to db.type before interception, while splitServiceTags still contains the literal db.system, so service splitting silently stops working. Default-tag maps have the same mismatch; setting the tag after creation still works because interception precedes canonicalization. Normalize configured split-service keys and interception inputs consistently across these paths.

Was this helpful? React 👍 or 👎
_{🤖 Bits Code Review · @DataDog review to ask questions · Open Bits AI session}