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.
| Attribute | Type | Description | Examples | Requirement Level |
|---|
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 |