Skip to content

Migrate AWS SQS messaging telemetry to v1.43 - #19350

Merged
trask merged 13 commits into
mainfrom
trask/messaging-v1-43-aws
Aug 7, 2026
Merged

trask merged 13 commits into
mainfrom
trask/messaging-v1-43-aws

Conversation

@trask

@trask trask commented Jul 31, 2026 •

Copy link
Copy Markdown
Member

Migrates the AWS SQS instrumentation (aws-sdk-1.11, aws-sdk-2.2) to the v1.43 conventions: typed SQS telemetry, stable batch counts, receive links, and process spans that hang off the ambient context and link each message's creation context. A new SqsMessage abstraction gives both SDK versions a single view of a message, so the shared code doesn't have to be written twice.

messaging.operation.name is send, receive and process, after the SQS client API operations (SendMessage / SendMessageBatch, ReceiveMessage).

Default-path impact

One narrow fix in SqsParentContext.ofMessage (aws-sdk-2.2) is not gated.

The X-Ray fallback used to be skipped whenever the messaging propagator returned anything other than the exact Context.root() instance. A propagator that extracted only non-span state β€” baggage, for example β€” therefore suppressed the fallback even though no span had been extracted. It now checks for a valid extracted span instead, and applies the fallback on top of the propagator's extracted context rather than on Context.root(), so baggage and other non-span fields survive it.

Everything else is gated. The AWS SDK 1.11 batch path and the choice of process parent context (emitStableMessagingSemconv() ? parentContext : receiveContext) keep their current behavior when the opt-in is unset.

Part of #19254.

@trask trask changed the title Migrate AWS SQS messaging telemetry to v1.43 Migrate AWS SQS messaging telemetry to v1.43 preview Jul 31, 2026
@trask
trask force-pushed the trask/messaging-v1-43-aws branch from b5912bc to bf59997 Compare July 31, 2026 16:36
@opentelemetry-pr-dashboard

opentelemetry-pr-dashboard Bot commented Jul 31, 2026 •

Copy link
Copy Markdown

Pull request dashboard status

Merged Β· refreshed 2026-08-07 05:38 UTC

Status above doesn't look right?
  • Anything look wrong? Report it with what you expected; it helps us improve the dashboard.

@trask
trask force-pushed the trask/messaging-v1-43-aws branch from bf59997 to d82ed85 Compare August 1, 2026 18:40
@trask
trask force-pushed the trask/messaging-v1-43-aws branch from f69a87d to 253c712 Compare August 2, 2026 19:00
@trask trask changed the title Migrate AWS SQS messaging telemetry to v1.43 preview Migrate AWS SQS messaging telemetry to v1.43 Aug 3, 2026
@trask
trask force-pushed the trask/messaging-v1-43-aws branch 3 times, most recently from 822f9e9 to f333096 Compare August 3, 2026 23:27
@trask
trask force-pushed the trask/messaging-v1-43-aws branch 3 times, most recently from a9091c6 to ae3b6a1 Compare August 4, 2026 03:07
@trask
trask force-pushed the trask/messaging-v1-43-aws branch from ae3b6a1 to d172e60 Compare August 4, 2026 17:58
Base automatically changed from trask/messaging-v1-43-topology to main August 5, 2026 13:07
@trask
trask force-pushed the trask/messaging-v1-43-aws branch from fb866c8 to 9af7e48 Compare August 5, 2026 13:07
SpanContext spanContext =
Span.fromContext(message.getCreationContext()).getSpanContext();
if (spanContext.isValid()) {
spanLinks.addLink(spanContext);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wondering whether spec says anything about lining to the same creation context multiple times. Idk whether this would happen in practice.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good question, will follow-up: #19415

systemProperty("metadataConfig", "otel.semconv-stability.preview=messaging")
}

