# 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. ## Call-level 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 | |---|---|---|---|---| | `db.cosmosdb.client_id` | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | Recommended | | `db.cosmosdb.connection_mode` | string | Cosmos client connection mode. | `gateway` | Conditionally Required: if not `direct` (or pick gw as default) | | `db.cosmosdb.container` | string | Cosmos DB container name. | `anystring` | Conditionally Required: if available | | `db.cosmosdb.operation_type` | string | CosmosDB Operation Type. | `Invalid` | Conditionally Required: [1] | | `db.cosmosdb.request_charge` | double | RU consumed for that operation | `46.18`; `1.0` | Conditionally Required: when available | | `db.cosmosdb.request_content_length` | int | Request payload size in bytes | | Recommended | | `db.cosmosdb.status_code` | int | Cosmos DB status code. | `200`; `201` | Conditionally Required: if response was received | | `db.cosmosdb.sub_status_code` | int | Cosmos DB sub status code. | `1000`; `1002` | Conditionally Required: [2] | | `user_agent.original` | string | Full user-agent string is generated by Cosmos DB SDK [3] | `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]:** when performing one of the operations in this list **[2]:** when response was received and contained sub-code. **[3]:** 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 | |---|---| | `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 | |---|---| | `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` | `"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.22.0/specification/document-status.md