Resolve direction-dependent tag names by the span's kind (otlp - tag registry - phase 3)

[dougqh]

What Does This Do

Phase 3 of the tag registry work: span directions at runtime. It is stacked on #12713 (registry directions) and #12715 (set known tags by id), and merges both. The base is #12713's branch, so until #12715 merges, its commits also show in this diff.

phase 1              phase 2                              phase 3
            ┌──► #12713 (registry directions) ──┐
#12354 ─────┤                                   ├──► this PR: resolve names by the span's direction
            └──► #12715 (set tags by id) ───────┘

#12713 taught the registry that a few names mean different tags depending on the span's direction: peer.port is the client's port on a server span and the server's on a client span, and server.address is http.hostname inbound but peer.hostname outbound. This PR makes the runtime use that.

KnownTagCodec: lookups that take a direction

• keyOf(name, direction) and openTelemetryTagOf(id, direction), with descriptive int constants: DIRECTION_INBOUND (server, consumer), DIRECTION_OUTBOUND (client, producer), DIRECTION_NONE (internal), DIRECTION_UNKNOWN.
• directionalKeyOf(name, direction): only the direction-dependent part. It's a switch over just those names, so a miss is far cheaper than a full lookup.
• keyOf(name) is unchanged. Every name still costs one table lookup. The table marks the direction-dependent names SHARED_NAME (peer.port) or DIRECTION_SCOPED_NAME (server.address), and only those take a second step.
• The generated resolver is now pure data: nameOf, openTelemetryNameOf(id, direction), lookup, directionalKeyOf. The codec owns the policy.

TagMap: reading a shared name finds whichever tag the map holds

• A span holds only one of a shared name's tags, so get("peer.port"), containsKey, remove and read-through to a parent map probe each per-direction id. Only shared names take the probe; custom tags and direction-free names take exactly the path they took before. This keeps the Map contract for name-keyed readers, including getTags() copies.
• getEntry(long) / getAndRemove(long) find exactly one tag.
• A bucket holding a single entry now compares the hash as well as the name, as BucketGroup already did. Before this, a lookup by id could hit a custom tag of the same name.

DDSpanContext: resolve names by the span's kind

