From 6da7369d013ab6db1f0e68084767713fd05b7a2c Mon Sep 17 00:00:00 2001 From: "Kevin N." <6809505+kevinnoel-be@users.noreply.github.com> Date: Fri, 25 Oct 2024 18:50:24 +0200 Subject: [PATCH 1/2] Add system uptime metric (#1507) --- .chloggen/add-system-uptime.yaml | 17 +++++++++++++++++ docs/system/system-metrics.md | 27 +++++++++++++++++++++++++++ model/system/metrics.yaml | 12 ++++++++++++ 3 files changed, 56 insertions(+) create mode 100644 .chloggen/add-system-uptime.yaml diff --git a/.chloggen/add-system-uptime.yaml b/.chloggen/add-system-uptime.yaml new file mode 100644 index 0000000000..a9c3e49c0d --- /dev/null +++ b/.chloggen/add-system-uptime.yaml @@ -0,0 +1,17 @@ +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: system + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add system uptime metric + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [648] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 962087e83b..96ec1475e7 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -21,6 +21,8 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam +- [General Metrics](#general-metrics) + - [Metric: `system.uptime`](#metric-systemuptime) - [Processor Metrics](#processor-metrics) - [Metric: `system.cpu.time`](#metric-systemcputime) - [Metric: `system.cpu.utilization`](#metric-systemcpuutilization) @@ -73,6 +75,31 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam > * SHOULD introduce a control mechanism to allow users to opt-in to the new > conventions once the migration plan is finalized. +## General Metrics + +### Metric: `system.uptime` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `system.uptime` | Gauge | `s` | The time the system has been running [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Instrumentations SHOULD use a gauge with type `double` and measure uptime in seconds as a floating point number with the highest precision available. +The actual accuracy would depend on the instrumentation and operating system. + + + + + + ## Processor Metrics **Description:** System level processor metrics captured under the namespace `system.cpu`. diff --git a/model/system/metrics.yaml b/model/system/metrics.yaml index b2b79bf3b7..2f954e41aa 100644 --- a/model/system/metrics.yaml +++ b/model/system/metrics.yaml @@ -1,4 +1,16 @@ groups: + # system.* metrics + - id: metric.system.uptime + type: metric + metric_name: system.uptime + stability: experimental + brief: "The time the system has been running" + note: | + Instrumentations SHOULD use a gauge with type `double` and measure uptime in seconds as a floating point number with the highest precision available. + The actual accuracy would depend on the instrumentation and operating system. + instrument: gauge + unit: "s" + # system.cpu.* metrics - id: metric.system.cpu.time type: metric From 63094c6c92e1fa60a3d9ed972554a47dbb691a13 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Tue, 29 Oct 2024 05:19:22 +0530 Subject: [PATCH 2/2] Cosmos DB: Operation Level Metrics (#1438) Co-authored-by: Justine Cocchi Co-authored-by: Liudmila Molkova Co-authored-by: Trask Stalnaker --- .../users_sourabhjain_otelcosmosmetrics.yaml | 22 ++ docs/attributes-registry/db.md | 52 +++-- docs/database/cassandra.md | 1 + docs/database/cosmosdb.md | 206 ++++++++++++++++-- docs/database/database-metrics.md | 190 ++++++++++++++++ docs/database/database-spans.md | 1 + docs/database/mariadb.md | 1 + docs/database/mssql.md | 1 + docs/database/mysql.md | 1 + docs/database/postgresql.md | 1 + docs/database/sql.md | 1 + model/database/common.yaml | 29 +++ model/database/cosmosdb-metrics.yaml | 28 +++ .../deprecated/registry-deprecated.yaml | 51 +++++ model/database/metrics.yaml | 30 +++ model/database/registry.yaml | 84 +++---- model/database/spans.yaml | 13 +- 17 files changed, 612 insertions(+), 100 deletions(-) create mode 100644 .chloggen/users_sourabhjain_otelcosmosmetrics.yaml create mode 100644 model/database/cosmosdb-metrics.yaml diff --git a/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml b/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml new file mode 100644 index 0000000000..34a4940925 --- /dev/null +++ b/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: db + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: "Added new common `db.client.response.returned_rows` database metric and several operation level metrics for Azure Cosmos DB." + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1438] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 101c111191..bc6f42e7f4 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -28,6 +28,7 @@ This group defines the attributes used to describe telemetry in the context of d | `db.query.parameter.` | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [5] | `someval`; `55` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.query.summary` | string | Low cardinality representation of a database query text. [6] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.query.text` | string | The database query being executed. [7] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.response.returned_rows` | int | Number of rows returned by the operation. | `10`; `30`; `1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.response.status_code` | string | Database response status code. [8] | `102`; `ORA-17002`; `08P01`; `404` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.system` | string | The database management system (DBMS) product as identified by the client instrumentation. [9] | `other_sql`; `adabas`; `cache` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -193,9 +194,9 @@ This group defines attributes for Azure Cosmos DB. |---|---|---|---|---| | `db.cosmosdb.client_id` | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.cosmosdb.connection_mode` | string | Cosmos client connection mode. | `gateway`; `direct` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.cosmosdb.operation_type` | string | Cosmos DB Operation Type. | `batch`; `create`; `delete` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.cosmosdb.request_charge` | double | RU consumed for that operation | `46.18`; `1.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.cosmosdb.request_content_length` | int | Request payload size in bytes | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.consistency_level` | string | Account or request [consistency level](https://learn.microsoft.com/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong`; `Session` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.request_charge` | double | Request units consumed for the operation. | `46.18`; `1.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.request_content_length` | int | Request payload size in bytes. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.cosmosdb.sub_status_code` | int | Cosmos DB sub status code. | `1000`; `1002` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `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. @@ -203,27 +204,17 @@ This group defines attributes for Azure Cosmos DB. | Value | Description | Stability | |---|---|---| | `direct` | Direct connection. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gateway` | Gateway (HTTP) connections mode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gateway` | Gateway (HTTP) connection. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`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. +`db.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 | |---|---|---| -| `batch` | batch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `create` | create | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `delete` | delete | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `execute` | execute | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `execute_javascript` | execute_javascript | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `head` | head | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `head_feed` | head_feed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `invalid` | invalid | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `patch` | patch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `query` | query | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `query_plan` | query_plan | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `read` | read | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `read_feed` | read_feed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `replace` | replace | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `upsert` | upsert | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `BoundedStaleness` | bounded_staleness | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ConsistentPrefix` | consistent_prefix | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Eventual` | eventual | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Session` | session | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Strong` | strong | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## Elasticsearch Attributes @@ -245,6 +236,7 @@ This group defines attributes for Elasticsearch. | `db.cassandra.table` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | | `db.connection_string` | string | Deprecated, use `server.address`, `server.port` attributes instead. | `Server=(localdb)\v11.0;Integrated Security=true;` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `server.address` and `server.port`. | | `db.cosmosdb.container` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | +| `db.cosmosdb.operation_type` | string | Deprecated, no replacement at this time. | `batch`; `create`; `delete` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
No replacement at this time. | | `db.cosmosdb.status_code` | int | Deprecated, use `db.response.status_code` instead. | `200`; `201` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.response.status_code`. | | `db.elasticsearch.cluster.name` | string | Deprecated, use `db.namespace` instead. | `e9106fc68e3044f0b1475b04bf4ffd5f` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | | `db.instance.id` | string | Deprecated, no general replacement at this time. For Elasticsearch, use `db.elasticsearch.node.name` instead. | `mysql-e26b99z.example.com` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, no general replacement at this time. For Elasticsearch, use `db.elasticsearch.node.name` instead. | @@ -258,6 +250,26 @@ This group defines attributes for Elasticsearch. | `db.statement` | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.query.text`. | | `db.user` | string | Deprecated, no replacement at this time. | `readonly_user`; `reporting_user` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
No replacement at this time. | +`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 | +|---|---|---| +| `batch` | batch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `create` | create | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `delete` | delete | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `execute` | execute | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `execute_javascript` | execute_javascript | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `head` | head | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `head_feed` | head_feed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `invalid` | invalid | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `patch` | patch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `query` | query | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `query_plan` | query_plan | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `read` | read | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `read_feed` | read_feed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `replace` | replace | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `upsert` | upsert | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + ## Deprecated Database Metrics "Describes deprecated db metrics attributes." diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index 99d4fd6e08..ccfa8ad091 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -36,6 +36,7 @@ The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend a | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [11] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [12] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [13] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [14] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [15] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [16] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [17] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index fde6226532..3b75b969ae 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -2,7 +2,22 @@ linkTitle: Cosmos DB ---> -# Semantic Conventions for Microsoft Cosmos DB + + + + +- [Semantic Conventions for Microsoft Azure Cosmos DB](#semantic-conventions-for-microsoft-azure-cosmos-db) + - [Attributes](#attributes) + - [Example](#example) + - [Operation Level Metrics](#operation-level-metrics) + - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) + - [Metric: `db.client.response.returned_rows`](#metric-dbclientresponsereturned_rows) + - [Metric: `db.client.cosmosdb.operation.request_charge`](#metric-dbclientcosmosdboperationrequest_charge) + - [Metric: `db.client.cosmosdb.active_instance.count`](#metric-dbclientcosmosdbactive_instancecount) + + + +# Semantic Conventions for Microsoft Azure Cosmos DB **Status**: [Experimental][DocumentStatus] @@ -26,17 +41,18 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net |---|---|---|---|---|---| | [`db.collection.name`](/docs/attributes-registry/db.md) | string | Cosmos DB container name. [1] | `public.users`; `customers` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.connection_mode`](/docs/attributes-registry/db.md) | string | Cosmos client connection mode. | `gateway`; `direct` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.operation_type`](/docs/attributes-registry/db.md) | string | Cosmos DB Operation Type. | `batch`; `create`; `delete` | `Conditionally Required` when performing one of the operations in this list | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.request_charge`](/docs/attributes-registry/db.md) | double | RU consumed for that operation | `46.18`; `1.0` | `Conditionally Required` when available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.consistency_level`](/docs/attributes-registry/db.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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.request_charge`](/docs/attributes-registry/db.md) | double | Request units consumed for the operation. | `46.18`; `1.0` | `Conditionally Required` when available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [3] | `create_item`; `query_items`; `read_item` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Cosmos DB row count in result set. | `10`; `20` | `Conditionally Required` if response was received and returned any rows | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Cosmos DB status code. [5] | `200`; `201` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`error.type`](/docs/attributes-registry/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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Conditionally Required` If not default (443). | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`az.namespace`](/docs/attributes-registry/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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.client_id`](/docs/attributes-registry/db.md) | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.request_content_length`](/docs/attributes-registry/db.md) | int | Request payload size in bytes | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.request_content_length`](/docs/attributes-registry/db.md) | int | Request payload size in bytes. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [9] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [10] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [11] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [12] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [13] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -229,27 +245,17 @@ and SHOULD be provided **at span creation time** (if provided at all): | Value | Description | Stability | |---|---|---| | `direct` | Direct connection. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gateway` | Gateway (HTTP) connections mode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gateway` | Gateway (HTTP) connection. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`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. +`db.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 | |---|---|---| -| `batch` | batch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `create` | create | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `delete` | delete | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `execute` | execute | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `execute_javascript` | execute_javascript | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `head` | head | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `head_feed` | head_feed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `invalid` | invalid | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `patch` | patch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `query` | query | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `query_plan` | query_plan | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `read` | read | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `read_feed` | read_feed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `replace` | replace | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `upsert` | upsert | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `BoundedStaleness` | bounded_staleness | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ConsistentPrefix` | consistent_prefix | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Eventual` | eventual | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Session` | session | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Strong` | strong | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `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. @@ -274,11 +280,165 @@ and SHOULD be provided **at span creation time** (if provided at all): | `db.operation.name` | `"read_item"` | | `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.request_content_length` | `20` | -| `db.cosmosdb.status_code` | `201` | +| `db.response.status_code` | `201` | | `db.cosmosdb.sub_status_code` | `0` | | `db.cosmosdb.request_charge` | `7.43` | +## Operation Level 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 [db.client.cosmosdb.operation.request_charge](#metric-dbclientcosmosdboperationrequest_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 [db.client.cosmosdb.operation.request_charge](#metric-dbclientcosmosdboperationrequest_charge) metrics for dimensions. + +### Metric: `db.client.cosmosdb.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.35.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 | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.client.cosmosdb.operation.request_charge` | Histogram | `{request_unit}` | [Request charge](https://learn.microsoft.com/azure/cosmos-db/request-units) consumed by the operation | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| 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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.consistency_level`](/docs/attributes-registry/db.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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [2] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [4] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Conditionally Required` [8] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. + +**[2]:** It is RECOMMENDED to capture the value as provided by the application +without attempting to do any case normalization. + +A single database query may involve multiple operations. If the operation +name is parsed from the query text, it SHOULD only be captured for queries that +contain a single operation or when the operation name describing the +whole query is available by other means. + +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. + +This attribute has stability level RELEASE CANDIDATE. + +**[3]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query. + +**[4]:** 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. +This attribute has stability level RELEASE CANDIDATE. + +**[5]:** If the operation failed and status code is available. + +**[6]:** 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]:** 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]:** If using a port other than the default port for this DBMS and if `server.address` is set. + +**[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. + +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`db.namespace`](/docs/attributes-registry/db.md) + +`db.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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ConsistentPrefix` | consistent_prefix | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Eventual` | eventual | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Session` | session | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Strong` | strong | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + + + + +### Metric: `db.client.cosmosdb.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 | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.client.cosmosdb.active_instance.count` | UpDownCounter | `{instance}` | Number of active client instances | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [1] | `80`; `8080`; `443` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** 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]:** If using a port other than the default port for this DBMS and if `server.address` is set. + +**[3]:** 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 diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index f27d05bbdf..a82e7ccbd8 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -13,6 +13,8 @@ linkTitle: Metrics - [Database operation](#database-operation) - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) - [Experimental](#experimental) + - [Database Response](#database-response) + - [Metric: `db.client.response.returned_rows`](#metric-dbclientresponsereturned_rows) - [Connection pools](#connection-pools) - [Metric: `db.client.connection.count`](#metric-dbclientconnectioncount) - [Metric: `db.client.connection.idle.max`](#metric-dbclientconnectionidlemax) @@ -239,6 +241,194 @@ and SHOULD be provided **at span creation time** (if provided at all): ## Experimental +### Database Response + +The following metric instruments describe database query response. + +#### Metric: `db.client.response.returned_rows` + +This metric is [recommended][MetricRecommended]. + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters) +of `[1, 2, 5, 10, 20, 50, 100, 200, 500, 1000, 2000, 5000, 10000]`. + +Explaining bucket configuration: + +1. 1, 2, 5, 10, 50, 100: These buckets are useful for capturing scenarios where only a small number of items are returned. Such small queries are common in real-time or interactive applications where performance and quick responses are critical. +2. 200, 500, 1000: These values represent typical workloads where moderate amounts of data are returned in each query. +3. 2000, 5000: These boundaries capture scenarios where the query returns large datasets. These larger page sizes can potentially increase memory or CPU usage and may lead to longer query execution times, making it important to track performance in these ranges. +4. 10000: This boundary is included to capture rare, very large response sizes. Such queries can put significant strain on system resources, including memory, CPU, and network bandwidth, and can often lead to performance issues such as high latency or even network drops. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.client.response.returned_rows` | Histogram | `{row}` | The actual number of records returned by the database operation. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `other_sql`; `adabas`; `cache` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [2] | `public.users`; `customers` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [4] | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [5] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [7] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [9] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Conditionally Required` [11] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [12] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [13] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [14] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this database system. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` If and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [16] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge. +This attribute has stability level RELEASE CANDIDATE. + +**[2]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. + +A single database query may involve multiple collections. + +If the collection name is parsed from the query text, it SHOULD only be captured for queries that +contain a single collection and it SHOULD match the value provided in +the query text including any schema and database name prefix. + +For batch operations, if the individual operations are known to have the same collection name +then that collection name SHOULD be used. + +If the operation or query involves multiple collections, `db.collection.name` +SHOULD NOT be captured. + +This attribute has stability level RELEASE CANDIDATE. + +**[3]:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query. + +**[4]:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid. +Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. +It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +This attribute has stability level RELEASE CANDIDATE. + +**[5]:** It is RECOMMENDED to capture the value as provided by the application +without attempting to do any case normalization. + +A single database query may involve multiple operations. If the operation +name is parsed from the query text, it SHOULD only be captured for queries that +contain a single operation or when the operation name describing the +whole query is available by other means. + +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. + +This attribute has stability level RELEASE CANDIDATE. + +**[6]:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query. + +**[7]:** 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. +This attribute has stability level RELEASE CANDIDATE. + +**[8]:** If the operation failed and status code is available. + +**[9]:** 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. + +**[10]:** 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. + +**[11]:** If using a port other than the default port for this DBMS and if `server.address` is set. + +**[12]:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. +Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-quey-text) section. +This attribute has stability level RELEASE CANDIDATE. + +**[13]:** if readily available or if instrumentation supports query summarization. + +**[14]:** Semantic conventions for individual database systems SHOULD document whether `network.peer.*` attributes are applicable. Network peer address and port are useful when the application interacts with individual database nodes directly. +If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. + +**[15]:** 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. + +**[16]:** 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. +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. +This attribute has stability level RELEASE CANDIDATE. + +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/attributes-registry/db.md) + +`db.system` 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 | +|---|---|---| +| `adabas` | Adabas (Adaptable Database System) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cassandra` | Apache Cassandra | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `clickhouse` | ClickHouse | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cockroachdb` | CockroachDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cosmosdb` | Microsoft Azure Cosmos DB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `couchbase` | Couchbase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `couchdb` | CouchDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db2` | IBM Db2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `derby` | Apache Derby | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `dynamodb` | Amazon DynamoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `edb` | EnterpriseDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `elasticsearch` | Elasticsearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `filemaker` | FileMaker | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `firebird` | Firebird | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `geode` | Apache Geode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `h2` | H2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hanadb` | SAP HANA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hbase` | Apache HBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hive` | Apache Hive | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `hsqldb` | HyperSQL DataBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `influxdb` | InfluxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `informix` | Informix | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `ingres` | Ingres | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `instantdb` | InstantDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `interbase` | InterBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `intersystems_cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mariadb` | MariaDB (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `maxdb` | SAP MaxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mssql` | Microsoft SQL Server (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mysql` | MySQL (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `netezza` | Netezza | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `opensearch` | OpenSearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `oracle` | Oracle Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other_sql` | Some other SQL database. Fallback only. See notes. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pervasive` | Pervasive PSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pointbase` | PointBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `postgresql` | PostgreSQL (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `progress` | Progress Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `redis` | Redis | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `redshift` | Amazon Redshift | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `spanner` | Cloud Spanner | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `sqlite` | SQLite | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `sybase` | Sybase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `teradata` | Teradata | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `trino` | Trino | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vertica` | Vertica | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + + + + ### Connection pools The following metric instruments describe database client connection pool operations. diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 2839163b94..06c08b0597 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -108,6 +108,7 @@ These attributes will usually be the same for all operations performed over the | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [12] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [13] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [14] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [15] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [16] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [17] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this database system. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [18] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md index fc20d6d57a..99aced8daf 100644 --- a/docs/database/mariadb.md +++ b/docs/database/mariadb.md @@ -30,6 +30,7 @@ The Semantic Conventions for *MariaDB* extend and override the [Database Semanti | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [10] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 46d8c09e18..35519e5fd6 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -30,6 +30,7 @@ The Semantic Conventions for the *Microsoft SQL Server* extend and override the | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [10] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/mysql.md b/docs/database/mysql.md index 58550b31a1..65e273688a 100644 --- a/docs/database/mysql.md +++ b/docs/database/mysql.md @@ -30,6 +30,7 @@ The Semantic Conventions for *MySQL* extend and override the [Database Semantic | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [10] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md index 1481e4d302..23950fbe41 100644 --- a/docs/database/postgresql.md +++ b/docs/database/postgresql.md @@ -30,6 +30,7 @@ The Semantic Conventions for *PostgreSQL* extend and override the [Database Sema | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [10] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/sql.md b/docs/database/sql.md index bb759388fb..66773c90bd 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -54,6 +54,7 @@ Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic co | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [10] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.query.parameter.`](/docs/attributes-registry/db.md) | string | A query parameter used in `db.query.text`, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [16] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/database/common.yaml b/model/database/common.yaml index ff268158b8..5d776a2f28 100644 --- a/model/database/common.yaml +++ b/model/database/common.yaml @@ -32,6 +32,35 @@ groups: Instrumentations SHOULD document how `error.type` is populated. + - id: attributes.db.cosmosdb.minimal + type: attribute_group + brief: 'Azure Cosmos DB Client attributes' + stability: experimental + extends: attributes.db.client.minimal + attributes: + # TODO: add db.system once https://github.com/open-telemetry/build-tools/issues/192 is possible + # - ref: db.system + # requirement_level: + # conditionally_required: if available + - ref: db.collection.name + brief: > + Cosmos DB container name. + note: > + It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. + requirement_level: + conditionally_required: If available + - ref: db.namespace + sampling_relevant: true + requirement_level: + conditionally_required: If available. + note: "" # overriding the base note + - ref: db.cosmosdb.sub_status_code + requirement_level: + conditionally_required: when response was received and contained sub-code. + - ref: db.cosmosdb.consistency_level + requirement_level: + conditionally_required: If available. + - id: attributes.db.client.with_query_and_collection extends: attributes.db.client.minimal type: attribute_group diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml new file mode 100644 index 0000000000..3946880699 --- /dev/null +++ b/model/database/cosmosdb-metrics.yaml @@ -0,0 +1,28 @@ +groups: + - id: metric.db.client.cosmosdb.operation.request_charge + type: metric + metric_name: db.client.cosmosdb.operation.request_charge + brief: "[Request charge](https://learn.microsoft.com/azure/cosmos-db/request-units) consumed by the operation" + instrument: histogram + unit: "{request_unit}" + stability: experimental + extends: attributes.db.cosmosdb.minimal + + - id: metric.db.client.cosmosdb.active_instance.count + type: metric + metric_name: db.client.cosmosdb.active_instance.count + brief: "Number of active client instances" + instrument: updowncounter + unit: "{instance}" + stability: experimental + attributes: + # TODO: add db.system once https://github.com/open-telemetry/build-tools/issues/192 is possible + # - ref: db.system + # requirement_level: + # conditionally_required: if available + - ref: server.address + brief: > + Name of the database host. + - ref: server.port + requirement_level: + conditionally_required: If using a port other than the default port for this DBMS and if `server.address` is set. diff --git a/model/database/deprecated/registry-deprecated.yaml b/model/database/deprecated/registry-deprecated.yaml index 610aadf0ca..04bcc26ec3 100644 --- a/model/database/deprecated/registry-deprecated.yaml +++ b/model/database/deprecated/registry-deprecated.yaml @@ -97,6 +97,57 @@ groups: deprecated: 'Replaced by `db.response.status_code`.' brief: 'Deprecated, use `db.response.status_code` instead.' examples: [200, 201] + - id: db.cosmosdb.operation_type + type: + members: + - id: batch + value: "batch" + stability: experimental + - id: create + value: "create" + stability: experimental + - id: delete + value: "delete" + stability: experimental + - id: execute + value: "execute" + stability: experimental + - id: execute_javascript + value: "execute_javascript" + stability: experimental + - id: invalid + value: "invalid" + stability: experimental + - id: head + value: "head" + stability: experimental + - id: head_feed + value: "head_feed" + stability: experimental + - id: patch + value: "patch" + stability: experimental + - id: query + value: "query" + stability: experimental + - id: query_plan + value: "query_plan" + stability: experimental + - id: read + value: "read" + stability: experimental + - id: read_feed + value: "read_feed" + stability: experimental + - id: replace + value: "replace" + stability: experimental + - id: upsert + value: "upsert" + stability: experimental + stability: experimental + deprecated: "No replacement at this time." + brief: Deprecated, no replacement at this time. - id: registry.db.metrics.deprecated type: attribute_group diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index d8e8f3fbc0..5ae4d801b9 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -131,3 +131,33 @@ groups: attributes: - ref: db.client.connection.pool.name requirement_level: required + + - id: metric.db.client.response.returned_rows + type: metric + metric_name: db.client.response.returned_rows + brief: "The actual number of records returned by the database operation." + instrument: histogram + unit: "{row}" + stability: experimental + extends: attributes.db.client.with_query_and_collection + attributes: + - ref: db.system + # TODO: Not adding to the minimal because of https://github.com/open-telemetry/build-tools/issues/192 + requirement_level: required + - ref: network.peer.address + brief: Peer address of the database node where the operation was performed. + requirement_level: + recommended: If applicable for this database system. + note: > + Semantic conventions for individual database systems SHOULD document whether `network.peer.*` attributes are applicable. + Network peer address and port are useful when the application interacts with individual database nodes directly. + + If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. + - ref: network.peer.port + requirement_level: + recommended: If and only if `network.peer.address` is set. + - ref: db.namespace + requirement_level: + conditionally_required: If available. + - ref: db.query.text + requirement_level: opt_in diff --git a/model/database/registry.yaml b/model/database/registry.yaml index 5924f054a6..c67c035cc2 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -148,7 +148,11 @@ groups: This attribute has stability level RELEASE CANDIDATE. examples: ["102", "ORA-17002", "08P01", "404"] - + - id: db.response.returned_rows + type: int + stability: experimental + brief: Number of rows returned by the operation. + examples: [10, 30, 1000] - id: db.system brief: The database management system (DBMS) product as identified by the client instrumentation. note: > @@ -496,7 +500,7 @@ groups: members: - id: gateway value: "gateway" - brief: Gateway (HTTP) connections mode + brief: Gateway (HTTP) connection. stability: experimental - id: direct value: "direct" @@ -504,70 +508,42 @@ groups: stability: experimental stability: experimental brief: Cosmos client connection mode. - - id: db.cosmosdb.operation_type - type: - members: - - id: batch - value: "batch" - stability: experimental - - id: create - value: "create" - stability: experimental - - id: delete - value: "delete" - stability: experimental - - id: execute - value: "execute" - stability: experimental - - id: execute_javascript - value: "execute_javascript" - stability: experimental - - id: invalid - value: "invalid" - stability: experimental - - id: head - value: "head" - stability: experimental - - id: head_feed - value: "head_feed" - stability: experimental - - id: patch - value: "patch" - stability: experimental - - id: query - value: "query" - stability: experimental - - id: query_plan - value: "query_plan" - stability: experimental - - id: read - value: "read" - stability: experimental - - id: read_feed - value: "read_feed" - stability: experimental - - id: replace - value: "replace" - stability: experimental - - id: upsert - value: "upsert" - stability: experimental - stability: experimental - brief: Cosmos DB Operation Type. - id: db.cosmosdb.request_charge type: double stability: experimental - brief: RU consumed for that operation + brief: Request units consumed for the operation. examples: [46.18, 1.0] - id: db.cosmosdb.request_content_length type: int stability: experimental - brief: Request payload size in bytes + brief: Request payload size in bytes. - id: db.cosmosdb.sub_status_code type: int stability: experimental brief: Cosmos DB sub status code. examples: [1000, 1002] + - id: db.cosmosdb.consistency_level + type: + members: + - id: strong + value: "Strong" + stability: experimental + - id: bounded_staleness + value: "BoundedStaleness" + stability: experimental + - id: session + value: "Session" + stability: experimental + - id: eventual + value: "Eventual" + stability: experimental + - id: consistent_prefix + value: "ConsistentPrefix" + stability: experimental + stability: experimental + brief: Account or request [consistency level](https://learn.microsoft.com/azure/cosmos-db/consistency-levels). + examples: ["Eventual", "ConsistentPrefix", "BoundedStaleness", "Strong", "Session"] + - id: registry.db.elasticsearch type: attribute_group display_name: Elasticsearch Attributes diff --git a/model/database/spans.yaml b/model/database/spans.yaml index 8ed7e57d62..9f37b23c3c 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -47,6 +47,7 @@ groups: sampling_relevant: true - ref: server.port sampling_relevant: true + - ref: db.response.returned_rows - id: trace.db.common.full type: attribute_group @@ -539,9 +540,6 @@ groups: Attributes for Cosmos DB. attributes: - ref: db.cosmosdb.client_id - - ref: db.cosmosdb.operation_type - requirement_level: - conditionally_required: when performing one of the operations in this list - ref: user_agent.original brief: 'Full user-agent string is generated by Cosmos DB SDK' note: > @@ -573,6 +571,12 @@ groups: examples: ["200", "201"] requirement_level: conditionally_required: if response was received + - ref: db.response.returned_rows + brief: > + Cosmos DB row count in result set. + examples: [10, 20] + requirement_level: + conditionally_required: if response was received and returned any rows - ref: db.cosmosdb.sub_status_code requirement_level: conditionally_required: when response was received and contained sub-code. @@ -719,3 +723,6 @@ groups: - ref: server.port requirement_level: conditionally_required: If not default (443). + - ref: db.cosmosdb.consistency_level + requirement_level: + conditionally_required: If available.