Add AWS resource ARN tags to AWS SDK client spans

[pedramsafaei]

What Does This Do

Tags AWS SDK v1 and v2 client spans with the complete resource identity that is already present in the request, instead of only the short name:

Service	Request field	New span tags	Existing tag kept
SNS	TopicArn / TargetArn	aws.topic.arn, aws.sns.topic_arn	aws.topic.name, topicname
Kinesis	StreamARN	aws.stream.arn	aws.stream.name, streamname
Step Functions	stateMachineArn	aws.state_machine.arn, statemachinearn	–
Step Functions	executionArn	aws.execution.arn	–
Lambda	FunctionName	aws.function.name, functionname	–

No additional network calls are made; every value is read from the request object the instrumentation already inspects. Existing tags, peer.service derivation and Data Streams Monitoring behaviour are unchanged. Nothing is added when the request does not carry the field.

The plain-name variants (aws.sns.topic_arn, statemachinearn, functionname) are the tags dd-trace-py and dd-trace-js already emit for the same calls, so one query now works across the three tracers.

Implementation:

• internal-api: new constants in InstrumentationTags.
• aws-java-sdk-2.2: AwsSdkClientDecorator.onSdkRequest reads the fields via SdkRequest.getValueForField. getValueForField matches the API model's member name verbatim, and the Step Functions model declares its members in lowerCamelCase (unlike SNS TopicArn or DynamoDB TableName), so those two fields are read as stateMachineArn and executionArn.
• aws-java-sdk-1.11: GetterAccess gains getStateMachineArn, getExecutionArn and getFunctionName method handles, resolved the same way as the existing getTableName; AwsSdkClientDecorator.onRequest uses them. The SNS and Kinesis branches tag the ARN they already read.

Motivation

peer.service and the *name tags identify which topic, stream, state machine or function a span talks to, but not whose. Two accounts can each own a payments state machine or a notifications topic, and the short name is ambiguous the moment a service crosses an account or Region boundary. The ARN removes that ambiguity and carries partition, Region and account with it.

This matters for anyone building account-aware dependency maps or joining APM spans with the AWS integration metrics (which are tagged by ARN-derived dimensions), and for cross-account debugging where the short name alone does not say which resource was hit. The tracer already had the ARN in hand for SNS, Kinesis and Step Functions and was discarding it.

The Java tracer was also the odd one out: the Python and JS tracers already emit aws.sns.topic_arn and statemachinearn, and Java emitted neither.

Additional Notes

Testing

Unit and instrumentation tests, all green locally on this branch:

• aws-java-sdk-2.2: test (41 + 41 across the V0/V1 forks), LegacyAws2ClientForkedTest (23), dsmTest (14). New rows for Step Functions StartExecution / DescribeExecution and Lambda Invoke; SNS rows now assert both ARN tags; the Kinesis DSM tests assert aws.stream.arn.
• aws-java-sdk-1.11: test (25), forkedTest (25 + 17). Same new rows; the test_before_1_11_106 configuration pins aws-java-sdk-core to 1.11.0 because aws-java-sdk-stepfunctions (a new test dependency) only exists from 1.11.63 and would otherwise pull a newer core than the pinned clients.
• spotlessApply clean on the touched modules.

How the end-to-end test was run

• Environment: an EKS cluster (managed node group, EC2 nodes) running the Datadog Helm chart with the node Agent's trace receiver; a real DynamoDB table, Kinesis stream, SNS topic, Step Functions state machine, Lambda function, S3 bucket and RDS for PostgreSQL instance in the same account; IRSA credentials on the workload's service account.
• Workload: a small Java 21 application (AWS SDK for Java v2 2.29.52, PostgreSQL JDBC 42.7.4) that once per cycle calls SNS Publish, Kinesis PutRecord, Step Functions StartExecution + DescribeExecution, Lambda Invoke, DynamoDB GetItem (by name and by ARN), S3 GetObject and a JDBC SELECT 1, all inside one traced method so the client spans share a trace.
• Two deployments of the same container image, differing only in the dd-java-agent.jar copied into it: the released 1.66.0 tracer (before) and the jar built from this branch with ./gradlew :dd-java-agent:shadowJar (after). Same node pool, same DD_ENV, distinct DD_VERSION so the two runs are separable in Span Search.
• Verification: the Datadog Span Search API (/api/v2/spans/events/search) was queried for each run's client spans and the per-span attributes compared key by key; the raw responses are retained. Where the change enables a join to the AWS integration metrics, the corresponding /api/v1/query was run against the same org and the returned scope recorded.

Live before/after on a real EKS workload

A Java 21 workload using AWS SDK v2 (sns, kinesis, sfn, lambda, dynamodb) was run on an EKS cluster under IRSA, once with the stock dd-java-agent 1.66.0 and once with the jar built from this branch (dcb9e6a20c), same image, same node pool, same fixtures. Client spans as returned by the Span Search API (account masked):

Sns.Publish
  before: aws.topic.name=datadog-context-trace-fixture  topicname=datadog-context-trace-fixture
  after : + aws.topic.arn=arn:aws:sns:us-east-1:123456789012:datadog-context-trace-fixture
          + aws.sns.topic_arn=arn:aws:sns:us-east-1:123456789012:datadog-context-trace-fixture

Kinesis.PutRecord
  before: aws.stream.name=DatadogContextTraceFixture-FixtureStream-aiWeiLPpX1jU
  after : + aws.stream.arn=arn:aws:kinesis:us-east-1:123456789012:stream/DatadogContextTraceFixture-FixtureStream-aiWeiLPpX1jU

Sfn.StartExecution
  before: (no resource tags; peer.hostname=states.us-east-1.amazonaws.com only)
  after : + aws.state_machine.arn=arn:aws:states:us-east-1:123456789012:stateMachine:datadog-context-trace-fixture
          + statemachinearn=arn:aws:states:us-east-1:123456789012:stateMachine:datadog-context-trace-fixture

Sfn.DescribeExecution
  before: (no resource tags)
  after : + aws.execution.arn=arn:aws:states:us-east-1:123456789012:execution:datadog-context-trace-fixture:965b1f0d-...

Lambda.Invoke
  before: (no resource tags)
  after : + aws.function.name=datadog-context-normal-fixture
          + functionname=datadog-context-normal-fixture

DynamoDb.GetItem
  before == after (aws.table.name / tablename unchanged, as expected)

Design notes for reviewers

• Duplicate keys (aws.topic.arn + aws.sns.topic_arn, aws.state_machine.arn + statemachinearn, aws.function.name + functionname) follow the existing convention in this decorator (aws.topic.name + topicname, aws.stream.name + streamname). The namespaced key matches Java's own style; the plain key matches the other tracers. Happy to drop either half if you would rather not carry both.
• Lambda FunctionName may be a name, a partial ARN or a full ARN; it is tagged verbatim. The SDK v1 decorator only reads getFunctionName when the service is AWSLambda, and the v2 decorator when the service name is lambda, so unrelated request types with a FunctionName member are not affected.
• Kinesis StreamARN was already read for Data Streams Monitoring; this only additionally sets it on the span, so DSM pathway keys are unchanged (the existing DSM tests still pass with the added tag).
• EventBridge PutEvents was considered but its bus identity lives inside each entry (EventBusName per PutEventsRequestEntry), not on the request, so it is left for a follow-up if there is interest.

Contributor Checklist

• Format the title according to the contribution guidelines
• Assign the type: and (comp: or inst:) labels in addition to any other useful labels — suggested inst: aws sdk, type: feature (external contributor, cannot set labels)
• Avoid using close, fix, or any linking keywords when referencing an issue
• Update the CODEOWNERS file on source file addition, migration, or deletion — no files added or moved
• Update public documentation with any new configuration flags or behaviors — no new configuration; new tags only
• Once approved, use merge queue to merge the PR

Suggested labels (cannot set as an external contributor): inst: aws sdk, type: feature.

[mhlidd]

LGTM from an SDK Capabilities POV

[ygree]

Should we skip v1 since it was EOLed?

[ygree]

https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-aws-sdk-for-java-v1-x-on-december-31-2025/

[pedramsafaei]

I would like to keep at least part of v1 if you are open to it. v1 is EOL from AWS but the tracer still ships and tests this instrumentation, and the users still on it are the ones most likely to have cross-account SNS topics where the bare name is ambiguous. The SNS and Kinesis half of the v1 change is a few lines with no new dependencies and the decorator already reads the ARN and discards it. The Step Functions and Lambda half is what pulled in the stepfunctions test dependency and the core pin, so if the concern is that surface I am happy to drop those two from v1 and keep SNS and Kinesis. But anyways if the team's stance is absolutely no new features on v1 at all, tell me and I will drop v1 entirely here and in #12602.

[ygree]

Why do we need to check both camelCase and PascalCase? Isn't the model generator supposed to normalize them to PascalCase?

[pedramsafaei]

The generator does not normalize the member name so getValueForField is generated as an equals chain against the model's member name verbatim. Step Functions' API model defines its members in lowerCamelCase, so sfn's StartExecutionRequest.getValueForField matches "stateMachineArn" (checked in 2.2.0 and 2.15.35), whereas SNS matches "TopicArn" and DynamoDB "TableName". Querying "StateMachineArn" returns empty on sfn, which is why the lowerCamel spelling is there. You are right that probing both is unnecessary though, since the member name comes from the API model and does not vary by SDK version. I will drop the stringField helper and query "stateMachineArn" / "executionArn" directly with a comment on the casing.

[pedramsafaei]

Done. stringField is gone, the two fields are read directly as stateMachineArn / executionArn with a comment on why the casing differs from SNS and DynamoDB.

[ygree]

From a functional perspective, the change looks good, but the code footprint can be reduced by removing unnecessary parts, see details in the comments.

[ygree]

Should these three two-line methods, which were only used once, be inlined instead?

[pedramsafaei]

Yes, agreed. Inlined all three as each had exactly one call site. Left setStreamName and setQueueName as methods since they have two callers each.

[ygree]

IDM approved. There are no blockers, but the code change footprint could likely be reduced.