• Name-keyed writes, reads (unsafeGetTag, so getTag, the stats aggregator's peer tags and sampling rules) and removes resolve direction-dependent names using the span's kind, then store by id.
• Every other tag costs a switch miss before TagMap's usual single lookup.
• A direction-dependent name written before the span has a kind is stored under its bare name and re-keyed when the kind is set. A flag keeps that off every other span.
• Side effect: the agent's default peer-tags list includes server.address, so on client spans it now reads peer.hostname.

Also

• Fixes the build after merging Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713 and Set known tags by id on TagMap and spans (otlp - tag registry - phase 2) #12715: BaseDecorator.setPeerPort sets peer.port by name and lets the span resolve it, and tests use an int tag whose name isn't shared.

Still to do (draft)

• Builder tags: resolve eagerly once the kind is known; defer only direction-dependent names written before it.
• OTLP output: pass the span's direction, so http.hostname → server.address inbound and peer.port → server.port / client.port.
• Retire span-kind-neutral.
• Tidy the generated code's indentation.
• JMH on the setTag / getTag / TagMap lookup paths.

Known gap: a span kind that changes from one direction to the other doesn't re-key entries that were already resolved; only entries written before any kind existed get re-keyed.

Contributor Checklist

• build-logic :tag-registry:test green
• :internal-api:test (KnownTags*, TagMap*) and :dd-trace-core:test (DDSpan*, DDSpanContext*, *Otlp*, *TagInterceptor*, new DDSpanDirectionalTagsTest) green

Jira ticket

N/A

🤖 Generated with Claude Code

[datadog-official]

🎯 Code Coverage (details)
• Patch Coverage: 75.10%
• Overall Coverage: 59.53% (+0.06%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: cc43136 | Docs | 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.77 s	14.66 s	[-0.1%; +1.6%] (no difference)
startup:insecure-bank:tracing:Agent	13.52 s	13.60 s	[-1.4%; +0.3%] (no difference)
startup:petclinic:appsec:Agent	17.21 s	17.08 s	[-0.3%; +1.9%] (no difference)
startup:petclinic:iast:Agent	16.97 s	17.03 s	[-1.2%; +0.5%] (no difference)
startup:petclinic:profiling:Agent	16.59 s	16.80 s	[-2.4%; -0.1%] (maybe better)
startup:petclinic:sca:Agent	17.15 s	17.00 s	[-0.2%; +1.8%] (no difference)
startup:petclinic:tracing:Agent	16.13 s	16.12 s	[-0.8%; +0.9%] (no difference)

Commit: cc43136f · 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-09T18:47:38.206541Z	a17c830	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: a17c830e25

ℹ️ 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".

[chatgpt-codex-connector]

Route bulk tag writes through directional resolution

When a directional key is supplied through CoreSpanBuilder.withTag(...), AgentSpan.setAllTags(...), or a SpanPrototype, the bulk paths in setAllTags, seedAbsentTags, and the ledger handling insert the entry directly instead of applying this resolution. Consequently, even when span.kind is known, peer.port remains a custom tag with ID 0 and is exported as peer.port rather than client.port/server.port; if the kind is assigned later, unresolvedDirectionalTags is never set and the entry is never re-keyed. Apply the same directional resolution to every bulk entry source.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Pass the span direction to OTLP attribute naming

When OTel semantics are enabled, the production JSON and protobuf exporters still call the directionless TagMap.EntryReader.openTelemetryTag(), so this new overload has no production caller that supplies the span's direction. As a result, direction-scoped renames such as http.hostname to server.address and network.client.ip to network.peer.address are not applied on inbound spans, and OTLP output continues using the Datadog keys.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Re-key tags when the span direction changes

If span.kind is first set to client, a directional tag such as peer.port is stored under the outbound ID; changing the public tag later to server or consumer leaves unresolvedDirectionalTags false, so this method never moves that entry to the inbound ID. Reads then use the new direction and can miss the existing value, while a later write creates a second peer.port entry with the other ID, causing inconsistent map views and duplicate/conflicting OTLP attributes. Re-key existing directional entries whenever the ordinal changes direction, not only when they were initially unresolved.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Preserve last-write ordering while resolving aliases

When two names that will resolve to the same tag are written before span.kind—for example server.address followed by the canonical peer.hostname—the older custom entry is collected here and then unconditionally written over the newer known entry. With multiple unresolved aliases such as peer.port and server.port, the winner instead depends on bucket iteration order rather than call order. Re-keying must preserve the normal last-write-wins behavior so setting the kind does not change the value.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Synchronize publishing unresolved tags with setting the kind

When one thread writes a directional tag while another assigns the first span.kind, the writer can read DIRECTION_UNKNOWN, then the kind-setting thread can update the ordinal and observe unresolvedDirectionalTags == false, after which the writer sets this flag and stores the bare custom entry. No later kind transition is required, so that entry remains unresolved and is exported under the wrong name. Coordinate the ordinal/flag transition under the same unsafeTags lock or recheck the direction after publishing the unresolved entry.

Useful? React with 👍 / 👎.

[datadog-official]

Directional tag updates can leave stale values visible, and assigning a span kind can overwrite newer alias values. Shared-name storage also violates replacement, parent-shadowing, and entry hash-code contracts.

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit a17c830}

[datadog-official]

Apply directional resolution to bulk tag writes

On a client span, setting peer.port individually and then updating it through setAllTags leaves getTag("peer.port") returning the older value. The bulk Map, TagMap, and ledger paths bypass directional storage, creating bare-name entries instead of replacing resolved IDs. They also fail to mark pre-kind writes for later resolution. Apply the same directional policy across all bulk paths.

Was this helpful? React 👍 or 👎
_{🤖 Bits Code Review · Open Bits AI session}

[datadog-official]

Preserve shared-name replacement and parent shadowing

A bare-name peer.port entry and a resolved port ID have different bucket hashes despite sharing the same Map key. Setting an outbound ID to 5432 and then calling put("peer.port", 6000) returns null, increases size to two, and still reads 5432. A resolved local entry also fails to shadow a bare-name parent entry, exposing duplicate serialized keys. Replacement and parent visibility must recognize both representations.

Was this helpful? React 👍 or 👎
_{🤖 Bits Code Review · Open Bits AI session}

[datadog-official]

Preserve write order when resolving deferred tags

Writing server.address before the span kind, then writing a newer peer.hostname value, causes setting the kind to client to overwrite the newer value with the older deferred address. Deferred peer.port can similarly remove and overwrite a later explicit outbound-ID write. Re-keying must preserve write precedence; simply skipping occupied destinations would also mishandle the reverse write order.

Was this helpful? React 👍 or 👎
_{🤖 Bits Code Review · Open Bits AI session}

[datadog-official]

Synchronize the deferred-tag flag check with writes

A concurrent tag writer can read DIRECTION_UNKNOWN before the kind writer updates the ordinal, while the kind writer checks unresolvedDirectionalTags before the tag writer sets it. The directional tag then remains under its bare name indefinitely. For server.address on a client span, peer.hostname reads consequently miss the value. Check the deferred flag under the same unsafeTags lock used by tag writers.

Suggested change

	if (unresolvedDirectionalTags) {
	resolveDirectionalTags();
	}
	synchronized (unsafeTags) {
	if (unresolvedDirectionalTags) {
	resolveDirectionalTags();
	}
	}

Was this helpful? React 👍 or 👎
_{🤖 Bits Code Review · Open Bits AI session}

[datadog-official]

Keep entry hash codes consistent with equality

Inbound and outbound peer.port entries with equal values compare equal because Entry.equals uses only the name and value. Entry.hashCode delegates to hash(), which now returns different ID-derived hashes for those entries. Hash-based collections can therefore miss equal entries or retain duplicates. Separate the public equality hash from the bucket hash required for ID lookup.

Was this helpful? React 👍 or 👎
_{🤖 Bits Code Review · Open Bits AI session}

[datadog-official]

Bulk updates and inherited defaults can leave bare-name and direction-specific entries for the same tag, producing stale peer.port reads and duplicate serialized keys. Concurrent kind assignment can also miss deferred resolution, and equal directional entries now receive different hashes.

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit d509119}

