Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2)

[dougqh]

What Does This Do

Follow-on to #12354 (stacked on it; the diff here is only the follow-on). #12354 had to drop several OpenTelemetry renames because their meaning depends on span direction, and a flat rename cannot express that. This PR teaches the tag registry about direction. This phase (2) is registry-only. Every rename TagMap and OTLP apply today is unchanged; the one generated change is that peer.port becomes one tag per direction (see below).

The problem

OpenTelemetry names fall into two frames:

• Absolute — a fixed role: server.address, server.port, client.address, client.port.
• Relative — the other end of the connection: network.peer.address, network.peer.port.

Datadog mixes the two as well. http.hostname and http.client_ip are absolute, but peer.hostname, peer.ipv4/6, and peer.port are relative. HttpServerDecorator sets peer.port to the client's port, and the client decorators set it to the server's. So server.address is http.hostname on an inbound span and peer.hostname on an outbound one, and peer.port is client.port inbound but server.port outbound.

Same-frame mappings never need context. Mapping a relative name to an absolute one needs exactly one bit: the span's direction.

What changes (phase 2)

The conventions are arranged like an object model: span types are classes, mixins are traits. Direction now fits that model.

• span-kind on span types and mixins (server|client|producer|consumer|internal, inherited through extends). It sets the direction: server/consumer are inbound, client/producer are outbound, internal has none. A directional mixin may only reach span types of its direction, and a span type may not change the direction it inherits through extends; the generator checks both, so no type can receive both sides of a tag declared per direction.

• Where a rename is declared scopes it. In a scope without a span-kind (trace_level, an abstract type, a plain mixin) it applies in every direction; in a directional scope, only in that direction.

• A tag whose meaning flips with direction is declared once per direction, each declaration in its own directional mixin. Each becomes its own tag, <dd-name>@<direction>, with fixed names in both namespaces:

  outbound_peer:              # the other end of an outbound connection: the server
    span-kind: client
    tags:
      - { dd-name: peer.hostname, otel-name: server.address }
      - { dd-name: peer.port,     otel-name: server.port }
  inbound_peer:               # the other end of an inbound connection: the client
    span-kind: server
    tags:
      - { dd-name: peer.port,     otel-name: client.port }

  peer.port@outbound and peer.port@inbound share the Datadog name, but each has one OTel name, so the reverse translation needs no context: input resolves to the specific tag, and output is a plain id→name lookup per namespace. Any other repeated declaration is still an error, and a ref to a shared name resolves by the referencing scope's direction.

• Shared Datadog names are explicit. peer.port is one name for two tags. It isn't 1-to-1, so the mapping from name to tag needs context, while the mapping from tag to name doesn't. KnownTags generates no name constant for it, since a bare "peer.port" would only invite direction-blind use. Callers use the unambiguous IDs (PEER_PORT_OUTBOUND_ID, PEER_PORT_INBOUND_ID), each documented with its name and direction. tag-assignment.txt lists shared names:

  # SHARED DATADOG NAMES ...
    peer.port                      -> peer.port@inbound, peer.port@outbound
  

• Names are unique per direction, in both namespaces. server.address is http.hostname inbound and peer.hostname outbound; peer.port is one tag per direction.

• Only direction-free renames feed the generated tables, because TagMap and OTLP do not know a span's direction yet. Direction-scoped renames are validated and listed in tag-assignment.txt:

  # DIRECTION-SCOPED OPENTELEMETRY NAMES ...
    client.port                    inbound   -> peer.port@inbound
    network.peer.address           inbound   -> network.client.ip
    server.address                 inbound   -> http.hostname
    server.address                 outbound  -> peer.hostname
    server.port                    outbound  -> peer.port@outbound
  

• The one interim runtime change: the bare peer.port names two tags, so the direction-free keyOf("peer.port") returns 0 (unknown) instead of guessing. Its output is unchanged: it had no direction-free rename, so it still exports as peer.port.

• span-kind-neutral narrows to "apply this directional rename in every direction" (for example, db.system only ever names a database). It is still required on a concrete type with no span-kind, and is rejected on a tag declared per direction, whose meaning flips with direction by definition. Phase 3 removes it.

• YAML: every concrete type declares a span-kind. peer.* is split into peer_address (peer.ipv4/6, shared), outbound_peer, and inbound_peer, so http.server now carries its client's peer.*, fixing Add the tag registry and map OpenTelemetry tag names through it (otlp - tag registry - phase 1) #12354's client-only modeling.

Planned phases

