From c3056eb454d6a5759e1ce55a8932e9fcf7e4ff86 Mon Sep 17 00:00:00 2001 From: Luke Zhang Date: Sun, 15 Jun 2025 17:52:17 -0700 Subject: [PATCH 1/4] feat: Add AWS_SNS_TOPIC_ARN semantic convention support for AWS SNS SDK This PR adds the AWS_SNS_TOPIC_ARN semantic convention attribute for the following AWS resources: AWS SNS SDK The topic ARN is extracted from both request and response objects, and this behavior is covered by unit tests. Tests Run: npm run compile npm run lint npm run test All newly added tests pass, and no regressions were found. Backward Compatibility: This change is fully backward compatible. It introduces instrumentation for an additional AWS resource without modifying existing behavior in the auto-instrumentation library. --- package-lock.json | 4 +- .../package.json | 2 +- .../src/semconv.ts | 3 + .../src/services/sns.ts | 13 +++- .../test/mock-responses/sns-create-topic.xml | 9 +++ .../test/sns.test.ts | 70 ++++++++++++++----- 6 files changed, 81 insertions(+), 20 deletions(-) create mode 100644 plugins/node/opentelemetry-instrumentation-aws-sdk/test/mock-responses/sns-create-topic.xml diff --git a/package-lock.json b/package-lock.json index 72da5233c0..145e605fb8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -32913,7 +32913,7 @@ "@opentelemetry/core": "^2.0.0", "@opentelemetry/instrumentation": "^0.202.0", "@opentelemetry/propagation-utils": "^0.31.2", - "@opentelemetry/semantic-conventions": "^1.31.0" + "@opentelemetry/semantic-conventions": "^1.34.0" }, "devDependencies": { "@aws-sdk/client-bedrock-runtime": "^3.587.0", @@ -40281,7 +40281,7 @@ "@opentelemetry/instrumentation": "^0.202.0", "@opentelemetry/propagation-utils": "^0.31.2", "@opentelemetry/sdk-trace-base": "^2.0.0", - "@opentelemetry/semantic-conventions": "^1.31.0", + "@opentelemetry/semantic-conventions": "^1.34.0", "@smithy/node-http-handler": "2.4.0", "@types/mocha": "10.0.10", "@types/node": "18.18.14", diff --git a/plugins/node/opentelemetry-instrumentation-aws-sdk/package.json b/plugins/node/opentelemetry-instrumentation-aws-sdk/package.json index ba1a8b2d9a..b4384655e8 100644 --- a/plugins/node/opentelemetry-instrumentation-aws-sdk/package.json +++ b/plugins/node/opentelemetry-instrumentation-aws-sdk/package.json @@ -47,7 +47,7 @@ "@opentelemetry/core": "^2.0.0", "@opentelemetry/instrumentation": "^0.202.0", "@opentelemetry/propagation-utils": "^0.31.2", - "@opentelemetry/semantic-conventions": "^1.31.0" + "@opentelemetry/semantic-conventions": "^1.34.0" }, "devDependencies": { "@aws-sdk/client-bedrock-runtime": "^3.587.0", diff --git a/plugins/node/opentelemetry-instrumentation-aws-sdk/src/semconv.ts b/plugins/node/opentelemetry-instrumentation-aws-sdk/src/semconv.ts index 9bb050c040..eec986b826 100644 --- a/plugins/node/opentelemetry-instrumentation-aws-sdk/src/semconv.ts +++ b/plugins/node/opentelemetry-instrumentation-aws-sdk/src/semconv.ts @@ -158,3 +158,6 @@ export const GEN_AI_TOKEN_TYPE_VALUE_INPUT = 'input' as const; * Enum value "output" for attribute {@link ATTR_GEN_AI_TOKEN_TYPE}. */ export const GEN_AI_TOKEN_TYPE_VALUE_OUTPUT = 'output' as const; + +// Copied ATTR_AWS_SNS_TOPIC_ARN from '@opentelemetry/semantic-conventions/incubating' +export const ATTR_AWS_SNS_TOPIC_ARN = 'aws.sns.topic.arn' as const; diff --git a/plugins/node/opentelemetry-instrumentation-aws-sdk/src/services/sns.ts b/plugins/node/opentelemetry-instrumentation-aws-sdk/src/services/sns.ts index f6f6182253..0c8302aba7 100644 --- a/plugins/node/opentelemetry-instrumentation-aws-sdk/src/services/sns.ts +++ b/plugins/node/opentelemetry-instrumentation-aws-sdk/src/services/sns.ts @@ -20,6 +20,7 @@ import { SEMATTRS_MESSAGING_DESTINATION_KIND, SEMATTRS_MESSAGING_SYSTEM, } from '@opentelemetry/semantic-conventions'; +import { ATTR_AWS_SNS_TOPIC_ARN } from '../semconv'; import { NormalizedRequest, NormalizedResponse, @@ -58,6 +59,11 @@ export class SnsServiceExtension implements ServiceExtension { } send`; } + const topicArn = request.commandInput?.TopicArn; + if (topicArn) { + spanAttributes[ATTR_AWS_SNS_TOPIC_ARN] = topicArn; + } + return { isIncoming: false, spanAttributes, @@ -83,7 +89,12 @@ export class SnsServiceExtension implements ServiceExtension { span: Span, tracer: Tracer, config: AwsSdkInstrumentationConfig - ): void {} + ): void { + const topicArn = response.data?.TopicArn; + if (topicArn) { + span.setAttribute(ATTR_AWS_SNS_TOPIC_ARN, topicArn); + } + } extractDestinationName( topicArn: string, diff --git a/plugins/node/opentelemetry-instrumentation-aws-sdk/test/mock-responses/sns-create-topic.xml b/plugins/node/opentelemetry-instrumentation-aws-sdk/test/mock-responses/sns-create-topic.xml new file mode 100644 index 0000000000..d9f3d0ae82 --- /dev/null +++ b/plugins/node/opentelemetry-instrumentation-aws-sdk/test/mock-responses/sns-create-topic.xml @@ -0,0 +1,9 @@ + + + + arn:aws:sns:us-east-1:123456789012:sns-topic-foo + + + d74b8436-ae13-5ab4-a9ff-ce54dfea72a0 + + \ No newline at end of file diff --git a/plugins/node/opentelemetry-instrumentation-aws-sdk/test/sns.test.ts b/plugins/node/opentelemetry-instrumentation-aws-sdk/test/sns.test.ts index 64d9e9cab6..b01b0eb4a5 100644 --- a/plugins/node/opentelemetry-instrumentation-aws-sdk/test/sns.test.ts +++ b/plugins/node/opentelemetry-instrumentation-aws-sdk/test/sns.test.ts @@ -27,28 +27,30 @@ import { SEMATTRS_MESSAGING_SYSTEM, SEMATTRS_RPC_METHOD, } from '@opentelemetry/semantic-conventions'; +import { ATTR_AWS_SNS_TOPIC_ARN } from '@opentelemetry/semantic-conventions/incubating'; import { SpanKind } from '@opentelemetry/api'; describe('SNS - v3', () => { let sns: any; - beforeEach(() => { - sns = new SNSv3({ - region: 'us-east-1', - credentials: { - accessKeyId: 'abcde', - secretAccessKey: 'abcde', - }, - }); - - nock('https://sns.us-east-1.amazonaws.com/') - .post('/') - .reply( - 200, - fs.readFileSync('./test/mock-responses/sns-publish.xml', 'utf8') - ); - }); describe('publish', () => { + beforeEach(() => { + sns = new SNSv3({ + region: 'us-east-1', + credentials: { + accessKeyId: 'abcde', + secretAccessKey: 'abcde', + }, + }); + + nock('https://sns.us-east-1.amazonaws.com/') + .post('/') + .reply( + 200, + fs.readFileSync('./test/mock-responses/sns-publish.xml', 'utf8') + ); + }); + it('topic arn', async () => { const topicV3Name = 'dummy-sns-v3-topic'; const topicV3ARN = `arn:aws:sns:us-east-1:000000000:${topicV3Name}`; @@ -73,6 +75,7 @@ describe('SNS - v3', () => { expect(publishSpan.attributes['messaging.destination.name']).toBe( topicV3ARN ); + expect(publishSpan.attributes[ATTR_AWS_SNS_TOPIC_ARN]).toBe(topicV3ARN); expect(publishSpan.attributes[SEMATTRS_RPC_METHOD]).toBe('Publish'); expect(publishSpan.attributes[SEMATTRS_MESSAGING_SYSTEM]).toBe('aws.sns'); expect(publishSpan.kind).toBe(SpanKind.PRODUCER); @@ -93,6 +96,41 @@ describe('SNS - v3', () => { expect(publishSpan.attributes[SEMATTRS_MESSAGING_DESTINATION]).toBe( PhoneNumber ); + expect(publishSpan.attributes[ATTR_AWS_SNS_TOPIC_ARN]).toBeUndefined(); + }); + }); + + describe('Create Topic', () => { + beforeEach(() => { + sns = new SNSv3({ + region: 'us-east-1', + credentials: { + accessKeyId: 'abcde', + secretAccessKey: 'abcde', + }, + }); + + nock('https://sns.us-east-1.amazonaws.com/') + .post('/') + .reply( + 200, + fs.readFileSync('./test/mock-responses/sns-create-topic.xml', 'utf8') + ); + }); + + it('topic arn', async () => { + const topicName = 'sns-topic-foo'; + const topicArn = `arn:aws:sns:us-east-1:123456789012:${topicName}`; + await sns.createTopic({ + Name: topicName, + }); + const publishSpans = getTestSpans().filter( + (s: ReadableSpan) => s.name === 'SNS CreateTopic' + ); + expect(publishSpans.length).toBe(1); + const publishSpan = publishSpans[0]; + expect(publishSpan.attributes[ATTR_AWS_SNS_TOPIC_ARN]).toBe(topicArn); + expect(publishSpan.kind).toBe(SpanKind.CLIENT); }); }); }); From 696bbb7154be2df1cfc3617f91eedfbbd55e0606 Mon Sep 17 00:00:00 2001 From: Luke Zhang Date: Tue, 24 Jun 2025 21:31:59 -0700 Subject: [PATCH 2/4] address code review feedback. update unit test description. --- .../node/opentelemetry-instrumentation-aws-sdk/test/sns.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/node/opentelemetry-instrumentation-aws-sdk/test/sns.test.ts b/plugins/node/opentelemetry-instrumentation-aws-sdk/test/sns.test.ts index b01b0eb4a5..d8c48c699e 100644 --- a/plugins/node/opentelemetry-instrumentation-aws-sdk/test/sns.test.ts +++ b/plugins/node/opentelemetry-instrumentation-aws-sdk/test/sns.test.ts @@ -118,7 +118,7 @@ describe('SNS - v3', () => { ); }); - it('topic arn', async () => { + it('should create topic ARN and capture expected trace attributes', async () => { const topicName = 'sns-topic-foo'; const topicArn = `arn:aws:sns:us-east-1:123456789012:${topicName}`; await sns.createTopic({ From bab4cfade6f5afa858bc3a5d5ca8c99d2a53321d Mon Sep 17 00:00:00 2001 From: Luke Zhang Date: Thu, 3 Jul 2025 14:06:48 -0700 Subject: [PATCH 3/4] address code review feedback. --- .../opentelemetry-instrumentation-aws-sdk/src/semconv.ts | 9 ++++++++- .../test/sns.test.ts | 6 +++--- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/plugins/node/opentelemetry-instrumentation-aws-sdk/src/semconv.ts b/plugins/node/opentelemetry-instrumentation-aws-sdk/src/semconv.ts index eec986b826..baf772142d 100644 --- a/plugins/node/opentelemetry-instrumentation-aws-sdk/src/semconv.ts +++ b/plugins/node/opentelemetry-instrumentation-aws-sdk/src/semconv.ts @@ -159,5 +159,12 @@ export const GEN_AI_TOKEN_TYPE_VALUE_INPUT = 'input' as const; */ export const GEN_AI_TOKEN_TYPE_VALUE_OUTPUT = 'output' as const; -// Copied ATTR_AWS_SNS_TOPIC_ARN from '@opentelemetry/semantic-conventions/incubating' +/** + * Originally from '@opentelemetry/semantic-conventions/incubating' + * https://github.com/open-telemetry/semantic-conventions/blob/main/docs/registry/attributes/aws.md#amazon-sns-attributes + * The ARN of the AWS SNS Topic. An Amazon SNS [topic](https://docs.aws.amazon.com/sns/latest/dg/sns-create-topic.html) + * is a logical access point that acts as a communication channel. + * @example arn:aws:sns:us-east-1:123456789012:mystack-mytopic-NZJ5JSMVGFIE + * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`. + */ export const ATTR_AWS_SNS_TOPIC_ARN = 'aws.sns.topic.arn' as const; diff --git a/plugins/node/opentelemetry-instrumentation-aws-sdk/test/sns.test.ts b/plugins/node/opentelemetry-instrumentation-aws-sdk/test/sns.test.ts index d8c48c699e..25f59f7523 100644 --- a/plugins/node/opentelemetry-instrumentation-aws-sdk/test/sns.test.ts +++ b/plugins/node/opentelemetry-instrumentation-aws-sdk/test/sns.test.ts @@ -124,11 +124,11 @@ describe('SNS - v3', () => { await sns.createTopic({ Name: topicName, }); - const publishSpans = getTestSpans().filter( + const createTopicSpans = getTestSpans().filter( (s: ReadableSpan) => s.name === 'SNS CreateTopic' ); - expect(publishSpans.length).toBe(1); - const publishSpan = publishSpans[0]; + expect(createTopicSpans.length).toBe(1); + const publishSpan = createTopicSpans[0]; expect(publishSpan.attributes[ATTR_AWS_SNS_TOPIC_ARN]).toBe(topicArn); expect(publishSpan.kind).toBe(SpanKind.CLIENT); }); From 3665bc92db6e634220a94a109e0134226b274c45 Mon Sep 17 00:00:00 2001 From: Luke Zhang Date: Thu, 3 Jul 2025 14:14:10 -0700 Subject: [PATCH 4/4] fix variable naming issue. --- .../opentelemetry-instrumentation-aws-sdk/test/sns.test.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/node/opentelemetry-instrumentation-aws-sdk/test/sns.test.ts b/plugins/node/opentelemetry-instrumentation-aws-sdk/test/sns.test.ts index 25f59f7523..9ded8b7396 100644 --- a/plugins/node/opentelemetry-instrumentation-aws-sdk/test/sns.test.ts +++ b/plugins/node/opentelemetry-instrumentation-aws-sdk/test/sns.test.ts @@ -128,9 +128,9 @@ describe('SNS - v3', () => { (s: ReadableSpan) => s.name === 'SNS CreateTopic' ); expect(createTopicSpans.length).toBe(1); - const publishSpan = createTopicSpans[0]; - expect(publishSpan.attributes[ATTR_AWS_SNS_TOPIC_ARN]).toBe(topicArn); - expect(publishSpan.kind).toBe(SpanKind.CLIENT); + const span = createTopicSpans[0]; + expect(span.attributes[ATTR_AWS_SNS_TOPIC_ARN]).toBe(topicArn); + expect(span.kind).toBe(SpanKind.CLIENT); }); }); });