[datadog-official]

Resolve directional names in bulk tag writes

On a client span, set peer.port=80, then call setAllTags with a separate TagMap containing peer.port=81. The bulk path inserts a bare-name entry alongside the outbound-ID entry, so getTag("peer.port") still returns 80 instead of 81 and serialization can emit duplicate keys. Bulk, ledger, and prototype paths need the same directional resolution and deferred-resolution bookkeeping as individual setters.

Was this helpful? React 👍 or 👎
_{🤖 Bits Code Review · Open Bits AI session}

[datadog-official]

Shadow inherited bare-name tags when storing a directional ID

When a frozen parent contains bare-name peer.port and its child writes PEER_PORT_OUTBOUND_ID, removeLocal cannot hide the inherited entry. Parent visibility compares bucket hashes, which now differ between the two representations, so iteration and size expose both mappings. Configured tracer tags use this parent mechanism; copying the span's tags into an ordinary map can overwrite its explicit value with the inherited default. Parent shadowing must recognize equivalent shared-name representations.

Was this helpful? React 👍 or 👎
_{🤖 Bits Code Review · Open Bits AI session}

[datadog-official]

Synchronize kind assignment with deferred directional writes

A directional-tag setter can read DIRECTION_UNKNOWN under unsafeTags, then another thread can publish the first span kind and observe unresolvedDirectionalTags=false before the setter raises it. Resolution is permanently skipped: server.address remains a custom tag and getTag("peer.hostname") returns null on the client span. Publish the kind and inspect the deferred flag under the same lock as directional writes.

Suggested change

	spanKindOrdinal = spanKindOrdinalOf(kind);
	if (unresolvedDirectionalTags) {
	resolveDirectionalTags();
	}
	synchronized (unsafeTags) {
	spanKindOrdinal = spanKindOrdinalOf(kind);
	if (unresolvedDirectionalTags) {
	resolveDirectionalTags();
	}
	}

Was this helpful? React 👍 or 👎
_{🤖 Bits Code Review · Open Bits AI session}

[datadog-official]

Preserve equal hashes for name-equal tag entries

Entries created with PEER_PORT_INBOUND_ID and PEER_PORT_OUTBOUND_ID and the same value compare equal because Entry.equals compares their shared Datadog name and value. Entry.hashCode delegates to this changed method, giving those equal entries different hashes and causing failed lookups or duplicates in hash collections. Separate the internal ID-based bucket hash from the public equality-compatible hashCode.

Was this helpful? React 👍 or 👎
_{🤖 Bits Code Review · Open Bits AI session}