Add DynamoDB attributes that uniquely identify sanitized queries/writes, similar to db.statement

[swar8080]

Suggestion overview

When an application runs the same CRUD statements with different inputs it's helpful to aggregate statistics at the statement-level. This is possible in most databases with the db.statement attribute, which can have values like SELECT foo FROM bar WHERE baz=? LIMIT ? and UPDATE foo SET bar=?. This attribute allows quickly answering questions like:

• Which statements are slowest?
• Which statements are failing?
• Which statements are most frequent?
• Which statements are costing the most money (when cost is based on usage like with DynamoDB)?

Those questions take more work to answer with the conventional DynamoDB attributes, since it's not possible to map a span/metric to a specific DynamoDB statement that an application makes

DynamoDB doesn't have a query language like SQL, but there's of course some similarities like:

• Querys have filter conditions similar to a WHERE clause
• PutItem/DeleteItem/UpdateItem have conditional expressions, like a WHERE clause
• UpdateItem has a SQL-like update expression like SET myNum = myNum + :val

Th suggestion is a new span and/or metric attribute that is a SQL-like representation of a DynamoDB Query, UpdateItem, PutItem, or DeleteItem request. The attribute's format would need to be intuitive to read and include sanitized information about all request parameters that change the statement's outcome

Examples

Query API

• AttributesToGet/ProjectionExpression could be represented as the fields in SELECT [Projection]
• TableName/IndexName could be represented as FROM [TableName].[IndexName]
• KeyConditionExpression/Filter could be represented as WHERE clauses
• ScanIndexForward flag could be represented as ORDER BY DESC/ASC
• Limit could be represented as a limit

UpdateItem API:

• TableName represented as UPDATE [TableName]
• UpdateExpression represented as SET [UpdateExpression]
• Key/ConditionalOperator/ConditionExpression represented as a WHERE clause

DeleteItem API:

• TableName represented as DELETE FROM [TableName]
• Key/ConditionalOperator/ConditionExpression represented as a WHERE clause

PutItem API:

• TableName represented as INSERT INTO [TableName]
• ConditionalOperator/ConditionExpression represented as WHERE clauses

Contributing

Let me know if this makes sense as a convention, if it's better off as a custom/third-party library, or if you have suggestions for a different approach

I'd be interested in proposing more exact mappings of API requests to attribute values if that would be useful

[trask]

hi @swar8080!

I think this would indeed be useful:

I'd be interested in proposing more exact mappings of API requests to attribute values if that would be useful

btw, we are working toward database semantic convention stability and many things have changed recently so it's worth revisiting the latest changes to the semconv

[trask]

@jcocchi would be interesting to get your perspective given your work on CosmosDB semantic conventions

[jcocchi]

@swar8080, @trask - I agree adding context about the operation to the span is useful!

For Cosmos DB we capture the API name in the db.operation.name attribute rather than converting it to a SQL syntax. Table name (called container for us) is in the db.collection.name. For queries specifically, we also have a SQL-like query syntax which we plan to add to the db.query.text attribute (we don't currently populate this). This would include SQL representations of your KeyConditionExpression, ScanIndexForward, and Limit examples. We don't plan to create SQL syntax for non-query operations.

For non-queries, there may be other attributes to capture for a given request similar to your ConditionalOperator examples. In Cosmos DB we'd be interested in capturing the PartitionKey and Id of the item for example. It makes sense to have custom attributes per implementation for these database specific attributes.