1. Add the tag registry and map OpenTelemetry tag names through it (otlp - tag registry - phase 1) #12354, the tag registry: registry, generated KnownTags, and the direction-free OpenTelemetry renames.
2. This PR, registry model: span directions, directional mixins, per-direction declarations and validation, and the YAML. Its sibling Set known tags by id on TagMap and spans (otlp - tag registry - phase 2) #12715 adds setting known tags by id.
3. Runtime resolution (Resolve direction-dependent tag names by the span's kind (otlp - tag registry - phase 3) #12731): writers resolve input to the specific tag using the span's direction, and serializers emit by id. Resolution happens in the core span (DDSpanContext), using its span kind; the per-direction lookup is generated into KnownTags. This retires span-kind-neutral.
4. Remaining mappings, after a semantic-conventions audit: network.peer.address for peer.ipv4/6, which splits by address family rather than direction, so the registry can't resolve it. The plan is a resolved-by: <layer> marker naming the layer responsible (e.g. the OTel API layer), which allows the mutually exclusive shared output name and keeps it out of every lookup table. Also: messaging consumers, where it needs checking whether server.address means the broker; and proxies, which may carry both frames on one span.

Phase 3 is #12731, a separate PR. It builds on this PR and on #12715, which adds setting known tags by id to TagMap and spans (a sibling of this PR in phase 2, also stacked on #12354):

phase 1              phase 2                                       phase 3
            ┌──► #12713 (this PR: registry directions) ──┐
#12354 ─────┤                                            ├──► #12731: writers resolve to ids by direction
            └──► #12715 (set tags by id) ────────────────┘

Motivation

Resolution belongs at the writer, which has the context to pick the right concept. Datadog instrumentation writes by Datadog name, the OTel bridge knows its span kind, and a serializer knows its target namespace. Each tag needs one identity and unique input names, while output names may collide across directions. dd-trace-dotnet reaches the same result with typed ClientTags/ServerTags classes; here the registry carries that context instead.

Additional Notes

• New generator tests follow the suite's existing conventions. They cover typed renames scoped to their direction, one name mapping to different tags per direction, and span-kind-neutral widening, plus 10 invalid configurations.
• Tag ids shift because peer.port becomes two tags; ids are not a stable contract. The direction-free rename table is identical to Add the tag registry and map OpenTelemetry tag names through it (otlp - tag registry - phase 1) #12354's.

Generated report changes

The generated reports now live under internal-api/build/generated/tag-registry/ (regenerate with ./gradlew :internal-api:generateKnownTags), so they no longer show up in the PR diff. Here they are against #12354. Labels like peer.port@inbound are the generator's derived identities for a name declared per direction, not YAML syntax.

resolved-tags.txt: http.server gains its client's peer.*; peer.port becomes one tag per direction

--- resolved-tags.txt (#12354)
+++ resolved-tags.txt (this PR)
@@ -24,10 +24,10 @@
   - peer.service
   - _dd.peer.service.source
   - _dd.peer.service.remapped_from
-  - peer.hostname
   - peer.ipv4
   - peer.ipv6
-  - peer.port
+  - peer.hostname
+  - peer.port@outbound
 
 http.client  (21 tags):
   - _dd.parent_id
@@ -47,12 +47,12 @@
   - peer.service
   - _dd.peer.service.source
   - _dd.peer.service.remapped_from
-  - peer.hostname
   - peer.ipv4
   - peer.ipv6
-  - peer.port
+  - peer.hostname
+  - peer.port@outbound
 
-http.server  (21 tags):
+http.server  (24 tags):
   - _dd.parent_id
   - service
   - component
@@ -74,6 +74,9 @@
   - servlet.context
   - http.client_ip
   - network.client.ip
+  - peer.ipv4
+  - peer.ipv6
+  - peer.port@inbound
 
 view.render  (10 tags):
   - _dd.parent_id

tag-assignment.txt: peer.port splits in two (serials after it shift by one); new direction-scoped and shared-name sections

--- tag-assignment.txt (#12354)
+++ tag-assignment.txt (this PR)
@@ -1,4 +1,4 @@
-# Tag id assignment.  tags=53
+# Tag id assignment.  tags=54
 
 # TAGS     serial lvl id                 required     name
        1   T  0x0001000000000004 recommended  _dd.appsec.enabled
@@ -41,19 +41,20 @@
       38   -  0x0026000000000000 recommended  peer.hostname
       39   -  0x0027000000000000 optional     peer.ipv4
       40   -  0x0028000000000000 optional     peer.ipv6
-      41   -  0x0029000000000000 optional     peer.port
-      42   -  0x002A000000000000 recommended  peer.service
-      43   T  0x002B000000000004 required     runtime-id
-      44   -  0x002C000000000000 required     service
-      45   -  0x002D000000000000 optional     servlet.context
-      46   -  0x002E000000000000 optional     servlet.path
-      47   -  0x002F000000000000 required     span.kind
-      48   -  0x0030000000000000 recommended  test.framework
-      49   -  0x0031000000000000 recommended  test.name
-      50   -  0x0032000000000000 recommended  test.status
-      51   -  0x0033000000000000 recommended  test.suite
-      52   T  0x0034000000000004 recommended  version
-      53   -  0x0035000000000000 recommended  view.name
+      41   -  0x0029000000000000 optional     peer.port@inbound
+      42   -  0x002A000000000000 optional     peer.port@outbound
+      43   -  0x002B000000000000 recommended  peer.service
+      44   T  0x002C000000000004 required     runtime-id
+      45   -  0x002D000000000000 required     service
+      46   -  0x002E000000000000 optional     servlet.context
+      47   -  0x002F000000000000 optional     servlet.path
+      48   -  0x0030000000000000 required     span.kind
+      49   -  0x0031000000000000 recommended  test.framework
+      50   -  0x0032000000000000 recommended  test.name
+      51   -  0x0033000000000000 recommended  test.status
+      52   -  0x0034000000000000 recommended  test.suite
+      53   T  0x0035000000000004 recommended  version
+      54   -  0x0036000000000000 recommended  view.name
 
 # OPENTELEMETRY NAMES. keyOf(otelName) resolves to the canonical tag's id; nameOf still
 # returns the Datadog name, openTelemetryNameOf returns the name below. (No distinct id.)
@@ -66,3 +67,15 @@
   service.name                   -> service
   url.full                       -> http.url
   user_agent.original            -> http.useragent
+
+# DIRECTION-SCOPED OPENTELEMETRY NAMES. Each applies only on spans of the given direction, so
+# it is not in the tables above; name resolution does not use it until it knows the direction.
+  client.port                    inbound   -> peer.port@inbound
+  network.peer.address           inbound   -> network.client.ip
+  server.address                 inbound   -> http.hostname
+  server.address                 outbound  -> peer.hostname
+  server.port                    outbound  -> peer.port@outbound
+
+# SHARED DATADOG NAMES. One Datadog name for a tag per direction: emitting it needs no context,
+# but resolving the name to a tag needs the span's direction, so keyOf does not resolve it yet.
+  peer.port                      -> peer.port@inbound, peer.port@outbound

Contributor Checklist

• build-logic :tag-registry:test (71 tests) and :tag-registry:spotlessCheck green
• :internal-api:test (KnownTags*, TagMap*), :dd-trace-core:test (*otlp*, *taginterceptor*), OpenTelemetry14ConventionsTest green

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.73 s	14.63 s	[-0.1%; +1.5%] (no difference)
startup:insecure-bank:tracing:Agent	13.52 s	13.56 s	[-1.1%; +0.5%] (no difference)
startup:petclinic:appsec:Agent	17.10 s	17.00 s	[-0.2%; +1.4%] (no difference)
startup:petclinic:iast:Agent	17.01 s	16.97 s	[-0.7%; +1.2%] (no difference)
startup:petclinic:profiling:Agent	16.37 s	16.77 s	[-3.4%; -1.3%] (significantly better)
startup:petclinic:sca:Agent	17.09 s	16.89 s	[+0.2%; +2.2%] (maybe worse)
startup:petclinic:tracing:Agent	16.11 s	16.07 s	[-0.5%; +1.1%] (no difference)

Commit: 885bdb5f · 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.

[datadog-datadog-prod-us1]

The two most critical issues are: (1) inherited shared-name tags from a directional parent are not validated against a child's differing direction, allowing ambiguous resolved tag sets containing both inbound and outbound identities; and (2) shared-name aliases marked span-kind-neutral are incorrectly included in direction-free runtime tables, causing their resolved IDs to be lost and OTLP to emit the wrong tag name.

_{Open Bits AI session}

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

[sarahchen6]

One minor comment, but otherwise LGTM

[datadog-datadog-prod-us1]

More details

Direction-scoped renames remain outside the runtime lookup tables. Shared peer.port names resolve as unknown while retaining their exported Datadog name, consistent with the intended phase-2 boundary.

Was this helpful? React 👍 or 👎

_{Open Bits AI session}

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

[datadog-datadog-prod-us1]

More details

The direction-free rename table remains unchanged, and generator checks confirm that conflicting inherited directions are rejected.

Was this helpful? React 👍 or 👎

_{Open Bits AI session}

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

[datadog-datadog-prod-us1]

More details

Current tag conventions generate valid Java and preserve direction-free OpenTelemetry renames. The sole candidate requires a hypothetical shared tag name containing a comment terminator and falls below the requested reporting threshold.

Was this helpful? React 👍 or 👎

_{Open Bits AI session}

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

[dd-octo-sts]

/merge

[gh-worker-devflow-routing-ef8351]

View all feedbacks in Devflow UI.

2026-10-09 13:36:10 UTC ℹ️ Start processing command /merge

---

2026-10-09 13:36:15 UTC ℹ️ MergeQueue: pull request added to the queue

The expected merge time in master is approximately 1h (p90).

---

2026-10-09 14:50:04 UTC ℹ️ MergeQueue: This merge request was merged