val testMessagingPreviewNoReceiveTelemetry = register<Test>("testMessagingPreviewNoReceiveTelemetry") {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wondering whether we still need the receive telemetry flag. As far as I remember we introduced it because spec demanded producer and consumer in separate linked traces, but since the backends didn't support span links we chose to keep them in the same trace. Now I think the spec allowed keeping single message producers and consumers in the same trace. It is fine if this is something that we should look into after the first batch of changes are done.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

.region(Region.AP_NORTHEAST_1)
.credentialsProvider(CREDENTIALS_PROVIDER)
.build()) {
client.purgeQueue(PurgeQueueRequest.builder().queueUrl(queueUrl).build());

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if the purgeQueue call also creates spans we might need to wait and clear them too

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

usually we add testing.waitForTraces(1); before clearing to ensure that the trace has been received. Idk whether the clearing itself is actually necessary because I think it is done anyway before each test

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@trask
trask requested a balanced review from Copilot August 5, 2026 22:21

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Migrates AWS SDK 1.11/2.2 SQS telemetry to v1.43 messaging conventions while preserving legacy behavior outside preview mode.

Changes:

  • Adds typed send, receive, and process telemetry with stable span names, kinds, links, and batch counts.
  • Revises process-parent and X-Ray fallback context handling.
  • Adds preview/dual-mode test coverage across AWS SDK and Spring Cloud AWS integrations.

Reviewed changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
instrumentation/spring/spring-cloud-aws-3.0/javaagent/src/test/java/.../AwsSqsTest.java Tests stable Spring SQS telemetry.
instrumentation/spring/spring-cloud-aws-3.0/javaagent/src/main/java/.../SpringAwsUtil.java Propagates creation and ambient contexts.
instrumentation/spring/spring-cloud-aws-3.0/javaagent/build.gradle.kts Adds messaging-preview test tasks.
instrumentation/aws-sdk/aws-sdk-2.2/testing/src/main/java/.../AbstractAws2SqsTracingTest.java Expands SDK 2 SQS assertions.
instrumentation/aws-sdk/aws-sdk-2.2/testing/src/main/java/.../AbstractAws2SqsSuppressReceiveSpansTest.java Tests suppressed receive-span behavior.
instrumentation/aws-sdk/aws-sdk-2.2/testing/src/main/java/.../AbstractAws2SqsBaseTest.java Adds shared stable assertions and cleanup.
instrumentation/aws-sdk/aws-sdk-2.2/testing/src/main/java/.../AbstractAws2ClientTest.java Updates send telemetry expectations.
instrumentation/aws-sdk/aws-sdk-2.2/library/src/test/java/.../SqsParentContextTest.java Tests context extraction and fallback.
instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/.../TracingList.java Stores the process parent context.
instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/.../TracingIterator.java Starts process spans from revised context.
instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/.../SqsParentContext.java Revises propagation and X-Ray fallback.
instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/.../SqsMessageImpl.java Implements creation-context extraction.
instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/.../SqsMessage.java Exposes message creation context.
instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/.../SqsImpl.java Selects stable parents and batch counts.
instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/.../SqsAttributesGetter.java Reports stable batch counts.
instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/.../SqsAccess.java Bridges batch-count access.
instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/.../AwsSdkInstrumenterFactory.java Builds v1.43 SQS instrumenters and links.
instrumentation/aws-sdk/aws-sdk-2.2/library/build.gradle.kts Adds library preview tests.
instrumentation/aws-sdk/aws-sdk-2.2/javaagent/build.gradle.kts Adds agent preview configurations.
instrumentation/aws-sdk/aws-sdk-1.11/testing/src/main/java/.../AbstractSqsTracingTest.java Expands SDK 1 SQS assertions.
instrumentation/aws-sdk/aws-sdk-1.11/testing/src/main/java/.../AbstractSqsSuppressReceiveSpansTest.java Tests suppressed receive telemetry.
instrumentation/aws-sdk/aws-sdk-1.11/library/src/test/java/.../SqsParentContextTest.java Tests parent-value preservation.
instrumentation/aws-sdk/aws-sdk-1.11/library/src/main/java/.../TracingRequestHandler.java Routes preview batch sends to messaging telemetry.
instrumentation/aws-sdk/aws-sdk-1.11/library/src/main/java/.../TracingList.java Stores the process parent context.
instrumentation/aws-sdk/aws-sdk-1.11/library/src/main/java/.../TracingIterator.java Applies creation contexts to processing.
instrumentation/aws-sdk/aws-sdk-1.11/library/src/main/java/.../SqsParentContext.java Preserves parent values during X-Ray extraction.
instrumentation/aws-sdk/aws-sdk-1.11/library/src/main/java/.../SqsMessageImpl.java Supplies message creation contexts.
instrumentation/aws-sdk/aws-sdk-1.11/library/src/main/java/.../SqsMessage.java Adds the creation-context contract.
instrumentation/aws-sdk/aws-sdk-1.11/library/src/main/java/.../SqsImpl.java Selects stable parents and batch counts.
instrumentation/aws-sdk/aws-sdk-1.11/library/src/main/java/.../SqsAttributesGetter.java Reports stable batch counts.
instrumentation/aws-sdk/aws-sdk-1.11/library/src/main/java/.../SqsAccess.java Bridges batch-count access.
instrumentation/aws-sdk/aws-sdk-1.11/library/src/main/java/.../AwsSdkInstrumenterFactory.java Builds v1.43 SQS instrumenters and links.
instrumentation/aws-sdk/aws-sdk-1.11/library/build.gradle.kts Adds library preview tests.
instrumentation/aws-sdk/aws-sdk-1.11/javaagent/build.gradle.kts Adds agent preview configurations.
.github/scripts/instrumentations.sh Registers preview instrumentation tests.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 35 out of 35 changed files in this pull request and generated no new comments.

@trask
trask marked this pull request as ready for review August 5, 2026 23:40
@trask
trask requested a review from a team as a code owner August 5, 2026 23:40
@trask
trask force-pushed the trask/messaging-v1-43-aws branch from 4e4c016 to e9688d7 Compare August 5, 2026 23:40
trask and others added 12 commits August 6, 2026 07:42
The X-Ray fallback in SqsParentContext was meant to kick in when the
message carries no propagation headers. Comparing the extracted context
against the current context is not enough to detect that, because the
current context can already carry an ambient span - in that case the
extracted context is the ambient one and the fallback was skipped even
though the message had no context of its own.

Compare span contexts instead, and only fall back to the X-Ray system
attribute when extraction did not produce a new span.

Also assert the messaging attributes on the stable receive and process
spans, and adapt the call sites to the create/builder overloads.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 61998545-3856-4623-a7cb-4ebc5346c921
…parent

Mirror the shared MessagingProcessInstrumenterFactory change: the SQS process
span skipped the creation-context link whenever there was no ambient span,
which is exactly the case where MessagingProcessContextCustomizer makes the
creation context the parent. Semconv v1.43 asks for a link to the creation
context for every message the span accounts for, so drop the
ambient-validity guard and keep only the trace id / span id comparison.

Also add testBothSemconv to aws-sdk-1.11, aws-sdk-2.2 and spring-cloud-aws-3.0
so dual emit is exercised, and split the messaging.operation assertions that
assumed the old and new attributes are mutually exclusive.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 3db492fb-401c-4e9e-8fff-a7c9e89c5f3b
The SQS `testMessagingPreview` / `testBothSemconv` tasks in the two library
modules only ran four hand-picked test methods, because the shared abstract SQS
test classes still hardcoded old messaging semconv (old span names, the old
`messaging.operation` attribute, old span kinds, and `hasTotalRecordedLinks(0)`).

Migrate those assertions to dual mode and widen both filters to `*Sqs*`. Under
the stable semconv the process span is parented to the message creation context
when there is no ambient span, which moves it (and its children) into the
publish trace, so the affected tests now build their trace assertions
conditionally.

Also add `testMessagingPreview` / `testBothSemconv` (plus the receive-spans
variants) to both javaagent modules, which had no messaging preview coverage at
all.

`AbstractAws2SqsBaseTest` gains an `@AfterEach` queue purge: the newly enabled
`testBatchSendMessageCount` leaves three messages in the shared queue, which
poisons subsequent tests.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 3db492fb-401c-4e9e-8fff-a7c9e89c5f3b
The parent-span test asserted receive and process span attributes with the
non-exact matcher, which was hiding twelve attributes. Reuse the existing
assertReceiveSpan/assertProcessSpan helpers instead.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5d6a6d06-2e10-41b5-8343-ad7dcb1a0dc8
The operation name is now a required argument, and SQS names its API operations SendMessage / ReceiveMessage, so 'send' is a better fit than the legacy 'publish'.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 41b6b4a0-35a4-40b3-a1f7-4437c556f298
Annotate the nullable aws-sdk-2.2 getBatchMessageCount methods, matching their aws-sdk-1.11 counterparts.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 41b6b4a0-35a4-40b3-a1f7-4437c556f298
The SQS process span links extractor guarded the link with a trace-id/span-id
comparison against the ambient parent, mirroring the guard in
MessagingProcessInstrumenterFactory. Here the comparison can never be true:
SqsMessageImpl.getCreationContext() delegates to SqsParentContext.ofMessage,
which extracts against Context.root(), so the creation context is either a valid
producer span or an invalid one and can never pick up the ambient span. isValid()
already does all the work.

Also drop the @nullable annotations this stack added to the SQS test helpers,
which are test code.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 80fcee33-cb85-420e-a857-d9de3a8d2b31
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: e6d66343-527c-48c3-aac6-7df226bf768d
Under the javaagent the SqsClient used by the purgeQueue @AfterEach is
instrumented, so the purge itself produces spans. Clear the exported data
after purging so nothing leaks into the next test.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 77fc86e1-293e-44ce-b6af-ec959329afc1
Extract against a context with the ambient span removed, so a span in the
extracted context is known to have come from the message. Previously the
extracted span was compared against the ambient span, which misclassified a
message whose creation context happened to equal the ambient span as having
no creation context, letting the X-Ray fallback replace it.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 77fc86e1-293e-44ce-b6af-ec959329afc1
InstrumentationExtension.beforeEach already clears all exported data
before every test, so clearing again in the @AfterEach purge adds
nothing.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@trask
trask force-pushed the trask/messaging-v1-43-aws branch from 26e3cb2 to e488f42 Compare August 6, 2026 14:42
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@trask
trask merged commit aa2d26f into main Aug 7, 2026
100 checks passed
@trask
trask deleted the trask/messaging-v1-43-aws branch August 7, 2026 05:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants