fix(otel): [Queue Instrumentation 34] Fix OTel messaging span mapping correctness#5337
Draft
adinauer wants to merge 6 commits intotest/queue-instrumentation-kafka-auto-config-filter-otelfrom
Conversation
…ans to Sentry queue ops Wire OTel messaging spans into the Sentry Queues product when `sentry.enable-queue-tracing=true` so OTel-only setups (e.g. the agentless Spring Boot Jakarta sample) populate queue dashboards without needing the Sentry-native Kafka interceptors. `SpanDescriptionExtractor` now recognizes spans carrying `messaging.system` and maps them to `queue.publish` / `queue.process` / `queue.receive` ops, using the destination name as the description and `TransactionNameSource.TASK`. Op selection prefers `messaging.operation.type` (current OTel semconv), falls back to the deprecated `messaging.operation`, and only as a last resort consults `SpanKind` — `SpanKind.CONSUMER` is overloaded for both `receive` and `process`, so attribute-driven mapping is required to disambiguate. The extractor takes `SentryOptions` so the mapping stays gated; when the flag is off, behavior is unchanged. `SentrySpanExporter` additionally transfers the messaging attributes (`system`, `destination.name`, `operation.type`, `message.id`, `message.body.size`, `message.envelope.size`) onto root transactions. Root transactions don't bulk-copy OTel attributes the way child spans do, but the Queues product reads `trace.data.messaging.*`, so consumer root transactions need them propagated explicitly. These are operational metadata only (no payload contents), so the transfer is unconditional. Add `MESSAGING_OPERATION_TYPE` and `MESSAGING_MESSAGE_ENVELOPE_SIZE` to `SpanDataConvention` for use by the exporter and downstream integrations. Document the OTel-mode behavior in the two Jakarta OTel sample `application-kafka.properties` so users know the flag activates the OTel remapping path here, not the Sentry-native Kafka auto-config (which stays suppressed by its `@ConditionalOnMissingClass` OTel guard).
Some OTel instrumentations (notably aws-sdk-2.2 SQS) attach both `http.request.method` and `messaging.system` to the same span. With the previous gate order, those spans resolved to http.client and the Sentry Queues product never lit up for one of the most common OTel-coexistence targets. When `enableQueueTracing` is true and `messaging.system` is present, map to a queue.* op before the http and db checks. When the flag is off, the existing http-first ordering is preserved. Co-Authored-By: Claude <[email protected]>
…blish The OTel messaging semconv defines "create" and "publish" as distinct operations: "create" represents message construction, "publish" the network send. Folding both into queue.publish risks double-counting producer transactions on instrumentations that emit a separate create span (per OTel semconv guidance). Per the Sentry Queues telemetry spec (https://develop.sentry.dev/sdk/telemetry/traces/modules/queues/), queue.create is a canonical op distinct from queue.publish, so map "create" to its spec-correct destination rather than dropping it. Empirically, current Kafka OTel instrumentation does not emit a separate create span, so this is a no-op for Kafka users today; the change future-proofs other systems and any future Kafka OTel version. Co-Authored-By: Claude <[email protected]>
The setEnableQueueTracing Javadoc said only "Whether queue operations (publish, process) should be traced." — silent on the fact that the flag also drives OTel messaging-span transformation when sentry-opentelemetry is on the classpath. Reword on both the getter and setter to make explicit that the flag both emits Sentry-native queue spans and transforms OTel messaging spans to match Sentry's queue conventions, so customers grepping their IDE see what the flag does in either integration mode. Co-Authored-By: Claude <[email protected]>
OTel messaging semconv defines messaging.operation.type=settle for consumer ack/nack/reject spans (JMS, RabbitMQ, Pulsar acknowledge). The switch had no case for "settle", so settle spans on SpanKind.CONSUMER were falling through to the SpanKind fallback and becoming queue.process — duplicating the real process span — while on SpanKind.CLIENT they became the generic "queue" default. queue.settle is one of the canonical Queues telemetry ops per https://develop.sentry.dev/sdk/telemetry/traces/modules/queues/, so add the explicit mapping. Co-Authored-By: Claude <[email protected]>
The OTel Kafka sample properties carried a 10-line comment explaining the OTel->Sentry remapping mechanism and SentryKafkaQueueConfiguration suppression behavior. That belongs in the SDK docs, not in a sample config — drop it so the property line speaks for itself. Co-Authored-By: Claude <[email protected]>
📲 Install BuildsAndroid
|
Contributor
Performance metrics 🚀
|
This was referenced Apr 27, 2026
This was referenced Apr 27, 2026
Open
Open
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR Stack (Queue Instrumentation)
📜 Description
Follow-up fixes to the OTel messaging span mapping introduced in [Queue Instrumentation 33]:
enableQueueTracingis on, checkmessaging.systembeforehttp.request.methodso OTel AWS SDK SQS spans (which carry both attributes) are classified as queue spans, not HTTP spans.createmapping — map the"create"operation type toqueue.createinstead ofqueue.publish, matching the spec.settlemapping — add explicit"settle"→queue.settlearm.enableQueueTracinggetter/setter docs.application-kafka.properties.💡 Motivation and Context
Review of Queue Instrumentation 33 surfaced several correctness and documentation issues (F002, F004, F007, F008 from internal review). This PR addresses them as a batch of small targeted fixes.
💚 How did you test it?
create→queue.createandsettle→queue.settlemappingsSpanDescriptionExtractorTesttests pass📝 Checklist
sendDefaultPIIis enabled.🔮 Next steps
Continue addressing remaining review findings (F001, F005, F006, F009–F017).
#skip-changelog