Semantic conventions for AWS SDK

Status: Experimental

This document defines semantic conventions to apply when instrumenting the AWS SDK. They map request or response parameters in AWS SDK API calls to attributes on a Span. The conventions have been collected over time based on feedback from AWS users of tracing and will continue to increase as new interesting conventions are found.

Some descriptions are also provided for populating general OpenTelemetry semantic conventions based on these APIs.

Common Attributes

The span name MUST be of the format Service.Operation as per the AWS HTTP API, e.g., DynamoDB.GetItem, S3.ListBuckets. This is equivalent to concatenating rpc.service and rpc.method with . and consistent with the naming guidelines for RPC client spans.

[1]: This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The code.function attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).

[2]: This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The code.namespace attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).

DynamoDB

Common Attributes

These attributes are filled in for all DynamoDB request types.

DynamoDB.BatchGetItem

DynamoDB.BatchWriteItem

DynamoDB.CreateTable

DynamoDB.DeleteItem

DynamoDB.DeleteTable

DynamoDB.DescribeTable

DynamoDB.GetItem

DynamoDB.ListTables

DynamoDB.PutItem

DynamoDB.Query

DynamoDB.Scan

DynamoDB.UpdateItem

DynamoDB.UpdateTable

S3

[1]: The bucket attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter. This applies to almost all S3 operations except list-buckets.

[2]: The key attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter. This applies in particular to the following operations:

• copy-object
• delete-object
• get-object
• head-object
• put-object
• restore-object
• select-object-content
• abort-multipart-upload
• complete-multipart-upload
• create-multipart-upload
• list-parts
• upload-part
• upload-part-copy

[3]: The copy_source attribute applies to S3 copy operations and corresponds to the --copy-source parameter of the copy-object operation within the S3 API. This applies in particular to the following operations:

• copy-object
• upload-part-copy

[4]: The upload_id attribute applies to S3 multipart-upload operations and corresponds to the --upload-id parameter of the S3 API multipart operations. This applies in particular to the following operations:

• abort-multipart-upload
• complete-multipart-upload
• list-parts
• upload-part
• upload-part-copy

[5]: The delete attribute is only applicable to the delete-object operation. The delete attribute corresponds to the --delete parameter of the delete-objects operation within the S3 API.

[6]: The part_number attribute is only applicable to the upload-part and upload-part-copy operations. The part_number attribute corresponds to the --part-number parameter of the upload-part operation within the S3 API.