Register APM tag constants on their span types (otlp - tag registry)

[dougqh]

What Does This Do

Registers the APM tag constants in the tag registry, each on the span types it's actually set on, so instrumentation can migrate to setting tags by KnownTags.*_ID and every tag gets a dense-store slot. A ratchet test tracks what's left.

• A ratchet over the tag constants. TagConstantsRegistryCoverageTest requires every String constant in Tags, InstrumentationTags and DDTags to be registered, or listed by name or pattern (*):
  • NEVER_REGISTERED maps each deliberate exception to its reason: values of a tag (Tags.SPAN_KIND_*), a name prefix, a name pattern, an operation name, names only the serializers write, and unused public API.
  • NOT_YET_REGISTERED_FAMILIES names whole families with a reason, today the CI Visibility constants (Tags.TEST_*, Tags.GIT_*, Tags.CI_*, ...). A family excuses only its unregistered constants, and is stale once none is left.
  • NOT_YET_REGISTERED lists single constants and can only shrink: registering one fails the test until its entry is removed. A new constant must be registered or listed.
• Placement from the code. For each tag I checked its production set sites (as a constant and as a string literal), its value type, and which spans it lands on, and placed it there: as low in the type hierarchy as it belongs, because a tag on a broad type takes a slot in every subtype's clique.
• Span types and mixins. Span types model a concept or an extension of one concept. Mixins are for concerns that cut across span types or kinds: product add-ons (Data Streams, Database Monitoring, Exception Replay, the debugger's code origin), inherited sampling, the AWS request tags shared by AWS client and SQS consumer spans, and a messaging system (Kafka, AMQP), which spans producers, consumers and more.
• Generator: the Java overlay can declare span_types and mixins. Java-only tags (servlet's, Spring's, TIBCO's, Mule's) live in tag-conventions-java.yaml, keeping the shared file language-agnostic. An overlay span type must extend a span type; an overlay mixin must say what it applies to. servlet.path and servlet.context move out of the shared file into a Java servlet.request type.

New span types

• Messaging: messaging.producer, .consumer, .broker (time in queue), .client (AMQP commands), .poll, with kafka and amqp mixins.
• RPC: rpc.client, rpc.server.
• Databases: db.client keeps what any database client sets; db.sql (JDBC, R2DBC), db.cassandra, db.couchbase, db.redis and db.mongo extend it. Database Monitoring's propagation tags are a dbm mixin on db.sql and db.mongo.
• AWS: aws.client (an http.client) and one type per service: aws.s3, .sqs, .sns, .kinesis, .dynamodb, .sfn, .lambda. One aws.client holding every service's tags would be 67 tags, over the 63-slot cap, though a span never carries two services' tags.
• Websocket: websocket.receive, .send, .close.
• Generic: web.handler (framework controller spans), internal (internal spans no other type models).
• Java overlay: servlet.request, spring.view.render, spring.webflux.handler, spring.webflux.client, tibco.process, mule.action, elasticsearch.rest, elasticsearch.transport, twilio.sdk, jsp.compile, jsp.render, quartz.job, hystrix.command.

Motivation

The registry had 66 tags against about 350 tag constants. The migration to ids needs every tag registered, and the dense store gives a tag a precise slot only when it's on the span types it appears on.

Additional Notes

• No functional change at runtime beyond more tags having ids. Two unreferenced constants are deleted from internal-api: Tags.DB_HOST and InstrumentationTags.JMS_PRODUCE (whose string is JMSDecorator's operation name).
• Coverage: every constant outside CI Visibility is registered or deliberately never registered. What remains is the CI Visibility families (about 100 tags on test spans), in a follow-up PR for that team to review. Some tags have no constant and are registered anyway (jsp.requestURL, elasticsearch.action, ...): tags set only by literal are outside this test's reach, and APMLP-2046 proposes auditing them in the instrumentation tests.
• Slots: with Color known tags into co-occurrence slots in their ids (phase 3a - groundwork - dense tag storage) #12882's coloring the 213 tags use 47 slots, under the cap of 63. The largest clique is elasticsearch.transport, which adds 21 tags to db.client.
• trace_level holds both process-static facts (the .enabled flags, now including _dd.apm.enabled) and values common to a trace (local-root tags such as the attribute schema version).
• Name patterns aren't registered. A family like _dd.code_origin.frames.<N>.<field> has unboundedly many names, so it can't have ids ahead of time and can't use the dense store; its members stay custom tags. Frame 0's constants are listed as never registered for that reason, and only _dd.code_origin.type is registered. A general registry could later describe patterns (name, type, OpenTelemetry naming) without ids.
• Open question: websocket spans copy peer.hostname from the handshake, but outbound_peer declares it for client spans only; left as a TODO in the YAML.
• Possible follow-up: span types for extensions of a concept mean some parallel types (AWS per service). If reviewers prefer an add-on concept, mutually exclusive mixins could be colored per alternative, so they'd cost no more slots than types.

🤖 Generated with Claude Code

[dougqh]

While I'll admit this test is a bit ugly, it acts as an explicitly sanity check that we're not missing anything. The exclusion list will get shorter in subsequent PRs.

[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	13.99 s	13.91 s	[-0.4%; +1.5%] (no difference)
startup:insecure-bank:tracing:Agent	12.96 s	12.99 s	[-1.0%; +0.5%] (no difference)
startup:petclinic:appsec:Agent	17.10 s	16.91 s	[+0.3%; +1.9%] (maybe worse)
startup:petclinic:iast:Agent	16.87 s	17.08 s	[-2.0%; -0.5%] (maybe better)
startup:petclinic:profiling:Agent	16.52 s	16.60 s	[-1.5%; +0.6%] (no difference)
startup:petclinic:sca:Agent	17.01 s	16.77 s	[+0.6%; +2.3%] (maybe worse)
startup:petclinic:tracing:Agent	15.64 s	16.12 s	[-7.2%; +1.2%] (no difference)

Commit: 9177a938 · 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-15T20:01:11.815625Z	20a0148	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.

[datadog-prod-us1-4]

The two most actionable issues are: messaging span type declarations (producer, consumer, client) omit peer address/hostname/service tag mixins that RabbitMQ instrumentation already writes, and web.handler spans are excluded from the code-origin tag applies list, causing Spring controller spans to omit _dd.code_origin.type from their resolved tag sets.

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit 20a0148}

[sarahchen6]

Changes look reasonable, though I'm not familiar with OTLP tag expectations TBH... Probably worth another check from the SDK Cap team