feat(instrumentation-aws-sdk): Add semconv attributes for AWS Step Functions

This PR adds the aws.step_functions.activity.arn and aws.step_functions.state_machine.arn semantic convention attributes for the following AWS resources:

AWS Step Functions SDK

The ARNs are extracted from request 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.

Author: lukeina2z

packages/instrumentation-aws-sdk/package.json

@@ -59,6 +59,7 @@
     "@aws-sdk/client-kinesis": "^3.85.0",
     "@aws-sdk/client-lambda": "^3.85.0",
     "@aws-sdk/client-s3": "^3.85.0",
+    "@aws-sdk/client-sfn": "^3.85.0",
     "@aws-sdk/client-sns": "^3.85.0",
     "@aws-sdk/client-sqs": "^3.85.0",
     "@aws-sdk/types": "^3.370.0",

packages/instrumentation-aws-sdk/src/semconv.ts

@@ -168,3 +168,23 @@ export const GEN_AI_TOKEN_TYPE_VALUE_OUTPUT = 'output' as const;
  * @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;
+
+/**
+ * The ARN of the AWS Step Functions Activity.
+ * Originally from '@opentelemetry/semantic-conventions/incubating'
+ * https://github.com/open-telemetry/semantic-conventions/blob/main/docs/registry/attributes/aws.md#amazon-step-functions-attributes
+ * @example arn:aws:states:us-east-1:123456789012:activity:get-greeting
+ * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
+ */
+export const ATTR_AWS_STEP_FUNCTIONS_ACTIVITY_ARN =
+  'aws.step_functions.activity.arn' as const;
+
+/**
+ * The ARN of the AWS Step Functions State Machine.
+ * Originally from '@opentelemetry/semantic-conventions/incubating'
+ * https://github.com/open-telemetry/semantic-conventions/blob/main/docs/registry/attributes/aws.md#amazon-step-functions-attributes
+ * @example arn:aws:states:us-east-1:123456789012:stateMachine:myStateMachine:1
+ * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
+ */
+export const ATTR_AWS_STEP_FUNCTIONS_STATE_MACHINE_ARN =
+  'aws.step_functions.state_machine.arn' as const;

packages/instrumentation-aws-sdk/src/services/ServicesExtensions.ts

