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.

AttributeTypeDescriptionExamplesRequired
rpc.methodstringThe name of the operation corresponding to the request, as returned by the AWS SDK [1]GetItem; PutItemNo
rpc.servicestringThe name of the service to which a request is made, as returned by the AWS SDK. [2]DynamoDB; S3No
rpc.systemstringThe value aws-api.aws-apiYes

[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.

AttributeTypeDescriptionExamplesRequired
db.systemstringThe value dynamodb.dynamodbYes

DynamoDB.BatchGetItem

AttributeTypeDescriptionExamplesRequired
aws.dynamodb.consumed_capacitystring[]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 }]No
aws.dynamodb.table_namesstring[]The keys in the RequestItems object field.[Users, Cats]No

DynamoDB.BatchWriteItem

AttributeTypeDescriptionExamplesRequired
aws.dynamodb.consumed_capacitystring[]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 }]No
aws.dynamodb.item_collection_metricsstringThe 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 ] } ] }No
aws.dynamodb.table_namesstring[]The keys in the RequestItems object field.[Users, Cats]No

DynamoDB.CreateTable

AttributeTypeDescriptionExamplesRequired
aws.dynamodb.global_secondary_indexesstring[]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 } }]No
aws.dynamodb.local_secondary_indexesstring[]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" } }]No
aws.dynamodb.consumed_capacitystring[]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 }]No
aws.dynamodb.item_collection_metricsstringThe 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 ] } ] }No
aws.dynamodb.provisioned_read_capacitydoubleThe value of the ProvisionedThroughput.ReadCapacityUnits request parameter.1.0; 2.0No
aws.dynamodb.provisioned_write_capacitydoubleThe value of the ProvisionedThroughput.WriteCapacityUnits request parameter.1.0; 2.0No
aws.dynamodb.table_namesstring[]A single-element array with the value of the TableName request parameter.[Users]No

DynamoDB.DeleteItem

AttributeTypeDescriptionExamplesRequired
aws.dynamodb.consumed_capacitystring[]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 }]No
aws.dynamodb.item_collection_metricsstringThe 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 ] } ] }No
aws.dynamodb.table_namesstring[]A single-element array with the value of the TableName request parameter.[Users]No

DynamoDB.DeleteTable

AttributeTypeDescriptionExamplesRequired
aws.dynamodb.table_namesstring[]A single-element array with the value of the TableName request parameter.[Users]No

DynamoDB.DescribeTable

AttributeTypeDescriptionExamplesRequired
aws.dynamodb.table_namesstring[]A single-element array with the value of the TableName request parameter.[Users]No

DynamoDB.GetItem

AttributeTypeDescriptionExamplesRequired
aws.dynamodb.consistent_readbooleanThe value of the ConsistentRead request parameter.No
aws.dynamodb.consumed_capacitystring[]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 }]No
aws.dynamodb.projectionstringThe value of the ProjectionExpression request parameter.Title; Title, Price, Color; Title, Description, RelatedItems, ProductReviewsNo
aws.dynamodb.table_namesstring[]A single-element array with the value of the TableName request parameter.[Users]No

DynamoDB.ListTables

AttributeTypeDescriptionExamplesRequired
aws.dynamodb.exclusive_start_tablestringThe value of the ExclusiveStartTableName request parameter.Users; CatsTableNo
aws.dynamodb.table_countintThe the number of items in the TableNames response parameter.20No
aws.dynamodb.limitintThe value of the Limit request parameter.10No

DynamoDB.PutItem

AttributeTypeDescriptionExamplesRequired
aws.dynamodb.consumed_capacitystring[]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 }]No
aws.dynamodb.item_collection_metricsstringThe 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 ] } ] }No
aws.dynamodb.table_namesstring[]The keys in the RequestItems object field.[Users, Cats]No

DynamoDB.Query

AttributeTypeDescriptionExamplesRequired
aws.dynamodb.scan_forwardbooleanThe value of the ScanIndexForward request parameter.No
aws.dynamodb.attributes_to_getstring[]The value of the AttributesToGet request parameter.[lives, id]No
aws.dynamodb.consistent_readbooleanThe value of the ConsistentRead request parameter.No
aws.dynamodb.consumed_capacitystring[]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 }]No
aws.dynamodb.index_namestringThe value of the IndexName request parameter.name_to_groupNo
aws.dynamodb.limitintThe value of the Limit request parameter.10No
aws.dynamodb.projectionstringThe value of the ProjectionExpression request parameter.Title; Title, Price, Color; Title, Description, RelatedItems, ProductReviewsNo
aws.dynamodb.selectstringThe value of the Select request parameter.ALL_ATTRIBUTES; COUNTNo
aws.dynamodb.table_namesstring[]A single-element array with the value of the TableName request parameter.[Users]No

DynamoDB.Scan

AttributeTypeDescriptionExamplesRequired
aws.dynamodb.segmentintThe value of the Segment request parameter.10No
aws.dynamodb.total_segmentsintThe value of the TotalSegments request parameter.100No
aws.dynamodb.countintThe value of the Count response parameter.10No
aws.dynamodb.scanned_countintThe value of the ScannedCount response parameter.50No
aws.dynamodb.attributes_to_getstring[]The value of the AttributesToGet request parameter.[lives, id]No
aws.dynamodb.consistent_readbooleanThe value of the ConsistentRead request parameter.No
aws.dynamodb.consumed_capacitystring[]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 }]No
aws.dynamodb.index_namestringThe value of the IndexName request parameter.name_to_groupNo
aws.dynamodb.limitintThe value of the Limit request parameter.10No
aws.dynamodb.projectionstringThe value of the ProjectionExpression request parameter.Title; Title, Price, Color; Title, Description, RelatedItems, ProductReviewsNo
aws.dynamodb.selectstringThe value of the Select request parameter.ALL_ATTRIBUTES; COUNTNo
aws.dynamodb.table_namesstring[]A single-element array with the value of the TableName request parameter.[Users]No

DynamoDB.UpdateItem

AttributeTypeDescriptionExamplesRequired
aws.dynamodb.consumed_capacitystring[]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 }]No
aws.dynamodb.item_collection_metricsstringThe 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 ] } ] }No
aws.dynamodb.table_namesstring[]A single-element array with the value of the TableName request parameter.[Users]No

DynamoDB.UpdateTable

AttributeTypeDescriptionExamplesRequired
aws.dynamodb.attribute_definitionsstring[]The JSON-serialized value of each item in the AttributeDefinitions request field.[{ "AttributeName": "string", "AttributeType": "string" }]No
aws.dynamodb.global_secondary_index_updatesstring[]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 } }]No
aws.dynamodb.consumed_capacitystring[]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 }]No
aws.dynamodb.provisioned_read_capacitydoubleThe value of the ProvisionedThroughput.ReadCapacityUnits request parameter.1.0; 2.0No
aws.dynamodb.provisioned_write_capacitydoubleThe value of the ProvisionedThroughput.WriteCapacityUnits request parameter.1.0; 2.0No
aws.dynamodb.table_namesstring[]A single-element array with the value of the TableName request parameter.[Users]No