# Semantic Conventions for Microsoft Cosmos DB **Status**: [Experimental][DocumentStatus] The Semantic Conventions for [Microsoft Cosmos DB](https://azure.microsoft.com/products/cosmos-db/) extend and override the [Database Semantic Conventions](database-spans.md) that describe common database operations attributes in addition to the Semantic Conventions described on this page. ## Attributes `db.system` MUST be set to `"cosmosdb"`. Cosmos DB instrumentation includes call-level (public API) surface spans and network spans. Depending on the connection mode (Gateway or Direct), network-level spans may also be created. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.collection.name`](../attributes-registry/db.md) | string | Cosmos DB container name. [1] | `public.users`; `customers` | `Conditionally Required` if available |  | | [`db.cosmosdb.connection_mode`](../attributes-registry/db.md) | string | Cosmos client connection mode. | `gateway` | `Conditionally Required` if not `direct` (or pick gw as default) |  | | [`db.cosmosdb.operation_type`](../attributes-registry/db.md) | string | CosmosDB Operation Type. | `Invalid` | `Conditionally Required` [2] |  | | [`db.cosmosdb.request_charge`](../attributes-registry/db.md) | double | RU consumed for that operation | `46.18`; `1.0` | `Conditionally Required` when available |  | | [`db.cosmosdb.status_code`](../attributes-registry/db.md) | int | Cosmos DB status code. | `200`; `201` | `Conditionally Required` if response was received |  | | [`db.cosmosdb.sub_status_code`](../attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` [3] |  | | [`db.cosmosdb.client_id`](../attributes-registry/db.md) | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | `Recommended` |  | | [`db.cosmosdb.request_content_length`](../attributes-registry/db.md) | int | Request payload size in bytes | | `Recommended` |  | | [`user_agent.original`](../attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [4] | `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` |  | **[1]:** If the collection name is parsed from the query, it SHOULD match the value provided in the query and may be qualified with the schema and database name. **[2]:** when performing one of the operations in this list **[3]:** when response was received and contained sub-code. **[4]:** 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". `db.cosmosdb.connection_mode` MUST be one of the following: | Value | Description | Stability | |---|---|---| | `gateway` | Gateway (HTTP) connections mode |  | | `direct` | Direct connection. |  | `db.cosmosdb.operation_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 | |---|---|---| | `Invalid` | invalid |  | | `Create` | create |  | | `Patch` | patch |  | | `Read` | read |  | | `ReadFeed` | read_feed |  | | `Delete` | delete |  | | `Replace` | replace |  | | `Execute` | execute |  | | `Query` | query |  | | `Head` | head |  | | `HeadFeed` | head_feed |  | | `Upsert` | upsert |  | | `Batch` | batch |  | | `QueryPlan` | query_plan |  | | `ExecuteJavaScript` | execute_javascript |  | In addition to Cosmos DB attributes, all spans include `az.namespace` attribute representing Azure Resource Provider namespace that MUST be equal to `Microsoft.DocumentDB`. ## Example | Key | Value | |:-------------------------------------| :------------------- | | Span name | `"ReadItemsAsync"` | | `kind` | `"internal"` | | `az.namespace` | `"Microsoft.DocumentDB"` | | `db.system` | `"cosmosdb"` | | `db.name` | `"database name"` | | `db.operation.name` | `"ReadItemsAsync"` | | `server.address` | `"account.documents.azure.com"` | | `db.cosmosdb.client_id` | `3ba4827d-4422-483f-b59f-85b74211c11d` | | `db.cosmosdb.operation_type` | `Read` | | `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\|` | | `db.cosmosdb.connection_mode` | `"Direct"` | | `db.cosmosdb.container` | `"container name"` | | `db.cosmosdb.request_content_length` | `20` | | `db.cosmosdb.status_code` | `201` | | `db.cosmosdb.sub_status_code` | `0` | | `db.cosmosdb.request_charge` | `7.43` | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md