Semantic conventions for AWS S3 client spans

Status: Development

Status:

Semantic Conventions for AWS S3 client spans extend the general AWS SDK Semantic Conventions

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.

AWS SDK span attributes are based on the request or response parameters in AWS SDK API calls. 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.

Span kind SHOULD be CLIENT.

Span status SHOULD follow the Recording Errors document.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
rpc.system	Replaced by rpc.system.name.	Required	string	The value aws-api.	aws-api (see more)
aws.extended_request_id		Conditionally Required If available.	string	The AWS extended request ID as returned in the response header x-amz-id-2.	wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=
aws.request_id		Recommended	string	The AWS request ID as returned in the response headers x-amzn-requestid, x-amzn-request-id or x-amz-request-id.	79b9da39-b7ae-508a-a6bc-864b2829c622; C9ER4AJX75574TDJ
aws.s3.bucket		Recommended	string	The S3 bucket name the request refers to. Corresponds to the --bucket parameter of the S3 API operations. [1]	some-bucket-name
aws.s3.copy_source		Recommended	string	The source object (in the form bucket/key) for the copy operation. [2]	someFile.yml
aws.s3.delete		Recommended	string	The delete request container that specifies the objects to be deleted. [3]	Objects=[{Key=string,VersionId=string},{Key=string,VersionId=string}],Quiet=boolean
aws.s3.key		Recommended	string	The S3 object key the request refers to. Corresponds to the --key parameter of the S3 API operations. [4]	someFile.yml
aws.s3.part_number		Recommended	int	The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000. [5]	3456
aws.s3.upload_id		Recommended	string	Upload ID that identifies the multipart upload. [6]	dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ
cloud.region		Recommended	string	The AWS Region where the requested service is being accessed. [7]	us-east-1; us-west-2
rpc.method		Recommended	string	The name of the operation corresponding to the request, as returned by the AWS SDK	GetItem; PutItem
rpc.service	Value should be included in rpc.method which is expected to be a fully-qualified name.	Recommended	string	The name of the service to which a request is made, as returned by the AWS SDK.	DynamoDB; S3

[1] aws.s3.bucket: 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] aws.s3.copy_source: 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

[3] aws.s3.delete: 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.

[4] aws.s3.key: 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

[5] aws.s3.part_number: 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.

[6] aws.s3.upload_id: 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

[7] cloud.region: Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute’s value should adhere to the AWS Region codes outlined in the AWS documentation.

rpc.system has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
apache_dubbo	Apache Dubbo
connect_rpc	Connect RPC
dotnet_wcf	.NET WCF
grpc	gRPC
java_rmi	Java RMI
jsonrpc	JSON-RPC
onc_rpc	ONC RPC (Sun RPC)