open-telemetry / open-telemetry/opentelemetry-java-instrumentation
Update to the latest messaging semantic conventions in 3.0
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 2.6k
- Forks
- 1.2k
- Avg merge
- 2d 18h
- Merged PRs (30d)
- 228
Description
Follow-ups
Deferred out of the #19347–#19357 stack, to be stacked on top of it. Each depends on
the shared contract as it exists after #19348, so none of them can be based on main.
-
Per-message attributes on batch links. Every batch link extractor adds a bare
span context and no attributes:spanLinks.addLink(Span.fromContext(extracted).getSpanContext());v1.43 says that when attribute values vary across a batch, the instrumentation SHOULD set
them on the links describing individual messages. This is the v1.27 "per-message link
attributes" milestone in the table above — the same one KafkaJS, Oban, Broadway and the
Lambda SQS instrumentations already implement.Most visible in Kafka, where the batch getter deliberately reports a topic only when every
record shares one, while per-record topic, partition, offset and key are available and
dropped. AffectsKafkaBatchProcessSpanLinksExtractor,
KafkaConnectBatchProcessSpanLinksExtractor,PulsarBatchRequestSpanLinksExtractor,
RocketMqBatchProcessSpanLinksExtractor,RocketMqReceiveSpanLinksExtractorand the
aws-sdk SQS receive path. Fix isaddLink(spanContext, attributes). -
Settlement spans. Keep the RabbitMQ and AWS SQS migrations that reclassify existing generic spans. Defer all other settlement work because settlement spans can be added later as a non-breaking telemetry addition.
-
Migrate AWS Lambda SQS events.
SqsEventAttributesExtractorand
SqsMessageAttributesExtractorare hand-rolledAttributesExtractors with locally copied
constants that hardcodemessaging.operationand never consult
emitStableMessagingSemconv(). Span names are still old-order
(getEventSource() + " process"). Needs rewriting ontoMessagingAttributesGetter/
MessagingAttributesExtractor/MessagingSpanNameExtractorwith dual-mode gating.
Blocks 3.0 GA. -
Migrate Apache Camel messaging.
camel-2.20carries a parallel span-decorator
subsystem inherited from Camel's OpenTracing model —DecoratorRegistry,
BaseSpanDecorator,MessagingSpanDecorator,KafkaSpanDecorator,S3SpanDecorator—
which hardcodes the oldmessaging.*attributes. Bridging it to the shared contract is a
subsystem change, not an attribute rename, so it is kept separate from the Lambda work.
Blocks 3.0 GA.
Neither instrumentation/aws-lambda/* nor instrumentation/camel-2.20/* is touched by any
PR in the stack, so under otel.instrumentation.common.v3-preview=true a trace that spans
one of them and a migrated instrumentation will mix old and new span-name formats and
attribute keys. That is by design — #19347 pins unmigrated instrumentations to the old
conventions so that opting in cannot change what they emit — but both migrations are marked
above as 3.0 GA blockers.
Background
The main worry I had with doing this was if other languages were sticking to the v1.24 messaging semantic conventions as recommended, in which case polyglot services would be adversely affected by us moving to the latest experimental messaging semantic conventions.
Did some AI-assisted research though and this this does not appear to be the case...
Post-v1.24 milestones used
| Release | Convention introduced |
|---|---|
| v1.25 | process operation and process metrics; settlement spans; messaging.destination.partition.id |
| v1.26 | messaging.operation.name; messaging.operation.type; messaging.client.id |
| v1.27 | Operation-first span names; current operation/consumed metrics; messaging.consumer.group.name; messaging.kafka.offset; per-message link attributes |
| v1.28 | Exhaustive operation-to-kind model; publish type replaced by send; current sent-message metric; optional creation-context parent for a single-message process span; ambient-parent guidance |
| v1.34 | aws.sqs.queue.url; aws.sns.topic.arn |
.NET
Pinned revision: 0f901706.
| Instrumentation | Default post-v1.24 conventions |
|---|---|
| Confluent.Kafka 0.2 alpha | v1.25 messaging.destination.partition.idv1.26 messaging.operation.name, messaging.operation.type, and messaging.client.idv1.27 messaging.consumer.group.name, messaging.kafka.offset, operation-first names, messaging.client.operation.duration, messaging.client.consumed.messages, and per-message link attributesv1.28 send operation value, exhaustive send/poll/process kinds, and messaging.client.sent.messagesSource explicitly pins the v1.43 contract |
| AWS Lambda SQS | v1.28 ambient invocation parent with links to record creation contexts |
The default AWS SDK semantic-convention selector does not itself qualify as evidence: its v1.28 mode emits no post-v1.24 messaging attributes. It is therefore excluded from the table.
AWS Lambda SQS is different: it qualifies through trace structure, not attributes. Its default ambient invocation parent plus record links implements the v1.28 guidance for processing under an existing ambient span.
For Confluent.Kafka, tracing and metrics registration are independent. The metrics above are the defaults after registering its metrics instrumentation; Confluent.Kafka does not emit the v1.25 messaging.process.duration metric.
Primary sources: ConfluentKafkaCommon, consumer, and Lambda options.
Go
Pinned revisions: Go contrib bb91f7a9 and compile instrumentation d3e016c6.
| Instrumentation | Default post-v1.24 conventions |
|---|---|
AWS SDK v2 SNS (otelaws) |
v1.26 messaging.operation.name and messaging.operation.typev1.28 send operation value |
| segmentio/kafka-go compile instrumentation | v1.25 messaging.destination.partition.idv1.26 messaging.operation.name and messaging.operation.typev1.27 messaging.consumer.group.name and messaging.kafka.offsetv1.28 send operation value |
These packages demonstrate post-v1.24 attribute adoption even though their spans are not complete current messaging models. The Kafka consumer's direct parent on a receive span is a deviation, not v1.28 evidence, and is intentionally omitted.
Primary sources: SNS attributes and Kafka semconv.
JavaScript
Pinned revision: 2927088f.
| Instrumentation | Default post-v1.24 conventions |
|---|---|
| KafkaJS | v1.25 messaging.destination.partition.id and messaging.process.durationv1.26 messaging.operation.name and messaging.operation.typev1.27 messaging.kafka.offset, operation-first names, messaging.client.operation.duration, messaging.client.consumed.messages, and per-message link attributesv1.28 send value, exhaustive send/poll/process kinds, and messaging.client.sent.messages |
| AWS Lambda SQS | v1.26 messaging.operation.name and messaging.operation.typev1.27 operation-first process name and per-message link attributes v1.28 process-to-CONSUMER kind and ambient-parent guidance v1.34 aws.sqs.queue.url |
| AWS SDK SNS | v1.34 aws.sns.topic.arn |
| AWS SDK SQS | v1.26 messaging.operation.typev1.27 per-message receive-link attributes v1.28 send-to-PRODUCER pairing |
| amqplib | v1.25 process operationv1.27 operation-first publish name pattern v1.28 creation-context parent option for the process span |
Primary sources: KafkaJS, AWS Lambda, AWS SNS, and amqplib.
Python
Pinned revision: 79f9e575.
| Instrumentation | Default post-v1.24 conventions |
|---|---|
| AWS Lambda SQS | v1.26 messaging.operation.typev1.27 operation-first process name and per-message link attributes v1.28 process-to-CONSUMER kind and ambient-parent guidance |
| botocore SNS | v1.28 send operation value and send-to-PRODUCER pairingv1.34 aws.sns.topic.arn |
| boto3sqs | v1.25 process operation |
| pika | v1.25 process operationv1.28 send value and creation-context parent option for process |
| aio-pika | v1.25 process operationv1.28 send value and creation-context parent option for process |
| aiokafka | v1.28 send operation value |
| confluent-kafka | v1.25 process operationv1.28 send operation value |
| kafka-python | v1.28 send operation value |
Python's shared stability helper has no messaging mode, so these are fixed package defaults rather than a messaging semconv opt-in.
Primary sources: AWS Lambda SQS, botocore extension, and Confluent Kafka.
PHP
Pinned revision: 176b3fc5.
| Instrumentation | Default post-v1.24 conventions |
|---|---|
| ExtAmqp | v1.25 settlement span concept v1.26 messaging.operation.type and messaging.client.idv1.28 settlement-to-CLIENT pairing |
| ExtRdKafka | v1.25 process operationv1.26 messaging.operation.typev1.27 messaging.kafka.offset and operation-first send namev1.28 send value, send-to-PRODUCER pairing, process-to-CONSUMER pairing, and creation-context parent option for process |
| Laravel queues | v1.26 messaging.operation.typev1.27 operation-first names v1.28 exhaustive create/send/receive/process kind pairings where applicable and creation-context parent option for process |
ExtRdKafka's incorrect consumer span name is a deviation and is not counted as post-v1.24 evidence.
Primary sources: ExtAmqp, ExtRdKafka, and Laravel queue worker.
Ruby
Pinned revision: 447d3a15.
| Instrumentation | Default post-v1.24 conventions |
|---|---|
| ActiveJob | v1.25 process operation |
| Sidekiq | v1.25 process operation |
| Resque | v1.25 process operation |
| Que | v1.25 process operation |
| DelayedJob | v1.25 process operation |
| Bunny | v1.25 process operationv1.28 creation-context parent option for process |
| ruby-kafka | v1.25 process operationv1.27 messaging.kafka.offset |
| rdkafka | v1.25 process operationv1.27 messaging.kafka.offset |
| Racecar | v1.25 process operationv1.27 messaging.kafka.offset |
The job instrumentations retain many legacy attributes, but their default process terminology is still a post-v1.24 convention. This is direct evidence of hybrid default adoption.
Primary sources: ActiveJob, Sidekiq, Resque, and Que.
Erlang/Elixir
Pinned revision: 04894327.
| Instrumentation | Default post-v1.24 conventions |
|---|---|
| Oban | v1.26 messaging.operation.name, messaging.operation.type, and messaging.client.idv1.27 operation-first send/process names and per-job link attributes v1.28 exhaustive PRODUCER/CONSUMER pairings |
| Broadway | v1.26 messaging.operation.type=processv1.27 message IDs on batch links v1.28 process-to-CONSUMER pairing |
Commanded is omitted because its post-v1.24 reference is only a comparison showing that direct parentage on a receive-oriented span is a deviation. It does not emit a qualifying default post-v1.24 convention.
Primary sources: Oban producer, Oban consumer, and Broadway.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the shared contract after #19348, then inspect the named batch link extractors and the AWS Lambda SQS classes under instrumentation/aws-lambda/; the issue also identifies the parallel Camel subsystem under instrumentation/camel-2.20/. Done means the listed migrations follow the latest messaging conventions, preserve the deferred settlement scope, and satisfy the stated 3.0 GA blockers.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, java, rabbitmq
- Domain
- backend, distributed-systems, observability
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100