Semantic conventions for AWS SDK¶
NOTICE Semantic Conventions are moving to a new location.
No changes to this document are allowed.
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.
Context Propagation¶
See compatibility.
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.
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
aws.request_id |
string | The AWS request ID as returned in the response headers x-amz-request-id or x-amz-requestid. |
79b9da39-b7ae-508a-a6bc-864b2829c622; C9ER4AJX75574TDJ |
Recommended |
rpc.method |
string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | GetItem; PutItem |
Recommended |
rpc.service |
string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | DynamoDB; S3 |
Recommended |
rpc.system |
string | The value aws-api. |
aws-api |
Required |
[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.
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
db.system |
string | The value dynamodb. |
dynamodb |
Required |
DynamoDB.BatchGetItem¶
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
aws.dynamodb.consumed_capacity |
string[] | The JSON-serialized value of each item in the ConsumedCapacity response field. |
[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }] |
Recommended |
aws.dynamodb.table_names |
string[] | The keys in the RequestItems object field. |
[Users, Cats] |
Recommended |
DynamoDB.BatchWriteItem¶
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
aws.dynamodb.consumed_capacity |
string[] | The JSON-serialized value of each item in the ConsumedCapacity response field. |
[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }] |
Recommended |
aws.dynamodb.item_collection_metrics |
string | The JSON-serialized value of the ItemCollectionMetrics response field. |
{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] } |
Recommended |
aws.dynamodb.table_names |
string[] | The keys in the RequestItems object field. |
[Users, Cats] |
Recommended |
DynamoDB.CreateTable¶
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
aws.dynamodb.global_secondary_indexes |
string[] | The JSON-serialized value of each item of the GlobalSecondaryIndexes request field |
[{ "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }] |
Recommended |
aws.dynamodb.local_secondary_indexes |
string[] | The JSON-serialized value of each item of the LocalSecondaryIndexes request field. |
[{ "IndexArn": "string", "IndexName": "string", "IndexSizeBytes": number, "ItemCount": number, "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" } }] |
Recommended |
aws.dynamodb.consumed_capacity |
string[] | The JSON-serialized value of each item in the ConsumedCapacity response field. |
[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }] |
Recommended |
aws.dynamodb.item_collection_metrics |
string | The JSON-serialized value of the ItemCollectionMetrics response field. |
{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] } |
Recommended |
aws.dynamodb.provisioned_read_capacity |
double | The value of the ProvisionedThroughput.ReadCapacityUnits request parameter. |
1.0; 2.0 |
Recommended |
aws.dynamodb.provisioned_write_capacity |
double | The value of the ProvisionedThroughput.WriteCapacityUnits request parameter. |
1.0; 2.0 |
Recommended |
aws.dynamodb.table_names |
string[] | A single-element array with the value of the TableName request parameter. | [Users] |
Recommended |
DynamoDB.DeleteItem¶
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
aws.dynamodb.consumed_capacity |
string[] | The JSON-serialized value of each item in the ConsumedCapacity response field. |
[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }] |
Recommended |
aws.dynamodb.item_collection_metrics |
string | The JSON-serialized value of the ItemCollectionMetrics response field. |
{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] } |
Recommended |
aws.dynamodb.table_names |
string[] | A single-element array with the value of the TableName request parameter. | [Users] |
Recommended |
DynamoDB.DeleteTable¶
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
aws.dynamodb.table_names |
string[] | A single-element array with the value of the TableName request parameter. | [Users] |
Recommended |
DynamoDB.DescribeTable¶
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
aws.dynamodb.table_names |
string[] | A single-element array with the value of the TableName request parameter. | [Users] |
Recommended |
DynamoDB.GetItem¶
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
aws.dynamodb.consistent_read |
boolean | The value of the ConsistentRead request parameter. |
Recommended | |
aws.dynamodb.consumed_capacity |
string[] | The JSON-serialized value of each item in the ConsumedCapacity response field. |
[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }] |
Recommended |
aws.dynamodb.projection |
string | The value of the ProjectionExpression request parameter. |
Title; Title, Price, Color; Title, Description, RelatedItems, ProductReviews |
Recommended |
aws.dynamodb.table_names |
string[] | A single-element array with the value of the TableName request parameter. | [Users] |
Recommended |
DynamoDB.ListTables¶
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
aws.dynamodb.exclusive_start_table |
string | The value of the ExclusiveStartTableName request parameter. |
Users; CatsTable |
Recommended |
aws.dynamodb.table_count |
int | The the number of items in the TableNames response parameter. |
20 |
Recommended |
aws.dynamodb.limit |
int | The value of the Limit request parameter. |
10 |
Recommended |
DynamoDB.PutItem¶
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
aws.dynamodb.consumed_capacity |
string[] | The JSON-serialized value of each item in the ConsumedCapacity response field. |
[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }] |
Recommended |
aws.dynamodb.item_collection_metrics |
string | The JSON-serialized value of the ItemCollectionMetrics response field. |
{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] } |
Recommended |
aws.dynamodb.table_names |
string[] | The keys in the RequestItems object field. |
[Users, Cats] |
Recommended |
DynamoDB.Query¶
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
aws.dynamodb.scan_forward |
boolean | The value of the ScanIndexForward request parameter. |
Recommended | |
aws.dynamodb.attributes_to_get |
string[] | The value of the AttributesToGet request parameter. |
[lives, id] |
Recommended |
aws.dynamodb.consistent_read |
boolean | The value of the ConsistentRead request parameter. |
Recommended | |
aws.dynamodb.consumed_capacity |
string[] | The JSON-serialized value of each item in the ConsumedCapacity response field. |
[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }] |
Recommended |
aws.dynamodb.index_name |
string | The value of the IndexName request parameter. |
name_to_group |
Recommended |
aws.dynamodb.limit |
int | The value of the Limit request parameter. |
10 |
Recommended |
aws.dynamodb.projection |
string | The value of the ProjectionExpression request parameter. |
Title; Title, Price, Color; Title, Description, RelatedItems, ProductReviews |
Recommended |
aws.dynamodb.select |
string | The value of the Select request parameter. |
ALL_ATTRIBUTES; COUNT |
Recommended |
aws.dynamodb.table_names |
string[] | A single-element array with the value of the TableName request parameter. | [Users] |
Recommended |
DynamoDB.Scan¶
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
aws.dynamodb.segment |
int | The value of the Segment request parameter. |
10 |
Recommended |
aws.dynamodb.total_segments |
int | The value of the TotalSegments request parameter. |
100 |
Recommended |
aws.dynamodb.count |
int | The value of the Count response parameter. |
10 |
Recommended |
aws.dynamodb.scanned_count |
int | The value of the ScannedCount response parameter. |
50 |
Recommended |
aws.dynamodb.attributes_to_get |
string[] | The value of the AttributesToGet request parameter. |
[lives, id] |
Recommended |
aws.dynamodb.consistent_read |
boolean | The value of the ConsistentRead request parameter. |
Recommended | |
aws.dynamodb.consumed_capacity |
string[] | The JSON-serialized value of each item in the ConsumedCapacity response field. |
[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }] |
Recommended |
aws.dynamodb.index_name |
string | The value of the IndexName request parameter. |
name_to_group |
Recommended |
aws.dynamodb.limit |
int | The value of the Limit request parameter. |
10 |
Recommended |
aws.dynamodb.projection |
string | The value of the ProjectionExpression request parameter. |
Title; Title, Price, Color; Title, Description, RelatedItems, ProductReviews |
Recommended |
aws.dynamodb.select |
string | The value of the Select request parameter. |
ALL_ATTRIBUTES; COUNT |
Recommended |
aws.dynamodb.table_names |
string[] | A single-element array with the value of the TableName request parameter. | [Users] |
Recommended |
DynamoDB.UpdateItem¶
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
aws.dynamodb.consumed_capacity |
string[] | The JSON-serialized value of each item in the ConsumedCapacity response field. |
[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }] |
Recommended |
aws.dynamodb.item_collection_metrics |
string | The JSON-serialized value of the ItemCollectionMetrics response field. |
{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] } |
Recommended |
aws.dynamodb.table_names |
string[] | A single-element array with the value of the TableName request parameter. | [Users] |
Recommended |
DynamoDB.UpdateTable¶
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
aws.dynamodb.attribute_definitions |
string[] | The JSON-serialized value of each item in the AttributeDefinitions request field. |
[{ "AttributeName": "string", "AttributeType": "string" }] |
Recommended |
aws.dynamodb.global_secondary_index_updates |
string[] | The JSON-serialized value of each item in the the GlobalSecondaryIndexUpdates request field. |
[{ "Create": { "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }] |
Recommended |
aws.dynamodb.consumed_capacity |
string[] | The JSON-serialized value of each item in the ConsumedCapacity response field. |
[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }] |
Recommended |
aws.dynamodb.provisioned_read_capacity |
double | The value of the ProvisionedThroughput.ReadCapacityUnits request parameter. |
1.0; 2.0 |
Recommended |
aws.dynamodb.provisioned_write_capacity |
double | The value of the ProvisionedThroughput.WriteCapacityUnits request parameter. |
1.0; 2.0 |
Recommended |
aws.dynamodb.table_names |
string[] | A single-element array with the value of the TableName request parameter. | [Users] |
Recommended |
S3¶
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
aws.s3.bucket |
string | The S3 bucket name the request refers to. Corresponds to the --bucket parameter of the S3 API operations. [1] |
some-bucket-name |
Recommended |
aws.s3.key |
string | The S3 object key the request refers to. Corresponds to the --key parameter of the S3 API operations. [2] |
someFile.yml |
Recommended |
aws.s3.copy_source |
string | The source object (in the form bucket/key) for the copy operation. [3] |
someFile.yml |
Recommended |
aws.s3.upload_id |
string | Upload ID that identifies the multipart upload. [4] | dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ |
Recommended |
aws.s3.delete |
string | The delete request container that specifies the objects to be deleted. [5] | Objects=[{Key=string,VersionId=string},{Key=string,VersionId=string}],Quiet=boolean |
Recommended |
aws.s3.part_number |
int | The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000. [6] | 3456 |
Recommended |
[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:
[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:
[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.