141 lines
12 KiB
Markdown
141 lines
12 KiB
Markdown
<!--- 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.
|
|
|
|
## 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(full) -->
|
|
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
|
|
<!-- see templates/registry/markdown/snippet.md.j2 -->
|
|
<!-- prettier-ignore-start -->
|
|
<!-- markdownlint-capture -->
|
|
<!-- markdownlint-disable -->
|
|
|
|
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|
|
|---|---|---|---|---|---|
|
|
| [`db.collection.name`](/docs/attributes-registry/db.md) | string | Cosmos DB container name. [1] | `public.users`; `customers` | `Conditionally Required` if available |  |
|
|
| [`db.cosmosdb.connection_mode`](/docs/attributes-registry/db.md) | string | Cosmos client connection mode. | `gateway`; `direct` | `Conditionally Required` if not `direct` (or pick gw as default) |  |
|
|
| [`db.cosmosdb.operation_type`](/docs/attributes-registry/db.md) | string | CosmosDB Operation Type. | `Invalid`; `Create`; `Patch` | `Conditionally Required` when performing one of the operations in this list |  |
|
|
| [`db.cosmosdb.request_charge`](/docs/attributes-registry/db.md) | double | RU consumed for that operation | `46.18`; `1.0` | `Conditionally Required` when available |  |
|
|
| [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB status code. | `200`; `201` | `Conditionally Required` if response was received |  |
|
|
| [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` when response was received and contained sub-code. |  |
|
|
| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [2] | `customers`; `test.users` | `Conditionally Required` If available. |  |
|
|
| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [3] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [4] |  |
|
|
| [`error.type`](/docs/attributes-registry/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/attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Conditionally Required` [7] |  |
|
|
| [`db.cosmosdb.client_id`](/docs/attributes-registry/db.md) | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | `Recommended` |  |
|
|
| [`db.cosmosdb.request_content_length`](/docs/attributes-registry/db.md) | int | Request payload size in bytes | | `Recommended` |  |
|
|
| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [8] |  |
|
|
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
|
| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [10] | `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.<key>`](/docs/attributes-registry/db.md) | string | The query parameters used in `db.query.text`, with `<key>` being the parameter name, and the attribute value being the parameter value. [11] | `someval`; `55` | `Opt-In` |  |
|
|
|
|
**[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.
|
|
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
|
|
|
|
**[2]:** <!-- TODO: overriding the base note, workaround for https://github.com/open-telemetry/build-tools/issues/299 -->
|
|
|
|
**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
|
|
|
|
**[4]:** If readily available. Otherwise, if the instrumentation library parses `db.query.text` to capture `db.operation.name`, then it SHOULD be the first operation name found in the query.
|
|
|
|
**[5]:** The `error.type` SHOULD match the error code returned by the database or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report.
|
|
|
|
**[6]:** 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]:** If using a port other than the default port for this DBMS and if `server.address` is set.
|
|
|
|
**[8]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information.
|
|
|
|
**[9]:** 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.
|
|
|
|
**[10]:** 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".
|
|
|
|
**[11]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders.
|
|
If a parameter has no name and instead is referenced only by index, then `<key>` SHOULD be the 0-based index.
|
|
|
|
|
|
|
|
`db.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 |
|
|
|---|---|---|
|
|
| `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 |  |
|
|
|
|
|
|
`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. |  |
|
|
|
|
|
|
|
|
<!-- markdownlint-restore -->
|
|
<!-- prettier-ignore-end -->
|
|
<!-- END AUTOGENERATED TEXT -->
|
|
<!-- 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 orders"` |
|
|
| `kind` | `"internal"` |
|
|
| `az.namespace` | `"Microsoft.DocumentDB"` |
|
|
| `db.system` | `"cosmosdb"` |
|
|
| `db.collection.name` | `"orders"` |
|
|
| `db.namespace` | `"ShopDb"` |
|
|
| `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.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.33.0/specification/document-status.md
|