# Semantic conventions for Microsoft Azure Cosmos DB client operations **Status**: [Development][DocumentStatus] - [Spans](#spans) - [Example](#example) - [Metrics](#metrics) - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) - [Metric: `db.client.response.returned_rows`](#metric-dbclientresponsereturned_rows) - [Metric: `azure.cosmosdb.client.operation.request_charge`](#metric-azurecosmosdbclientoperationrequest_charge) - [Metric: `azure.cosmosdb.client.active_instance.count`](#metric-azurecosmosdbclientactive_instancecount) The Semantic Conventions for [Microsoft Cosmos DB](https://azure.microsoft.com/products/cosmos-db/) extend and override the [Database Semantic Conventions](README.md). ## Spans **Status:**  Cosmos DB instrumentations include call-level spans that represent logical database calls and adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). Additional spans representing network calls may also be created depending on the connection mode (Gateway or Direct). Semantic conventions described in this document apply to the call-level spans only. `db.system.name` MUST be set to `"azure.cosmosdb"` and SHOULD be provided **at span creation time**. **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) **Span kind** SHOULD be `CLIENT`. **Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.operation.name`](/docs/registry/attributes/db.md) | string | The name of the operation or command being executed. [1] | `create_item`; `query_items`; `read_item` | `Required` |  | | [`azure.cosmosdb.connection.mode`](/docs/registry/attributes/azure.md) | string | Cosmos client connection mode. | `gateway`; `direct` | `Conditionally Required` [2] |  | | [`azure.cosmosdb.consistency.level`](/docs/registry/attributes/azure.md) | string | Account or request [consistency level](https://learn.microsoft.com/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong`; `Session` | `Conditionally Required` If available. |  | | [`azure.cosmosdb.operation.contacted_regions`](/docs/registry/attributes/azure.md) | string[] | List of regions contacted during operation in the order that they were contacted. If there is more than one region listed, it indicates that the operation was performed on multiple regions i.e. cross-regional call. [3] | `["North Central US", "Australia East", "Australia Southeast"]` | `Conditionally Required` If available. |  | | [`azure.cosmosdb.operation.request_charge`](/docs/registry/attributes/azure.md) | double | The number of request units consumed by the operation. | `46.18`; `1.0` | `Conditionally Required` when available |  | | [`azure.cosmosdb.response.sub_status_code`](/docs/registry/attributes/azure.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` when response was received and contained sub-code. |  | | [`db.collection.name`](/docs/registry/attributes/db.md) | string | Cosmos DB container name. [4] | `public.users`; `customers` | `Conditionally Required` if available |  | | [`db.namespace`](/docs/registry/attributes/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. |  | | [`db.response.returned_rows`](/docs/registry/attributes/db.md) | int | Cosmos DB row count in result set. | `10`; `20` | `Conditionally Required` if response was received and returned any rows |  | | [`db.response.status_code`](/docs/registry/attributes/db.md) | string | Cosmos DB status code. [5] | `200`; `201` | `Conditionally Required` if response was received |  | | [`error.type`](/docs/registry/attributes/error.md) | string | Describes a class of error the operation ended with. [6] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. |  | | [`server.port`](/docs/registry/attributes/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Conditionally Required` If not default (443). |  | | [`azure.client.id`](/docs/registry/attributes/azure.md) | string | The unique identifier of the client instance. | `3ba4827d-4422-483f-b59f-85b74211c11d`; `storage-client-1` | `Recommended` |  | | [`azure.cosmosdb.request.body.size`](/docs/registry/attributes/azure.md) | int | Request payload size in bytes. | | `Recommended` |  | | [`azure.resource_provider.namespace`](/docs/registry/attributes/azure.md) | string | [Azure Resource Provider Namespace](https://learn.microsoft.com/azure/azure-resource-manager/management/azure-services-resource-providers) as recognized by the client. [8] | `Microsoft.DocumentDB` | `Recommended` |  | | [`db.operation.batch.size`](/docs/registry/attributes/db.md) | int | The number of queries included in a batch operation. [9] | `2`; `3`; `4` | `Recommended` |  | | [`db.query.text`](/docs/registry/attributes/db.md) | string | The database query being executed. [10] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` |  | | [`db.stored_procedure.name`](/docs/registry/attributes/db.md) | string | The name of a stored procedure within the database. [11] | `GetCustomer` | `Recommended` [12] |  | | [`server.address`](/docs/registry/attributes/server.md) | string | Name of the database host. [13] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  | | [`user_agent.original`](/docs/registry/attributes/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [14] | `cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|` | `Recommended` |  | | [`db.query.parameter.`](/docs/registry/attributes/db.md) | string | A database query parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [15] | `someval`; `55` | `Opt-In` |  | **[1] `db.operation.name`:** The `db.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used. Batch operations: - `execute_batch` Bulk operations: - `execute_bulk` SHOULD be used on spans reported for methods like [`executeBulkOperations`](https://javadoc.io/doc/com.azure/azure-cosmos/latest/com/azure/cosmos/CosmosAsyncContainer.html#executeBulkOperations)). which represents a bulk execution of multiple operations. - `bulk_{operation name}` (`bulk_create_item`, `bulk_upsert_item`, etc) SHOULD be used on spans describing individual operations (when they are reported) within the bulk. This pattern SHOULD be used when instrumentation creates span per each operation, but operations are buffered and then performed in bulk. For example, this applies when [`AllowBulkExecution`](https://learn.microsoft.com/dotnet/api/microsoft.azure.cosmos.cosmosclientoptions.allowbulkexecution) property is configured on the `Microsoft.Azure.Cosmos` client. Change feed operations: - `query_change_feed` Conflicts operations: - `delete_conflict` - `query_conflicts` - `read_all_conflicts` - `read_conflict` Container operations: - `create_container` - `create_container_if_not_exists` - `delete_container` - `query_containers` - `read_all_containers` - `read_container` - `read_container_throughput` - `replace_container` - `replace_container_throughput` Database operations: - `create_database` - `create_database_if_not_exists` - `delete_database` - `query_databases` - `read_all_databases` - `read_database` - `read_database_throughput` - `replace_database_throughput` Encryption key operations: - `create_client_encryption_key` - `query_client_encryption_keys` - `read_all_client_encryption_keys` - `read_client_encryption_key` - `replace_client_encryption_key` Item operations: - `create_item` - `delete_all_items_by_partition_key` - `delete_item` - `patch_item` - `query_items` - `read_all_items` - `read_all_items_of_logical_partition` - `read_many_items` - `read_item` - `replace_item` - `upsert_item` Permission operations: - `create_permission` - `delete_permission` - `query_permissions` - `read_all_permissions` - `read_permission` - `replace_permission` - `upsert_permission` Stored procedure operations: - `create_stored_procedure` - `delete_stored_procedure` - `execute_stored_procedure` - `query_stored_procedures` - `read_all_stored_procedures` - `read_stored_procedure` - `replace_stored_procedure` Trigger operations: - `create_trigger` - `delete_trigger` - `query_triggers` - `read_all_triggers` - `read_trigger` - `replace_trigger` User operations: - `create_user` - `delete_user` - `query_users` - `read_all_users` - `read_user` - `replace_user` - `upsert_user` User-defined function operations: - `create_user_defined_function` - `delete_user_defined_function` - `query_user_defined_functions` - `read_all_user_defined_functions` - `read_user_defined_function` If none of them applies, it's RECOMMENDED to use language-agnostic representation of client method name in snake_case. Instrumentations SHOULD document additional values when introducing new operations. **[2] `azure.cosmosdb.connection.mode`:** if not `gateway` (the default value is assumed to be `gateway`). **[3] `azure.cosmosdb.operation.contacted_regions`:** Region name matches the format of `displayName` in [Azure Location API](https://learn.microsoft.com/rest/api/subscription/subscriptions/list-locations?view=rest-subscription-2021-10-01&tabs=HTTP#location) **[4] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. **[5] `db.response.status_code`:** Response codes in the 4xx and 5xx range SHOULD be considered errors. **[6] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. Instrumentations SHOULD document how `error.type` is populated. **[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[8] `azure.resource_provider.namespace`:** When `azure.resource_provider.namespace` attribute is populated, it MUST be set to `Microsoft.DocumentDB` for all operations performed by Cosmos DB client. **[9] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. **[10] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. Parameterized query text SHOULD NOT be sanitized. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. **[11] `db.stored_procedure.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. For batch operations, if the individual operations are known to have the same stored procedure name then that stored procedure name SHOULD be used. **[12] `db.stored_procedure.name`:** If operation applies to a specific stored procedure. **[13] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. **[14] `user_agent.original`:** The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled. Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it). Default value is "NS". **[15] `db.query.parameter.`:** If a query parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. `db.query.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. `db.query.parameter.` SHOULD NOT be captured on batch operations. Examples: - For a query `SELECT * FROM users where username = %s` with the parameter `"jdoe"`, the attribute `db.query.parameter.0` SHOULD be set to `"jdoe"`. - For a query `"SELECT * FROM users WHERE username = %(username)s;` with parameter `username = "jdoe"`, the attribute `db.query.parameter.username` SHOULD be set to `"jdoe"`. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`db.collection.name`](/docs/registry/attributes/db.md) * [`db.namespace`](/docs/registry/attributes/db.md) * [`db.operation.name`](/docs/registry/attributes/db.md) * [`server.address`](/docs/registry/attributes/server.md) * [`server.port`](/docs/registry/attributes/server.md) --- `azure.cosmosdb.connection.mode` 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 | |---|---|---| | `direct` | Direct connection. |  | | `gateway` | Gateway (HTTP) connection. |  | --- `azure.cosmosdb.consistency.level` 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 | |---|---|---| | `BoundedStaleness` | bounded_staleness |  | | `ConsistentPrefix` | consistent_prefix |  | | `Eventual` | eventual |  | | `Session` | session |  | | `Strong` | strong |  | --- `error.type` 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 | |---|---|---| | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  | ### Example | Key | Value | |:-------------------------------------| :------------------- | | Span name | `"read_item orders"` | | `azure.client.id` | `"3ba4827d-4422-483f-b59f-85b74211c11d"` | | `azure.cosmosdb.operation.request_charge` | `7.43` | | `azure.cosmosdb.request.body.size` | `20` | | `azure.cosmosdb.response.sub_status_code` | `0` | | `azure.resource_provider.namespace` | `"Microsoft.DocumentDB"` | | `db.system.name` | `"azure.cosmosdb"` | | `db.collection.name` | `"orders"` | | `db.namespace` | `"ShopDb"` | | `db.operation.name` | `"read_item"` | | `db.response.status_code` | `201` | | `server.address` | `"account.documents.azure.com"` | | `user_agent.original` | `"cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|"` | ## Metrics The following metrics provide insights into Azure Cosmos DB client operation performance and behavior. ### Metric: `db.client.operation.duration` This metric is [required][MetricRequired]. It captures the total time taken by an Azure Cosmos DB operation. This metric follows the common [db.client.operation.duration](/docs/database/database-metrics.md#metric-dbclientoperationduration) definition. Refer [azure.cosmosdb.client.operation.request_charge](#metric-azurecosmosdbclientoperationrequest_charge) metrics for dimensions. ### Metric: `db.client.response.returned_rows` This metric is [required][MetricRequired]. It captures the number of items returned by a query or feed operation in Azure Cosmos DB. It helps identify response sizes that may contribute to high latency, increased memory/CPU usage, or network call failures. This metric follows the common [`db.client.response.returned_rows`](/docs/database/database-metrics.md#metric-dbclientresponsereturned_rows) definition. Refer [azure.cosmosdb.client.operation.request_charge](#metric-azurecosmosdbclientoperationrequest_charge) metrics for dimensions. ### Metric: `azure.cosmosdb.client.operation.request_charge` This metric is [required][MetricRequired]. It captures the Request Units consumed by each operation in Azure Cosmos DB. Since Request Units serve as a form of throughput control within the Azure Cosmos DB database, monitoring their usage is crucial to avoid throttling. this metric SHOULD be specified with [`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.46.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 1, 5, 10, 25, 50, 100, 250, 500, 1000]`. Explaining bucket configuration: 1. 1, 5, 10: Low Usage Levels, These smaller buckets allow for precise tracking of operations that consume a minimal number of Request Units. This is important for lightweight operations, such as basic read requests or small queries, where resource utilization should be optimized. Monitoring these low usage levels can help ensure that the application is not inadvertently using more resources than necessary. 2. 25, 50: Moderate Usage Levels, These ranges capture more moderate operations, which are typical in many applications. For example, queries that return a reasonable amount of data or perform standard CRUD operations may fall within these limits. Identifying usage patterns in these buckets can help detect efficiency issues in routine operations. 3. 100, 250: Higher Usage Levels, These boundaries represent operations that may require significant resources, such as complex queries or larger transactions. Monitoring RUs in these ranges can help identify performance bottlenecks or costly queries that might lead to throttling. 4. 500, 1000: Very High Usage Levels, These buckets capture operations that consume a substantial number of Request Units, which may indicate potentially expensive queries or batch processes. Understanding the frequency and patterns of such high RU usage can be critical in optimizing performance and ensuring the application remains within provisioned throughput limits. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `azure.cosmosdb.client.operation.request_charge` | Histogram | `{request_unit}` | [Request units](https://learn.microsoft.com/azure/cosmos-db/request-units) consumed by the operation |  | | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.operation.name`](/docs/registry/attributes/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` |  | | [`azure.cosmosdb.consistency.level`](/docs/registry/attributes/azure.md) | string | Account or request [consistency level](https://learn.microsoft.com/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong`; `Session` | `Conditionally Required` If available. |  | | [`azure.cosmosdb.response.sub_status_code`](/docs/registry/attributes/azure.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` when response was received and contained sub-code. |  | | [`db.collection.name`](/docs/registry/attributes/db.md) | string | Cosmos DB container name. [2] | `public.users`; `customers` | `Conditionally Required` If available. |  | | [`db.namespace`](/docs/registry/attributes/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. |  | | [`db.response.status_code`](/docs/registry/attributes/db.md) | string | Database response status code. [3] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [4] |  | | [`error.type`](/docs/registry/attributes/error.md) | string | Describes a class of error the operation ended with. [5] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. |  | | [`server.port`](/docs/registry/attributes/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Conditionally Required` [7] |  | | [`azure.cosmosdb.operation.contacted_regions`](/docs/registry/attributes/azure.md) | string[] | List of regions contacted during operation in the order that they were contacted. If there is more than one region listed, it indicates that the operation was performed on multiple regions i.e. cross-regional call. [8] | `["North Central US", "Australia East", "Australia Southeast"]` | `Recommended` If available |  | | [`server.address`](/docs/registry/attributes/server.md) | string | Name of the database host. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  | **[1] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. The operation name SHOULD NOT be extracted from `db.query.text`, when the database system supports query text with multiple operations in non-batch operations. If spaces can occur in the operation name, multiple consecutive spaces SHOULD be normalized to a single space. For batch operations, if the individual operations are known to have the same operation name then that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. **[2] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. **[3] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. **[4] `db.response.status_code`:** If the operation failed and status code is available. **[5] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. Instrumentations SHOULD document how `error.type` is populated. **[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[7] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. **[8] `azure.cosmosdb.operation.contacted_regions`:** Region name matches the format of `displayName` in [Azure Location API](https://learn.microsoft.com/rest/api/subscription/subscriptions/list-locations?view=rest-subscription-2021-10-01&tabs=HTTP#location) **[9] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. --- `azure.cosmosdb.consistency.level` 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 | |---|---|---| | `BoundedStaleness` | bounded_staleness |  | | `ConsistentPrefix` | consistent_prefix |  | | `Eventual` | eventual |  | | `Session` | session |  | | `Strong` | strong |  | --- `error.type` 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 | |---|---|---| | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  | ### Metric: `azure.cosmosdb.client.active_instance.count` This metric is [required][MetricRequired]. It captures the number of active instances at any given time. Best practices dictate that there should ideally be only one instance of the SDK client per Azure Cosmos DB account. Having multiple instances of the SDK client for the same account in a single process can lead to CPU or memory-related issues. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `azure.cosmosdb.client.active_instance.count` | UpDownCounter | `{instance}` | Number of active client instances |  | | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`server.port`](/docs/registry/attributes/server.md) | int | Server port number. [1] | `80`; `8080`; `443` | `Conditionally Required` [2] |  | | [`server.address`](/docs/registry/attributes/server.md) | string | Name of the database host. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  | **[1] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[2] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. **[3] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status [MetricRequired]: /docs/general/metric-requirement-level.md#required