@@ -24,6 +24,7 @@ import {
 import { BedrockRuntimeServiceExtension } from './bedrock-runtime';
 import { DynamodbServiceExtension } from './dynamodb';
 import { SnsServiceExtension } from './sns';
+import { StepFunctionsServiceExtension } from './stepfunctions';
 import { LambdaServiceExtension } from './lambda';
 import { S3ServiceExtension } from './s3';
 import { KinesisServiceExtension } from './kinesis';
@@ -32,6 +33,11 @@ export class ServicesExtensions implements ServiceExtension {
   services: Map<string, ServiceExtension> = new Map();
 
   constructor() {
+    this.registerServices();
+  }
+
+  private registerServices() {
+    this.services.set('SFN', new StepFunctionsServiceExtension());
     this.services.set('SQS', new SqsServiceExtension());
     this.services.set('SNS', new SnsServiceExtension());
     this.services.set('DynamoDB', new DynamodbServiceExtension());

packages/instrumentation-aws-sdk/src/services/stepfunctions.ts

@@ -0,0 +1,49 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Attributes, SpanKind } from '@opentelemetry/api';
+import {
+  ATTR_AWS_STEP_FUNCTIONS_ACTIVITY_ARN,
+  ATTR_AWS_STEP_FUNCTIONS_STATE_MACHINE_ARN,
+} from '../semconv';
+import { RequestMetadata, ServiceExtension } from './ServiceExtension';
+import { NormalizedRequest, AwsSdkInstrumentationConfig } from '../types';
+
+export class StepFunctionsServiceExtension implements ServiceExtension {
+  requestPreSpanHook(
+    request: NormalizedRequest,
+    _config: AwsSdkInstrumentationConfig
+  ): RequestMetadata {
+    const stateMachineArn = request.commandInput?.stateMachineArn;
+    const activityArn = request.commandInput?.activityArn;
+    const spanKind: SpanKind = SpanKind.CLIENT;
+    const spanAttributes: Attributes = {};
+
+    if (stateMachineArn) {
+      spanAttributes[ATTR_AWS_STEP_FUNCTIONS_STATE_MACHINE_ARN] =
+        stateMachineArn;
+    }
+
+    if (activityArn) {
+      spanAttributes[ATTR_AWS_STEP_FUNCTIONS_ACTIVITY_ARN] = activityArn;
+    }
+
+    return {
+      isIncoming: false,
+      spanAttributes,
+      spanKind
+    };
+  }
+}

packages/instrumentation-aws-sdk/test/stepfunctions.test.ts

@@ -0,0 +1,114 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { getTestSpans } from '@opentelemetry/contrib-test-utils';
+import { SpanKind } from '@opentelemetry/api';
+import { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import {
+  ATTR_AWS_STEP_FUNCTIONS_ACTIVITY_ARN,
+  ATTR_AWS_STEP_FUNCTIONS_STATE_MACHINE_ARN,
+} from '@opentelemetry/semantic-conventions/incubating';
+
+import { SFN } from '@aws-sdk/client-sfn';
+
+import { expect } from 'expect';
+import * as nock from 'nock';
+
+const region = 'us-east-1';
+
+describe('SFN', () => {
+  let sfn: SFN;
+  beforeEach(() => {
+    sfn = new SFN({
+      region: region,
+      credentials: {
+        accessKeyId: 'abcde',
+        secretAccessKey: 'abcde',
+      },
+    });
+  });
+
+  describe('DescribeStateMachine', () => {
+    it('span has stateMachineArn in its attributes', async () => {
+      const stateMachineArn =
+        'arn:aws:states:us-east-1:123456789123:stateMachine:testStateMachine';
+
+      nock(`https://states.${region}.amazonaws.com/`)
+        .post('/')
+        .reply(200, '{}');
+
+      await sfn
+        .describeStateMachine({
+          stateMachineArn: stateMachineArn,
+        });
+
+      const testSpans: ReadableSpan[] = getTestSpans();
+      const getStateMachineAttributeSpans: ReadableSpan[] = testSpans.filter(
+        (s: ReadableSpan) => {
+          return s.name === 'SFN.DescribeStateMachine';
+        }
+      );
+
+      expect(getStateMachineAttributeSpans.length).toBe(1);
+
+      const stateMachineAttributeSpan = getStateMachineAttributeSpans[0];
+      expect(
+        ATTR_AWS_STEP_FUNCTIONS_STATE_MACHINE_ARN in
+          stateMachineAttributeSpan.attributes
+      ).toBe(true);
+      expect(
+        stateMachineAttributeSpan.attributes[
+          ATTR_AWS_STEP_FUNCTIONS_STATE_MACHINE_ARN
+        ]
+      ).toBe(stateMachineArn);
+      expect(stateMachineAttributeSpan.kind).toBe(SpanKind.CLIENT);
+    });
+  });
+
+  describe('DescribeActivity', () => {
+    it('span has activityArn in its attributes', async () => {
+      const activityArn =
+        'arn:aws:states:us-east-1:123456789123:activity:testActivity';
+
+      nock(`https://states.${region}.amazonaws.com/`)
+        .post('/')
+        .reply(200, '{}');
+
+      await sfn
+        .describeActivity({
+          activityArn: activityArn,
+        });
+
+      const testSpans: ReadableSpan[] = getTestSpans();
+      const getActivityAttributeSpans: ReadableSpan[] = testSpans.filter(
+        (s: ReadableSpan) => {
+          return s.name === 'SFN.DescribeActivity';
+        }
+      );
+
+      expect(getActivityAttributeSpans.length).toBe(1);
+
+      const activityAttributeSpan = getActivityAttributeSpans[0];
+      expect(
+        ATTR_AWS_STEP_FUNCTIONS_ACTIVITY_ARN in activityAttributeSpan.attributes
+      ).toBe(true);
+      expect(
+        activityAttributeSpan.attributes[ATTR_AWS_STEP_FUNCTIONS_ACTIVITY_ARN]
+      ).toBe(activityArn);
+      expect(activityAttributeSpan.kind).toBe(SpanKind.CLIENT);
+    });
+  });
+});