<!--- Hugo front matter used to generate the website version of this page:
linkTitle: Cosmos DB
--->

# 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.

<!-- semconv db.cosmosdb -->
| 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`](../attributes-registry/user-agent.md) | 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<br> `sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'<br> `direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'<br> `number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'<br> `type_of_machine_architecture` : Machine architecture. e.g. 'X64'<br> `operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'<br> `runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'<br> `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 |
<!-- endsemconv -->

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.26.0/specification/document-status.md
