From 3e8e1019e9e6f3de134b1187d92791135a33f9bf Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Mon, 30 Sep 2024 12:16:58 +0530 Subject: [PATCH 01/84] wip --- model/database/metrics.yaml | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index bc4985e323..98ff6e1160 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -33,6 +33,7 @@ groups: - ref: db.namespace requirement_level: conditionally_required: If available. + - id: metric.db.client.connection.count type: metric metric_name: db.client.connection.count @@ -133,3 +134,39 @@ groups: attributes: - ref: db.client.connection.pool.name requirement_level: required + + - id: metric.db.cosmos.operation.request_charge + type: metric + metric_name: db.cosmos.operation.request_charge + brief: "Request Charge Consumed by the operation" + instrument: histogram + unit: "{request_units}" + stability: experimental + extends: attributes.db.cosmos.minimal + + - id: metric.db.cosmos.operation.max_item_count + type: metric + metric_name: db.cosmos.operation.max_item_count + brief: "Max Item Count Requested by the Feed (Query, ReadAll, ReadMany, Change Feed) operation" + instrument: gauge + unit: "{count}" + stability: experimental + extends: attributes.db.cosmos.minimal + + - id: metric.db.cosmos.operation.actual_item_count + type: metric + metric_name: db.cosmos.operation.actual_item_count + brief: "Actual Item Count got by the Feed (Query, ReadAll, ReadMany, Change Feed) Operation" + instrument: gauge + unit: "{count}" + stability: experimental + extends: attributes.db.cosmos.minimal + + - id: metric.db.cosmos.operation.regions_contacted + type: metric + metric_name: db.cosmos.operation.regions_contacted + brief: "Number of region contacted by the Operation" + instrument: gauge + unit: "{count}" + stability: experimental + extends: attributes.db.cosmos.minimal From d43b29824b5fd7568a4af373d170bc476f942e50 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Mon, 30 Sep 2024 13:40:39 +0530 Subject: [PATCH 02/84] cosmosdb operation level metrics --- .../users_sourabhjain_otelcosmosmetrics.yaml | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 .chloggen/users_sourabhjain_otelcosmosmetrics.yaml diff --git a/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml b/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml new file mode 100644 index 0000000000..a221ba7437 --- /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: new_component + +# 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 operation level metrics for 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: From a323aec1fed5b9cc7b2350bf88f2f5e21869ea9b Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Mon, 30 Sep 2024 21:29:31 +0530 Subject: [PATCH 03/84] Update model/database/metrics.yaml Co-authored-by: Justine Cocchi --- model/database/metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index 98ff6e1160..c3dcbf6dc0 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -165,7 +165,7 @@ groups: - id: metric.db.cosmos.operation.regions_contacted type: metric metric_name: db.cosmos.operation.regions_contacted - brief: "Number of region contacted by the Operation" + brief: "Number of regions contacted for the operation" instrument: gauge unit: "{count}" stability: experimental From fd6c5da38fcdae99effcc8025b1f0c24494d8ec8 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Mon, 30 Sep 2024 21:29:44 +0530 Subject: [PATCH 04/84] Update model/database/metrics.yaml Co-authored-by: Justine Cocchi --- model/database/metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index c3dcbf6dc0..4de362cc2e 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -156,7 +156,7 @@ groups: - id: metric.db.cosmos.operation.actual_item_count type: metric metric_name: db.cosmos.operation.actual_item_count - brief: "Actual Item Count got by the Feed (Query, ReadAll, ReadMany, Change Feed) Operation" + brief: "Actual item count returned by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed)" instrument: gauge unit: "{count}" stability: experimental From 74078ea8d323c97fa14183bfd266ebf509e2a5b9 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Mon, 30 Sep 2024 21:29:57 +0530 Subject: [PATCH 05/84] Update model/database/metrics.yaml Co-authored-by: Justine Cocchi --- model/database/metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index 4de362cc2e..d604707734 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -147,7 +147,7 @@ groups: - id: metric.db.cosmos.operation.max_item_count type: metric metric_name: db.cosmos.operation.max_item_count - brief: "Max Item Count Requested by the Feed (Query, ReadAll, ReadMany, Change Feed) operation" + brief: "Max item count requested by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed) " instrument: gauge unit: "{count}" stability: experimental From c1f2efadd104f8cf398a5cd282e337b4dbe8170e Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Mon, 30 Sep 2024 21:30:25 +0530 Subject: [PATCH 06/84] Update model/database/metrics.yaml Co-authored-by: Justine Cocchi --- model/database/metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index d604707734..769579ee3b 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -138,7 +138,7 @@ groups: - id: metric.db.cosmos.operation.request_charge type: metric metric_name: db.cosmos.operation.request_charge - brief: "Request Charge Consumed by the operation" + brief: "Request Charge consumed by the operation" instrument: histogram unit: "{request_units}" stability: experimental From 54ef995dd1468086e8a2b49978c8714e443df1b5 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Mon, 30 Sep 2024 21:30:52 +0530 Subject: [PATCH 07/84] Update model/database/metrics.yaml Co-authored-by: Justine Cocchi --- model/database/metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index 769579ee3b..4929c6c197 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -135,7 +135,7 @@ groups: - ref: db.client.connection.pool.name requirement_level: required - - id: metric.db.cosmos.operation.request_charge + - id: metric.db.cosmosdb.operation.request_charge type: metric metric_name: db.cosmos.operation.request_charge brief: "Request Charge consumed by the operation" From f71ebb73807aeb8fb265338fb6915457b43f9845 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Mon, 30 Sep 2024 21:34:13 +0530 Subject: [PATCH 08/84] added consistency level --- model/database/registry.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/model/database/registry.yaml b/model/database/registry.yaml index f55ab580f0..6b76a90fcf 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -534,6 +534,11 @@ groups: stability: experimental brief: Cosmos DB sub status code. examples: [1000, 1002] + - id: db.cosmosdb.consistency_level + type: string + stability: experimental + brief: Account or Request Consistency Level. + examples: [Eventual, ConsistentPrefix, BoundedStaleness, Strong or Session] - id: registry.db.elasticsearch type: attribute_group display_name: Elasticsearch Attributes From 7678272d5435b87332bcf87c1650ba3d206c99eb Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Mon, 30 Sep 2024 21:36:14 +0530 Subject: [PATCH 09/84] cosmosdb name change --- model/database/metrics.yaml | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index 4929c6c197..adadd8c48b 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -137,36 +137,36 @@ groups: - id: metric.db.cosmosdb.operation.request_charge type: metric - metric_name: db.cosmos.operation.request_charge + metric_name: db.cosmosdb.operation.request_charge brief: "Request Charge consumed by the operation" instrument: histogram unit: "{request_units}" stability: experimental - extends: attributes.db.cosmos.minimal + extends: attributes.db.cosmosdb.minimal - - id: metric.db.cosmos.operation.max_item_count + - id: metric.db.cosmosdb.operation.max_item_count type: metric - metric_name: db.cosmos.operation.max_item_count + metric_name: db.cosmosdb.operation.max_item_count brief: "Max item count requested by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed) " instrument: gauge unit: "{count}" stability: experimental - extends: attributes.db.cosmos.minimal + extends: attributes.db.cosmosdb.minimal - - id: metric.db.cosmos.operation.actual_item_count + - id: metric.db.cosmosdb.operation.actual_item_count type: metric - metric_name: db.cosmos.operation.actual_item_count + metric_name: db.cosmosdb.operation.actual_item_count brief: "Actual item count returned by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed)" instrument: gauge unit: "{count}" stability: experimental - extends: attributes.db.cosmos.minimal + extends: attributes.db.cosmosdb.minimal - - id: metric.db.cosmos.operation.regions_contacted + - id: metric.db.cosmosdb.operation.regions_contacted type: metric - metric_name: db.cosmos.operation.regions_contacted + metric_name: db.cosmosdb.operation.regions_contacted brief: "Number of regions contacted for the operation" instrument: gauge unit: "{count}" stability: experimental - extends: attributes.db.cosmos.minimal + extends: attributes.db.cosmosdb.minimal From e324ded2c200683f35950e29d944dc91c27e7c2f Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Tue, 1 Oct 2024 17:29:58 +0530 Subject: [PATCH 10/84] wip --- docs/database/database-metrics.md | 408 ++++++++++++++++++++++++++++++ model/database/metrics.yaml | 37 ++- 2 files changed, 438 insertions(+), 7 deletions(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 30056e1c13..f4cd0f0b33 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -423,6 +423,414 @@ This metric is [recommended][MetricRecommended]. |---|---|---|---|---|---| | [`db.client.connection.pool.name`](/docs/attributes-registry/db.md) | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation SHOULD use a combination of parameters that would make the name unique, for example, combining attributes `server.address`, `server.port`, and `db.namespace`, formatted as `server.address:server.port/db.namespace`. Instrumentations that generate connection pool name following different patterns SHOULD document it. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.cosmosdb.operation.request_charge` | Histogram | `{request_units}` | Request Charge 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 | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | `Required` | ![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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.consistency_level`](/docs/attributes-registry/db.md) | string | Account or Request Consistency Level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB status code. | `200`; `201` | `Required` | ![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` | `Required` | ![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. [2] | `customers`; `test.users` | `Required` | ![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] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [4] | `other_sql`; `adabas`; `cache` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![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. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. + +**[2]:** 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. + +**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. +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. + +**[4]:** 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. + +**[5]:** 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. + + + +`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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mysql` | MySQL | ![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 | ![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) | + + + + + + + + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.query.limit` | Histogram | `{count}` | Max item count requested by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed) | ![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 | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | `Required` | ![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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.consistency_level`](/docs/attributes-registry/db.md) | string | Account or Request Consistency Level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB status code. | `200`; `201` | `Required` | ![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` | `Required` | ![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. [2] | `customers`; `test.users` | `Required` | ![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] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [4] | `other_sql`; `adabas`; `cache` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![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. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. + +**[2]:** 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. + +**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. +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. + +**[4]:** 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. + +**[5]:** 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. + + + +`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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mysql` | MySQL | ![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 | ![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) | + + + + + + + + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.query.response.item_count` | Histogram | `{count}` | Actual item count returned by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed) | ![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 | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | `Required` | ![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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.consistency_level`](/docs/attributes-registry/db.md) | string | Account or Request Consistency Level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB status code. | `200`; `201` | `Required` | ![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` | `Required` | ![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. [2] | `customers`; `test.users` | `Required` | ![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] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [4] | `other_sql`; `adabas`; `cache` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![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. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. + +**[2]:** 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. + +**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. +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. + +**[4]:** 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. + +**[5]:** 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. + + + +`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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mysql` | MySQL | ![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 | ![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) | + + + + + + + + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.cosmosdb.operation.request_charge` | Histogram | `{request_units}` | Request Charge 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 | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | `Required` | ![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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.consistency_level`](/docs/attributes-registry/db.md) | string | Account or Request Consistency Level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB status code. | `200`; `201` | `Required` | ![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` | `Required` | ![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. [2] | `customers`; `test.users` | `Required` | ![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] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [4] | `other_sql`; `adabas`; `cache` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![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. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. + +**[2]:** 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. + +**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. +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. + +**[4]:** 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. + +**[5]:** 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. + + + +`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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mysql` | MySQL | ![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 | ![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) | + + + diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index adadd8c48b..a6791ac90d 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -144,20 +144,20 @@ groups: stability: experimental extends: attributes.db.cosmosdb.minimal - - id: metric.db.cosmosdb.operation.max_item_count + - id: metric.db.query.limit type: metric - metric_name: db.cosmosdb.operation.max_item_count + metric_name: db.query.limit brief: "Max item count requested by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed) " - instrument: gauge + instrument: histogram unit: "{count}" stability: experimental extends: attributes.db.cosmosdb.minimal - - id: metric.db.cosmosdb.operation.actual_item_count + - id: metric.db.query.response.item_count type: metric - metric_name: db.cosmosdb.operation.actual_item_count + metric_name: db.query.response.item_count brief: "Actual item count returned by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed)" - instrument: gauge + instrument: histogram unit: "{count}" stability: experimental extends: attributes.db.cosmosdb.minimal @@ -166,7 +166,30 @@ groups: type: metric metric_name: db.cosmosdb.operation.regions_contacted brief: "Number of regions contacted for the operation" - instrument: gauge + instrument: histogram unit: "{count}" stability: experimental extends: attributes.db.cosmosdb.minimal + + - id: attributes.db.cosmosdb.minimal + type: attribute_group + brief: 'Azure Cosmos DB attributes' + attributes: + - ref: db.system + requirement_level: required + - ref: db.collection.name + requirement_level: required + - ref: db.namespace + requirement_level: required + - ref: db.operation.name + requirement_level: required + - ref: server.address + requirement_level: required + - ref: db.cosmosdb.status_code + requirement_level: required + - ref: db.cosmosdb.sub_status_code + requirement_level: required + - ref: db.cosmosdb.client_id + requirement_level: required + - ref: db.cosmosdb.consistency_level + requirement_level: required From 8c5f65c3bd30120987ef9adb7af907b3f7858e82 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Tue, 1 Oct 2024 18:03:01 +0530 Subject: [PATCH 11/84] consistency level fix --- docs/attributes-registry/db.md | 10 +++++++ docs/database/cosmosdb.md | 13 +++++++++ docs/database/database-metrics.md | 44 +++++++++++++++++++++++++++++++ model/database/registry.yaml | 18 ++++++++++++- model/database/spans.yaml | 2 ++ 5 files changed, 86 insertions(+), 1 deletion(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 1def1b8797..4451bb29bb 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -179,6 +179,16 @@ This group defines attributes for Azure Cosmos DB. | `direct` | Direct connection. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gateway` | Gateway (HTTP) connections mode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +`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) | + `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 | diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 2c93330c50..1a7c2aba1f 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -24,6 +24,7 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| +| [`db.cosmosdb.consistency_level`](/docs/attributes-registry/db.md) | string | Account or Request Consistency Level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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) | @@ -222,6 +223,18 @@ and SHOULD be provided **at span creation time** (if provided at all): | `direct` | Direct connection. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gateway` | Gateway (HTTP) connections mode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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) | + + `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 | diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index f4cd0f0b33..352972a32c 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -469,6 +469,17 @@ For batch operations, if the individual operations are known to have the same op +`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) | + + `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 | @@ -571,6 +582,17 @@ For batch operations, if the individual operations are known to have the same op +`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) | + + `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 | @@ -673,6 +695,17 @@ For batch operations, if the individual operations are known to have the same op +`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) | + + `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 | @@ -775,6 +808,17 @@ For batch operations, if the individual operations are known to have the same op +`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) | + + `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 | diff --git a/model/database/registry.yaml b/model/database/registry.yaml index 6b76a90fcf..3f5ec2fef7 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -535,7 +535,23 @@ groups: brief: Cosmos DB sub status code. examples: [1000, 1002] - id: db.cosmosdb.consistency_level - type: string + 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. examples: [Eventual, ConsistentPrefix, BoundedStaleness, Strong or Session] diff --git a/model/database/spans.yaml b/model/database/spans.yaml index cdac8e1059..81148971d1 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -701,3 +701,5 @@ groups: - ref: server.port requirement_level: conditionally_required: If not default (443). + - ref: db.cosmosdb.consistency_level + requirement_level: required From 0dac6eb63119e8ea56a18f3b036e89abcf6cfb69 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Tue, 1 Oct 2024 18:11:48 +0530 Subject: [PATCH 12/84] updatred toc --- docs/database/database-metrics.md | 128 ++++-------------------------- 1 file changed, 15 insertions(+), 113 deletions(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 352972a32c..8f125e20fd 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -23,6 +23,9 @@ linkTitle: Metrics - [Metric: `db.client.connection.create_time`](#metric-dbclientconnectioncreate_time) - [Metric: `db.client.connection.wait_time`](#metric-dbclientconnectionwait_time) - [Metric: `db.client.connection.use_time`](#metric-dbclientconnectionuse_time) + - [Metric: `db.cosmosdb.operation.request_charge`](#metric-dbcosmosdboperationrequest_charge) + - [Metric: `db.query.limit`](#metric-dbquerylimit) + - [Metric: `db.query.response.item_count`](#metric-dbqueryresponseitem_count) @@ -428,6 +431,10 @@ This metric is [recommended][MetricRecommended]. +### Metric: `db.cosmosdb.operation.request_charge` + +This metric is [recommended][MetricRecommended]. + @@ -541,6 +548,10 @@ For batch operations, if the individual operations are known to have the same op +### Metric: `db.query.limit` + +This metric is [recommended][MetricRecommended]. + @@ -654,120 +665,11 @@ For batch operations, if the individual operations are known to have the same op - - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | -| -------- | --------------- | ----------- | -------------- | --------- | -| `db.query.response.item_count` | Histogram | `{count}` | Actual item count returned by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed) | ![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 | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | `Required` | ![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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.consistency_level`](/docs/attributes-registry/db.md) | string | Account or Request Consistency Level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB status code. | `200`; `201` | `Required` | ![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` | `Required` | ![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. [2] | `customers`; `test.users` | `Required` | ![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] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [4] | `other_sql`; `adabas`; `cache` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![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. -If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. - -**[2]:** 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. - -**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. -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. - -**[4]:** 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. - -**[5]:** 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. - - - -`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) | - - -`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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mysql` | MySQL | ![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 | ![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) | - - +### Metric: `db.query.response.item_count` - - - - +This metric is [recommended][MetricRecommended]. - + @@ -776,7 +678,7 @@ For batch operations, if the individual operations are known to have the same op | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.cosmosdb.operation.request_charge` | Histogram | `{request_units}` | Request Charge consumed by the operation | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.query.response.item_count` | Histogram | `{count}` | Actual item count returned by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed) | ![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 | |---|---|---|---|---|---| From 0547b5a8df30edda6ff14f7f8d8c8593c2e75fee Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 2 Oct 2024 07:09:38 +0530 Subject: [PATCH 13/84] fix dimentions --- docs/database/database-metrics.md | 198 +++--------------------------- model/database/metrics.yaml | 2 - 2 files changed, 18 insertions(+), 182 deletions(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 8f125e20fd..515d4986cc 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -435,6 +435,10 @@ This metric is [recommended][MetricRecommended]. 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 `[ 3, 6, 9, 10, 50, 100]`. + @@ -455,8 +459,7 @@ This metric is [recommended][MetricRecommended]. | [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Required` | ![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. [2] | `customers`; `test.users` | `Required` | ![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] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [4] | `other_sql`; `adabas`; `cache` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![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. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. @@ -470,9 +473,7 @@ It is RECOMMENDED to capture the value as provided by the application without at If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. 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. -**[4]:** 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. - -**[5]:** 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. +**[4]:** 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. @@ -487,61 +488,6 @@ For batch operations, if the individual operations are known to have the same op | `Strong` | strong | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mysql` | MySQL | ![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 | ![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) | - - @@ -552,6 +498,10 @@ For batch operations, if the individual operations are known to have the same op 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 `[ 3, 6, 9, 10, 50, 100]`. + @@ -572,8 +522,7 @@ This metric is [recommended][MetricRecommended]. | [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Required` | ![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. [2] | `customers`; `test.users` | `Required` | ![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] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [4] | `other_sql`; `adabas`; `cache` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![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. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. @@ -587,9 +536,7 @@ It is RECOMMENDED to capture the value as provided by the application without at If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. 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. -**[4]:** 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. - -**[5]:** 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. +**[4]:** 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. @@ -604,61 +551,6 @@ For batch operations, if the individual operations are known to have the same op | `Strong` | strong | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mysql` | MySQL | ![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 | ![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) | - - @@ -669,6 +561,10 @@ For batch operations, if the individual operations are known to have the same op 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 `[ 3, 6, 9, 10, 50, 100]`. + @@ -689,8 +585,7 @@ This metric is [recommended][MetricRecommended]. | [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Required` | ![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. [2] | `customers`; `test.users` | `Required` | ![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] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [4] | `other_sql`; `adabas`; `cache` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![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. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. @@ -704,9 +599,7 @@ It is RECOMMENDED to capture the value as provided by the application without at If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. 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. -**[4]:** 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. - -**[5]:** 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. +**[4]:** 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. @@ -721,61 +614,6 @@ For batch operations, if the individual operations are known to have the same op | `Strong` | strong | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mysql` | MySQL | ![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 | ![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) | - - diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index a6791ac90d..1346295fa6 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -175,8 +175,6 @@ groups: type: attribute_group brief: 'Azure Cosmos DB attributes' attributes: - - ref: db.system - requirement_level: required - ref: db.collection.name requirement_level: required - ref: db.namespace From cc66b7761e39d9b34344cf0d71507ab4b278bc40 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 2 Oct 2024 15:40:18 +0530 Subject: [PATCH 14/84] better metrics name --- docs/attributes-registry/db.md | 10 + docs/database/cosmosdb.md | 3 +- docs/database/database-metrics.md | 446 +++++++++++++++++++++++---- model/database/cosmosdb-metrics.yaml | 57 ++++ model/database/metrics.yaml | 43 +-- model/database/registry.yaml | 6 + model/database/spans.yaml | 6 +- 7 files changed, 475 insertions(+), 96 deletions(-) create mode 100644 model/database/cosmosdb-metrics.yaml diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 4451bb29bb..ed628c5402 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -171,6 +171,16 @@ This group defines attributes for Azure Cosmos DB. | `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.sub_status_code` | int | Cosmos DB sub status code. | `1000`; `1002` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| ------------------------------------ | ------ | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `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.consistency_level` | string | Account or Request Consistency Level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.machine_id` | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | ![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.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. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 1a7c2aba1f..cf307fe32a 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -24,9 +24,10 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.cosmosdb.consistency_level`](/docs/attributes-registry/db.md) | string | Account or Request Consistency Level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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.consistency_level`](/docs/attributes-registry/db.md) | string | Account or Request Consistency Level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.machine_id`](/docs/attributes-registry/db.md) | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | `Conditionally Required` If available. | ![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.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) | diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 515d4986cc..04f3db32b9 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -13,7 +13,9 @@ linkTitle: Metrics - [Database operation](#database-operation) - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) - [Experimental](#experimental) - - [Connection pools](#connection-pools) + - [Metric: `db.query.limit`](#metric-dbquerylimit) + - [Metric: `db.query.response.item_count`](#metric-dbqueryresponseitem_count) +- [Connection pools](#connection-pools) - [Metric: `db.client.connection.count`](#metric-dbclientconnectioncount) - [Metric: `db.client.connection.idle.max`](#metric-dbclientconnectionidlemax) - [Metric: `db.client.connection.idle.min`](#metric-dbclientconnectionidlemin) @@ -23,9 +25,13 @@ linkTitle: Metrics - [Metric: `db.client.connection.create_time`](#metric-dbclientconnectioncreate_time) - [Metric: `db.client.connection.wait_time`](#metric-dbclientconnectionwait_time) - [Metric: `db.client.connection.use_time`](#metric-dbclientconnectionuse_time) +- [Azure Cosmos DB](#azure-cosmos-db) + - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration-1) + - [Metric: `db.query.limit`](#metric-dbquerylimit-1) + - [Metric: `db.query.response.item_count`](#metric-dbqueryresponseitem_count-1) - [Metric: `db.cosmosdb.operation.request_charge`](#metric-dbcosmosdboperationrequest_charge) - - [Metric: `db.query.limit`](#metric-dbquerylimit) - - [Metric: `db.query.response.item_count`](#metric-dbqueryresponseitem_count) + - [Metric: `db.cosmosdb.operation.regions_contacted`](#metric-dbcosmosdboperationregions_contacted) + - [Metric: `db.cosmosdb.client.active_instances`](#metric-dbcosmosdbclientactive_instances) @@ -196,6 +202,132 @@ If a database operation involved multiple network calls (for example retries), t |---|---|---| | `_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.query.limit` + +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 `[ 100, 500, 1000, 1500, 2000]`. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.query.limit` | Histogram | `{count}` | Max item count requested by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed) | ![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.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [3] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [4] | ![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. [5] | `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. [6] | `80`; `8080`; `443` | `Conditionally Required` [7] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [8] | `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. +If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. +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. + +**[2]:** If readily available. The operation name MAY be parsed from the query text, in which case it SHOULD be the first operation name found in the query. + +**[3]:** 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. + +**[4]:** If the operation failed and status code is available. + +**[5]:** 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. + +**[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]:** 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. + + + +`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.query.response.item_count` + +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 `[ 100, 500, 1000, 1500, 2000]`. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.query.response.item_count` | Histogram | `{count}` | Actual item count returned by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed) | ![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.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [3] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [4] | ![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. [5] | `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. [6] | `80`; `8080`; `443` | `Conditionally Required` [7] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [8] | `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. +If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. +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. + +**[2]:** If readily available. The operation name MAY be parsed from the query text, in which case it SHOULD be the first operation name found in the query. + +**[3]:** 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. + +**[4]:** If the operation failed and status code is available. + +**[5]:** 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. + +**[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]:** 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. + + + +`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) | + + + @@ -431,6 +563,40 @@ This metric is [recommended][MetricRecommended]. +## Azure Cosmos DB + +The following metric instruments describe Azure Cosmos DB client behaviour. + +### Metric: `db.client.operation.duration` + +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 `[ .010, .200, .400, .600, .800, 1.000 ]`. + +Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. + +### Metric: `db.query.limit` + +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 `[ 100, 500, 1000, 1500, 2000, 2500]`. + +Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. + +### Metric: `db.query.response.item_count` + +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 `[ 100, 500, 1000, 1500, 2000, 2500]`. + +Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. + ### Metric: `db.cosmosdb.operation.request_charge` This metric is [recommended][MetricRecommended]. @@ -452,28 +618,31 @@ of `[ 3, 6, 9, 10, 50, 100]`. | 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 | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | `Required` | ![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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.consistency_level`](/docs/attributes-registry/db.md) | string | Account or Request Consistency Level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB status code. | `200`; `201` | `Required` | ![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` | `Required` | ![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. [2] | `customers`; `test.users` | `Required` | ![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] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.machine_id`](/docs/attributes-registry/db.md) | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Deprecated, use `db.response.status_code` instead. | `200`; `201` | `Conditionally Required` if response was received | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.response.status_code`. | +| [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` if response was received | ![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.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [5] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. +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. + +**[2]:** 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. + +**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. -**[2]:** 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. +**[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. -**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. -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. - -**[4]:** 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. +**[5]:** 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. @@ -488,21 +657,76 @@ For batch operations, if the individual operations are known to have the same op | `Strong` | strong | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +`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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mysql` | MySQL | ![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 | ![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) | + + -### Metric: `db.query.limit` +### Metric: `db.cosmosdb.operation.regions_contacted` 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 `[ 3, 6, 9, 10, 50, 100]`. +of `[ 3, 6, 9, 10, 50]`. - + @@ -511,32 +735,35 @@ of `[ 3, 6, 9, 10, 50, 100]`. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.query.limit` | Histogram | `{count}` | Max item count requested by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.operation.regions_contacted` | Histogram | `{count}` | Number of regions contacted for 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 | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | `Required` | ![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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.consistency_level`](/docs/attributes-registry/db.md) | string | Account or Request Consistency Level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB status code. | `200`; `201` | `Required` | ![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` | `Required` | ![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. [2] | `customers`; `test.users` | `Required` | ![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] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.machine_id`](/docs/attributes-registry/db.md) | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Deprecated, use `db.response.status_code` instead. | `200`; `201` | `Conditionally Required` if response was received | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.response.status_code`. | +| [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` if response was received | ![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.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [5] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. +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. + +**[2]:** 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. + +**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. -**[2]:** 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. +**[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. -**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. -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. - -**[4]:** 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. +**[5]:** 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. @@ -551,21 +778,76 @@ For batch operations, if the individual operations are known to have the same op | `Strong` | strong | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +`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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mysql` | MySQL | ![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 | ![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) | + + -### Metric: `db.query.response.item_count` +### Metric: `db.cosmosdb.client.active_instances` 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 `[ 3, 6, 9, 10, 50, 100]`. +of `[ 2, 10, 50, 100]`. - + @@ -574,32 +856,35 @@ of `[ 3, 6, 9, 10, 50, 100]`. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.query.response.item_count` | Histogram | `{count}` | Actual item count returned by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.client.active_instances` | Histogram | `{count}` | Number of active client instance | ![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 | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | `Required` | ![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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.consistency_level`](/docs/attributes-registry/db.md) | string | Account or Request Consistency Level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB status code. | `200`; `201` | `Required` | ![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` | `Required` | ![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. [2] | `customers`; `test.users` | `Required` | ![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] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.machine_id`](/docs/attributes-registry/db.md) | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Deprecated, use `db.response.status_code` instead. | `200`; `201` | `Conditionally Required` if response was received | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.response.status_code`. | +| [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` if response was received | ![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.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [5] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. +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. + +**[2]:** 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. + +**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. -**[2]:** 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. +**[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. -**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. -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. - -**[4]:** 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. +**[5]:** 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. @@ -614,6 +899,61 @@ For batch operations, if the individual operations are known to have the same op | `Strong` | strong | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +`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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mysql` | MySQL | ![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 | ![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) | + + diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml new file mode 100644 index 0000000000..bc0dc959eb --- /dev/null +++ b/model/database/cosmosdb-metrics.yaml @@ -0,0 +1,57 @@ +groups: + - id: metric.db.cosmosdb.operation.request_charge + type: metric + metric_name: db.cosmosdb.operation.request_charge + brief: "Request Charge consumed by the operation" + instrument: histogram + unit: "{request_units}" + stability: experimental + extends: attributes.db.cosmosdb.minimal + + - id: metric.db.cosmosdb.operation.regions_contacted + type: metric + metric_name: db.cosmosdb.operation.regions_contacted + brief: "Number of regions contacted for the operation" + instrument: histogram + unit: "{count}" + stability: experimental + extends: attributes.db.cosmosdb.minimal + + - id: metric.db.cosmosdb.client.active_instances + type: metric + metric_name: db.cosmosdb.client.active_instances + brief: "Number of active client instance" + instrument: histogram + unit: "{count}" + stability: experimental + extends: attributes.db.cosmosdb.minimal + + - id: attributes.db.cosmosdb.minimal + type: attribute_group + brief: 'Azure Cosmos DB attributes' + attributes: + - ref: db.system + requirement_level: + conditionally_required: if available + - ref: db.collection.name + requirement_level: + conditionally_required: if available + - ref: db.namespace + requirement_level: + conditionally_required: If available. + - ref: db.operation.name + requirement_level: required + - ref: server.address + requirement_level: required + - ref: db.cosmosdb.status_code + requirement_level: + conditionally_required: if response was received + - ref: db.cosmosdb.sub_status_code + requirement_level: + conditionally_required: if response was received + - ref: db.cosmosdb.consistency_level + requirement_level: + conditionally_required: If available. + - ref: db.cosmosdb.machine_id + requirement_level: + conditionally_required: If available. diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index 1346295fa6..05a8638639 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -135,15 +135,6 @@ groups: - ref: db.client.connection.pool.name requirement_level: required - - id: metric.db.cosmosdb.operation.request_charge - type: metric - metric_name: db.cosmosdb.operation.request_charge - brief: "Request Charge consumed by the operation" - instrument: histogram - unit: "{request_units}" - stability: experimental - extends: attributes.db.cosmosdb.minimal - - id: metric.db.query.limit type: metric metric_name: db.query.limit @@ -151,7 +142,7 @@ groups: instrument: histogram unit: "{count}" stability: experimental - extends: attributes.db.cosmosdb.minimal + extends: attributes.db.client.minimal - id: metric.db.query.response.item_count type: metric @@ -160,34 +151,4 @@ groups: instrument: histogram unit: "{count}" stability: experimental - extends: attributes.db.cosmosdb.minimal - - - id: metric.db.cosmosdb.operation.regions_contacted - type: metric - metric_name: db.cosmosdb.operation.regions_contacted - brief: "Number of regions contacted for the operation" - instrument: histogram - unit: "{count}" - stability: experimental - extends: attributes.db.cosmosdb.minimal - - - id: attributes.db.cosmosdb.minimal - type: attribute_group - brief: 'Azure Cosmos DB attributes' - attributes: - - ref: db.collection.name - requirement_level: required - - ref: db.namespace - requirement_level: required - - ref: db.operation.name - requirement_level: required - - ref: server.address - requirement_level: required - - ref: db.cosmosdb.status_code - requirement_level: required - - ref: db.cosmosdb.sub_status_code - requirement_level: required - - ref: db.cosmosdb.client_id - requirement_level: required - - ref: db.cosmosdb.consistency_level - requirement_level: required + extends: attributes.db.client.minimal diff --git a/model/database/registry.yaml b/model/database/registry.yaml index 3f5ec2fef7..d5c28b54d9 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -555,6 +555,12 @@ groups: stability: experimental brief: Account or Request Consistency Level. examples: [Eventual, ConsistentPrefix, BoundedStaleness, Strong or Session] + - id: db.cosmosdb.machine_id + type: string + stability: experimental + brief: Azure VM Id or hashed machine name or unique generate GUID, whatever is available. + examples: ["vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918", "hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4", "uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042" ] + - id: registry.db.elasticsearch type: attribute_group display_name: Elasticsearch Attributes diff --git a/model/database/spans.yaml b/model/database/spans.yaml index 81148971d1..b0214b382f 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -702,4 +702,8 @@ groups: requirement_level: conditionally_required: If not default (443). - ref: db.cosmosdb.consistency_level - requirement_level: required + requirement_level: + conditionally_required: If available. + - ref: db.cosmosdb.machine_id + requirement_level: + conditionally_required: If available. From fb44bc1f87e917f39ef69d8cb0fd32933a016fca Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Thu, 3 Oct 2024 06:14:33 +0530 Subject: [PATCH 15/84] Update model/database/cosmosdb-metrics.yaml Co-authored-by: Justine Cocchi --- model/database/cosmosdb-metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml index bc0dc959eb..a73afff5bd 100644 --- a/model/database/cosmosdb-metrics.yaml +++ b/model/database/cosmosdb-metrics.yaml @@ -2,7 +2,7 @@ groups: - id: metric.db.cosmosdb.operation.request_charge type: metric metric_name: db.cosmosdb.operation.request_charge - brief: "Request Charge consumed by the operation" + brief: "Request charge consumed by the operation." instrument: histogram unit: "{request_units}" stability: experimental From 2535df1dcd6e099dede75ba2e1abdd16ff70e035 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Thu, 3 Oct 2024 06:14:41 +0530 Subject: [PATCH 16/84] Update model/database/cosmosdb-metrics.yaml Co-authored-by: Justine Cocchi --- model/database/cosmosdb-metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml index a73afff5bd..ee48c52500 100644 --- a/model/database/cosmosdb-metrics.yaml +++ b/model/database/cosmosdb-metrics.yaml @@ -20,7 +20,7 @@ groups: - id: metric.db.cosmosdb.client.active_instances type: metric metric_name: db.cosmosdb.client.active_instances - brief: "Number of active client instance" + brief: "Number of active client instances" instrument: histogram unit: "{count}" stability: experimental From dcf101bbb8c5820d0e76d0acf0999c7c977cbbeb Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Thu, 3 Oct 2024 06:15:03 +0530 Subject: [PATCH 17/84] Update model/database/registry.yaml Co-authored-by: Justine Cocchi --- model/database/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/registry.yaml b/model/database/registry.yaml index d5c28b54d9..ff8ad0f93f 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -553,7 +553,7 @@ groups: value: "ConsistentPrefix" stability: experimental stability: experimental - brief: Account or Request Consistency Level. + brief: Account or request consistency level. examples: [Eventual, ConsistentPrefix, BoundedStaleness, Strong or Session] - id: db.cosmosdb.machine_id type: string From 70fb428df410b8cfe3600de57c7ac3ec984991b8 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Thu, 3 Oct 2024 06:21:03 +0530 Subject: [PATCH 18/84] fix typos --- docs/attributes-registry/db.md | 2 +- docs/database/cosmosdb.md | 2 +- docs/database/database-metrics.md | 10 +++++----- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index ed628c5402..202ea83a1a 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -175,7 +175,7 @@ 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.consistency_level` | string | Account or Request Consistency Level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.consistency_level` | string | Account or request consistency level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.cosmosdb.machine_id` | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | ![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) | diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index cf307fe32a..3c2fb78f45 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -26,7 +26,7 @@ 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.consistency_level`](/docs/attributes-registry/db.md) | string | Account or Request Consistency Level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.machine_id`](/docs/attributes-registry/db.md) | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | `Conditionally Required` If available. | ![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) | diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 04f3db32b9..4065fbcc9a 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -614,14 +614,14 @@ of `[ 3, 6, 9, 10, 50, 100]`. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.cosmosdb.operation.request_charge` | Histogram | `{request_units}` | Request Charge consumed by the operation | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.operation.request_charge` | Histogram | `{request_units}` | Request charge 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.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.machine_id`](/docs/attributes-registry/db.md) | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Deprecated, use `db.response.status_code` instead. | `200`; `201` | `Conditionally Required` if response was received | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.response.status_code`. | | [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -742,7 +742,7 @@ of `[ 3, 6, 9, 10, 50]`. | [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.machine_id`](/docs/attributes-registry/db.md) | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Deprecated, use `db.response.status_code` instead. | `200`; `201` | `Conditionally Required` if response was received | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.response.status_code`. | | [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -856,14 +856,14 @@ of `[ 2, 10, 50, 100]`. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.cosmosdb.client.active_instances` | Histogram | `{count}` | Number of active client instance | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.client.active_instances` | Histogram | `{count}` | 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 | |---|---|---|---|---|---| | [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.machine_id`](/docs/attributes-registry/db.md) | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Deprecated, use `db.response.status_code` instead. | `200`; `201` | `Conditionally Required` if response was received | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.response.status_code`. | | [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | From 67d92efb64b703418ab2b26a1939b4d52511aa3d Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Thu, 3 Oct 2024 07:35:01 +0530 Subject: [PATCH 19/84] improved docuemnation --- docs/database/database-metrics.md | 48 ++++++++++++++++++++++--------- 1 file changed, 34 insertions(+), 14 deletions(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 4065fbcc9a..33b2628ce7 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -569,37 +569,57 @@ The following metric instruments describe Azure Cosmos DB client behaviour. ### Metric: `db.client.operation.duration` -This metric is [recommended][MetricRecommended]. +It captures the total time taken by an Azure Cosmos DB operation. This metric follows the common [db.client.operation.duration] (#metric-dbclientoperationduration)b definition. -this metric SHOULD be specified with +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 `[ .010, .200, .400, .600, .800, 1.000 ]`. +of `[ 0.001, 0.005, 0.010, 0.050, 0.100, 0.200, 0.500, 1.000, 2.000, 5.000 ]`. + +Explaining bucket configuration: + +1. 0.001, 0.005, 0.010 seconds: : These boundaries provide high precision for high-performance workloads, especially when dealing with microservices or low-latency queries. +2. 0.050, 0.100, 0.200 seconds: These intervals capture typical latencies between 50ms and 200ms, common in web applications, offering detailed tracking for normal operational performance. +3. 0.500, 1.000 seconds: These boundaries identify operations that take longer, highlighting potential bottlenecks or slower requests that may need optimization. +4. 2.000, 5.000 seconds: Although Azure Cosmos DB is optimized for sub-second latencies, these buckets are included to track rare, long-running outliers that might exceed 1 second. Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. ### Metric: `db.query.limit` -This metric is [recommended][MetricRecommended]. +It captures the requested page size for Query or Feed operations in Azure Cosmos DB. It helps in identifying patterns in page size requests that could contribute to higher latencies or other performance issues. -this metric SHOULD be specified with +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 `[ 100, 500, 1000, 1500, 2000, 2500]`. +of `[50, 100, 250, 500, 1000, 2000, 5000]`. + +Explaining bucket configuration: + +1. 50, 100, 250, 500: These small page sizes are common for lightweight queries where quick responses are essential, such as in real-time applications. +2. 1000, 2000: These boundaries capture scenarios where larger datasets are returned in fewer queries, which can be more efficient but might result in longer query execution times. +3. 5000: This boundary is used to capture rare cases where very large page sizes are requested. Although Cosmos DB generally handles larger datasets efficiently, large page sizes can sometimes lead to performance bottlenecks due to increased processing times or network bandwidth limitations. Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. ### Metric: `db.query.response.item_count` -This metric is [recommended][MetricRecommended]. +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 SHOULD be specified with +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 `[ 100, 500, 1000, 1500, 2000, 2500]`. +of `[10, 50, 100, 250, 500, 1000, 2000, 5000, 10000]`. + +Explaining bucket configuration: + +1. 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. 250, 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. Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. ### Metric: `db.cosmosdb.operation.request_charge` -This metric is [recommended][MetricRecommended]. +It captures the Request Units consumed by each operation in Azure Cosmos DB. Since Request Units serve as a form of currency 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) @@ -720,11 +740,11 @@ It is RECOMMENDED to capture the value as provided by the application without at ### Metric: `db.cosmosdb.operation.regions_contacted` -This metric is [recommended][MetricRecommended]. +It captures the number of regions contacted by the SDK in a multi-region setup. Understanding the SDK's interaction with multiple regions is crucial, as it may contribute to higher latency. In a single-region setup, this value will remain at 1 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 `[ 3, 6, 9, 10, 50]`. +of `[1, 2, 3, 5, 10, 20, 50]`. @@ -841,11 +861,11 @@ It is RECOMMENDED to capture the value as provided by the application without at ### Metric: `db.cosmosdb.client.active_instances` -This metric is [recommended][MetricRecommended]. +It aptures 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 process. Having multiple instances of the SDK client can lead to CPU or memory-related issues. 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 `[ 2, 10, 50, 100]`. +of `[1, 2, 3, 5, 10, 50, 100]`. From ffbe79705c541c0f00d36060b7935e9aaf1e3c57 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Thu, 3 Oct 2024 07:37:10 +0530 Subject: [PATCH 20/84] fixed documenation --- docs/database/database-metrics.md | 31 ++++++++++++++++++---------- model/database/cosmosdb-metrics.yaml | 2 +- 2 files changed, 21 insertions(+), 12 deletions(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 33b2628ce7..442014dc8b 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -573,7 +573,7 @@ It captures the total time taken by an Azure Cosmos DB operation. This metric fo 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 `[ 0.001, 0.005, 0.010, 0.050, 0.100, 0.200, 0.500, 1.000, 2.000, 5.000 ]`. +of `[0.001, 0.005, 0.010, 0.050, 0.100, 0.200, 0.500, 1.000, 2.000, 5.000]`. Explaining bucket configuration: @@ -612,7 +612,7 @@ Explaining bucket configuration: 1. 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. 250, 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. +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. Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. @@ -643,10 +643,10 @@ of `[ 3, 6, 9, 10, 50, 100]`. | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.machine_id`](/docs/attributes-registry/db.md) | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Deprecated, use `db.response.status_code` instead. | `200`; `201` | `Conditionally Required` if response was received | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.response.status_code`. | | [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` if response was received | ![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.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [5] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [6] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. @@ -662,7 +662,10 @@ For batch operations, if the individual operations are known to have the same co 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. -**[5]:** 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. +**[5]:** 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. + +**[6]:** 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. @@ -764,10 +767,10 @@ of `[1, 2, 3, 5, 10, 20, 50]`. | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.machine_id`](/docs/attributes-registry/db.md) | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Deprecated, use `db.response.status_code` instead. | `200`; `201` | `Conditionally Required` if response was received | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.response.status_code`. | | [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` if response was received | ![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.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [5] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [6] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. @@ -783,7 +786,10 @@ For batch operations, if the individual operations are known to have the same co 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. -**[5]:** 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. +**[5]:** 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. + +**[6]:** 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. @@ -885,10 +891,10 @@ of `[1, 2, 3, 5, 10, 50, 100]`. | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.machine_id`](/docs/attributes-registry/db.md) | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.status_code`](/docs/attributes-registry/db.md) | int | Deprecated, use `db.response.status_code` instead. | `200`; `201` | `Conditionally Required` if response was received | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.response.status_code`. | | [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` if response was received | ![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.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [5] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [6] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. @@ -904,7 +910,10 @@ For batch operations, if the individual operations are known to have the same co 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. -**[5]:** 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. +**[5]:** 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. + +**[6]:** 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. diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml index ee48c52500..568e78eb98 100644 --- a/model/database/cosmosdb-metrics.yaml +++ b/model/database/cosmosdb-metrics.yaml @@ -43,7 +43,7 @@ groups: requirement_level: required - ref: server.address requirement_level: required - - ref: db.cosmosdb.status_code + - ref: db.response.status_code requirement_level: conditionally_required: if response was received - ref: db.cosmosdb.sub_status_code From 891a62b3149590bd569bfd9d9cf9a7d0bfd342b0 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Mon, 7 Oct 2024 07:26:13 +0530 Subject: [PATCH 21/84] Update model/database/metrics.yaml Co-authored-by: Liudmila Molkova --- model/database/metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index 05a8638639..d8b9b9f0dc 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -147,7 +147,7 @@ groups: - id: metric.db.query.response.item_count type: metric metric_name: db.query.response.item_count - brief: "Actual item count returned by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed)" + brief: "The actual number of records returned by the query." instrument: histogram unit: "{count}" stability: experimental From f1625656357aaad7b63b06bbcaf78bf0f32acf78 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Mon, 7 Oct 2024 07:45:42 +0530 Subject: [PATCH 22/84] addressed comments --- docs/database/cosmosdb.md | 434 ++++++++++++++++++++++++++- docs/database/database-metrics.md | 426 -------------------------- model/database/cosmosdb-metrics.yaml | 6 +- model/database/registry.yaml | 5 - model/database/spans.yaml | 3 - 5 files changed, 436 insertions(+), 438 deletions(-) diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 3c2fb78f45..6fe811828f 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -27,7 +27,6 @@ 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.consistency_level`](/docs/attributes-registry/db.md) | string | Account or request consistency level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.machine_id`](/docs/attributes-registry/db.md) | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | `Conditionally Required` If available. | ![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.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) | @@ -286,4 +285,437 @@ and SHOULD be provided **at span creation time** (if provided at all): | `db.cosmosdb.sub_status_code` | `0` | | `db.cosmosdb.request_charge` | `7.43` | + +## Azure Cosmos DB + +The following metric instruments describe Azure Cosmos DB client behaviour. + +### Metric: `db.client.operation.duration` + +It captures the total time taken by an Azure Cosmos DB operation. This metric follows the common [db.client.operation.duration] (#metric-dbclientoperationduration)b definition. + +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 `[0.001, 0.005, 0.010, 0.050, 0.100, 0.200, 0.500, 1.000, 2.000, 5.000]`. + +Explaining bucket configuration: + +1. 0.001, 0.005, 0.010 seconds: : These boundaries provide high precision for high-performance workloads, especially when dealing with microservices or low-latency queries. +2. 0.050, 0.100, 0.200 seconds: These intervals capture typical latencies between 50ms and 200ms, common in web applications, offering detailed tracking for normal operational performance. +3. 0.500, 1.000 seconds: These boundaries identify operations that take longer, highlighting potential bottlenecks or slower requests that may need optimization. +4. 2.000, 5.000 seconds: Although Azure Cosmos DB is optimized for sub-second latencies, these buckets are included to track rare, long-running outliers that might exceed 1 second. + +Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. + +### Metric: `db.query.limit` + +It captures the requested page size for Query or Feed operations in Azure Cosmos DB. It helps in identifying patterns in page size requests that could contribute to higher latencies or other performance issues. + +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 `[50, 100, 250, 500, 1000, 2000, 5000]`. + +Explaining bucket configuration: + +1. 50, 100, 250, 500: These small page sizes are common for lightweight queries where quick responses are essential, such as in real-time applications. +2. 1000, 2000: These boundaries capture scenarios where larger datasets are returned in fewer queries, which can be more efficient but might result in longer query execution times. +3. 5000: This boundary is used to capture rare cases where very large page sizes are requested. Although Cosmos DB generally handles larger datasets efficiently, large page sizes can sometimes lead to performance bottlenecks due to increased processing times or network bandwidth limitations. + +Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. + +### Metric: `db.query.response.item_count` + +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 SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters) +of `[10, 50, 100, 250, 500, 1000, 2000, 5000, 10000]`. + +Explaining bucket configuration: + +1. 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. 250, 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. + +Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. + +### Metric: `db.cosmosdb.operation.request_charge` + +It captures the Request Units consumed by each operation in Azure Cosmos DB. Since Request Units serve as a form of currency 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 `[ 3, 6, 9, 10, 50, 100]`. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.cosmosdb.operation.request_charge` | Histogram | `{request_units}` | Request charge 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.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or 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` if response was received | ![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.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [6] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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) | + +**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. +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. + +**[2]:** 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. + +**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. + +**[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. + +**[5]:** 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. + +**[6]:** 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. + +**[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. + + + +`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) | + + +`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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mysql` | MySQL | ![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 | ![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) | + + + + + + + + +### Metric: `db.cosmosdb.operation.regions_contacted` + +It captures the number of regions contacted by the SDK in a multi-region setup. Understanding the SDK's interaction with multiple regions is crucial, as it may contribute to higher latency. In a single-region setup, this value will remain at 1 + +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, 3, 5, 10, 20, 50]`. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.cosmosdb.operation.regions_contacted` | Histogram | `{count}` | Number of regions contacted for 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.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or 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` if response was received | ![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.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [6] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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) | + +**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. +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. + +**[2]:** 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. + +**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. + +**[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. + +**[5]:** 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. + +**[6]:** 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. + +**[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. + + + +`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) | + + +`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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mysql` | MySQL | ![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 | ![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) | + + + + + + + + +### Metric: `db.cosmosdb.client.active_instances` + +It aptures 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 process. Having multiple instances of the SDK client can lead to CPU or memory-related issues. + +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, 3, 5, 10, 50, 100]`. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.cosmosdb.client.active_instances` | Histogram | `{count}` | 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 | +|---|---|---|---|---|---| +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or 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` if response was received | ![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.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [6] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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) | + +**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. +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. + +**[2]:** 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. + +**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. + +**[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. + +**[5]:** 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. + +**[6]:** 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. + +**[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. + + + +`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) | + + +`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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mysql` | MySQL | ![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 | ![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) | + + + + + + + + [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 442014dc8b..65d7562fd9 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -558,432 +558,6 @@ This metric is [recommended][MetricRecommended]. |---|---|---|---|---|---| | [`db.client.connection.pool.name`](/docs/attributes-registry/db.md) | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation SHOULD use a combination of parameters that would make the name unique, for example, combining attributes `server.address`, `server.port`, and `db.namespace`, formatted as `server.address:server.port/db.namespace`. Instrumentations that generate connection pool name following different patterns SHOULD document it. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - - - - - -## Azure Cosmos DB - -The following metric instruments describe Azure Cosmos DB client behaviour. - -### Metric: `db.client.operation.duration` - -It captures the total time taken by an Azure Cosmos DB operation. This metric follows the common [db.client.operation.duration] (#metric-dbclientoperationduration)b definition. - -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 `[0.001, 0.005, 0.010, 0.050, 0.100, 0.200, 0.500, 1.000, 2.000, 5.000]`. - -Explaining bucket configuration: - -1. 0.001, 0.005, 0.010 seconds: : These boundaries provide high precision for high-performance workloads, especially when dealing with microservices or low-latency queries. -2. 0.050, 0.100, 0.200 seconds: These intervals capture typical latencies between 50ms and 200ms, common in web applications, offering detailed tracking for normal operational performance. -3. 0.500, 1.000 seconds: These boundaries identify operations that take longer, highlighting potential bottlenecks or slower requests that may need optimization. -4. 2.000, 5.000 seconds: Although Azure Cosmos DB is optimized for sub-second latencies, these buckets are included to track rare, long-running outliers that might exceed 1 second. - -Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. - -### Metric: `db.query.limit` - -It captures the requested page size for Query or Feed operations in Azure Cosmos DB. It helps in identifying patterns in page size requests that could contribute to higher latencies or other performance issues. - -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 `[50, 100, 250, 500, 1000, 2000, 5000]`. - -Explaining bucket configuration: - -1. 50, 100, 250, 500: These small page sizes are common for lightweight queries where quick responses are essential, such as in real-time applications. -2. 1000, 2000: These boundaries capture scenarios where larger datasets are returned in fewer queries, which can be more efficient but might result in longer query execution times. -3. 5000: This boundary is used to capture rare cases where very large page sizes are requested. Although Cosmos DB generally handles larger datasets efficiently, large page sizes can sometimes lead to performance bottlenecks due to increased processing times or network bandwidth limitations. - -Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. - -### Metric: `db.query.response.item_count` - -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 SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters) -of `[10, 50, 100, 250, 500, 1000, 2000, 5000, 10000]`. - -Explaining bucket configuration: - -1. 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. 250, 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. - -Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. - -### Metric: `db.cosmosdb.operation.request_charge` - -It captures the Request Units consumed by each operation in Azure Cosmos DB. Since Request Units serve as a form of currency 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 `[ 3, 6, 9, 10, 50, 100]`. - - - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | -| -------- | --------------- | ----------- | -------------- | --------- | -| `db.cosmosdb.operation.request_charge` | Histogram | `{request_units}` | Request charge 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.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.machine_id`](/docs/attributes-registry/db.md) | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | `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` if response was received | ![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.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [6] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. -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. - -**[2]:** 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. - -**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. - -**[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. - -**[5]:** 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. - -**[6]:** 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. - - - -`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) | - - -`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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mysql` | MySQL | ![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 | ![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) | - - - - - - - - -### Metric: `db.cosmosdb.operation.regions_contacted` - -It captures the number of regions contacted by the SDK in a multi-region setup. Understanding the SDK's interaction with multiple regions is crucial, as it may contribute to higher latency. In a single-region setup, this value will remain at 1 - -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, 3, 5, 10, 20, 50]`. - - - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | -| -------- | --------------- | ----------- | -------------- | --------- | -| `db.cosmosdb.operation.regions_contacted` | Histogram | `{count}` | Number of regions contacted for 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.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.machine_id`](/docs/attributes-registry/db.md) | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | `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` if response was received | ![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.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [6] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. -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. - -**[2]:** 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. - -**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. - -**[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. - -**[5]:** 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. - -**[6]:** 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. - - - -`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) | - - -`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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mysql` | MySQL | ![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 | ![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) | - - - - - - - - -### Metric: `db.cosmosdb.client.active_instances` - -It aptures 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 process. Having multiple instances of the SDK client can lead to CPU or memory-related issues. - -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, 3, 5, 10, 50, 100]`. - - - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | -| -------- | --------------- | ----------- | -------------- | --------- | -| `db.cosmosdb.client.active_instances` | Histogram | `{count}` | 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 | -|---|---|---|---|---|---| -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.cosmosdb.machine_id`](/docs/attributes-registry/db.md) | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | `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` if response was received | ![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.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [6] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. -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. - -**[2]:** 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. - -**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. - -**[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. - -**[5]:** 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. - -**[6]:** 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. - - - -`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) | - - -`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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mysql` | MySQL | ![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 | ![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) | - - - diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml index 568e78eb98..39bd8a5f7f 100644 --- a/model/database/cosmosdb-metrics.yaml +++ b/model/database/cosmosdb-metrics.yaml @@ -33,6 +33,9 @@ groups: - ref: db.system requirement_level: conditionally_required: if available + - ref: server.port + requirement_level: + conditionally_required: If not default (443). - ref: db.collection.name requirement_level: conditionally_required: if available @@ -52,6 +55,3 @@ groups: - ref: db.cosmosdb.consistency_level requirement_level: conditionally_required: If available. - - ref: db.cosmosdb.machine_id - requirement_level: - conditionally_required: If available. diff --git a/model/database/registry.yaml b/model/database/registry.yaml index ff8ad0f93f..dd6b9f8d6e 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -555,11 +555,6 @@ groups: stability: experimental brief: Account or request consistency level. examples: [Eventual, ConsistentPrefix, BoundedStaleness, Strong or Session] - - id: db.cosmosdb.machine_id - type: string - stability: experimental - brief: Azure VM Id or hashed machine name or unique generate GUID, whatever is available. - examples: ["vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918", "hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4", "uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042" ] - id: registry.db.elasticsearch type: attribute_group diff --git a/model/database/spans.yaml b/model/database/spans.yaml index b0214b382f..f0415725eb 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -704,6 +704,3 @@ groups: - ref: db.cosmosdb.consistency_level requirement_level: conditionally_required: If available. - - ref: db.cosmosdb.machine_id - requirement_level: - conditionally_required: If available. From 10ecde0606f44b692f81ab311033cc7d8a8fa55c Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Mon, 7 Oct 2024 10:53:30 +0530 Subject: [PATCH 23/84] toc update --- docs/database/cosmosdb.md | 1 - docs/database/database-metrics.md | 7 ------- 2 files changed, 8 deletions(-) diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 6fe811828f..1c72e44af5 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -285,7 +285,6 @@ and SHOULD be provided **at span creation time** (if provided at all): | `db.cosmosdb.sub_status_code` | `0` | | `db.cosmosdb.request_charge` | `7.43` | - ## Azure Cosmos DB The following metric instruments describe Azure Cosmos DB client behaviour. diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 65d7562fd9..2b54c03471 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -25,13 +25,6 @@ linkTitle: Metrics - [Metric: `db.client.connection.create_time`](#metric-dbclientconnectioncreate_time) - [Metric: `db.client.connection.wait_time`](#metric-dbclientconnectionwait_time) - [Metric: `db.client.connection.use_time`](#metric-dbclientconnectionuse_time) -- [Azure Cosmos DB](#azure-cosmos-db) - - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration-1) - - [Metric: `db.query.limit`](#metric-dbquerylimit-1) - - [Metric: `db.query.response.item_count`](#metric-dbqueryresponseitem_count-1) - - [Metric: `db.cosmosdb.operation.request_charge`](#metric-dbcosmosdboperationrequest_charge) - - [Metric: `db.cosmosdb.operation.regions_contacted`](#metric-dbcosmosdboperationregions_contacted) - - [Metric: `db.cosmosdb.client.active_instances`](#metric-dbcosmosdbclientactive_instances) From e996837535c97b178709faab9a92938f4cbd8304 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 9 Oct 2024 17:38:26 +0530 Subject: [PATCH 24/84] fix merge rebase --- docs/database/cosmosdb.md | 39 +++++++++++++++++++++---------- docs/database/database-metrics.md | 12 ++++++---- 2 files changed, 35 insertions(+), 16 deletions(-) diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 1c72e44af5..ea2c466018 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -373,21 +373,26 @@ of `[ 3, 6, 9, 10, 50, 100]`. **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. 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. **[2]:** 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. **[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. +This attribute has stability level RELEASE CANDIDATE. **[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]:** 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. **[6]:** 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. **[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. @@ -434,12 +439,12 @@ Semantic conventions for individual database systems SHOULD document what `db.re | `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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mysql` | MySQL | ![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) | @@ -447,7 +452,7 @@ Semantic conventions for individual database systems SHOULD document what `db.re | `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 | ![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) | @@ -499,21 +504,26 @@ of `[1, 2, 3, 5, 10, 20, 50]`. **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. 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. **[2]:** 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. **[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. +This attribute has stability level RELEASE CANDIDATE. **[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]:** 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. **[6]:** 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. **[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. @@ -560,12 +570,12 @@ Semantic conventions for individual database systems SHOULD document what `db.re | `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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mysql` | MySQL | ![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) | @@ -573,7 +583,7 @@ Semantic conventions for individual database systems SHOULD document what `db.re | `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 | ![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) | @@ -625,21 +635,26 @@ of `[1, 2, 3, 5, 10, 50, 100]`. **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. 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. **[2]:** 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. **[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. +This attribute has stability level RELEASE CANDIDATE. **[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]:** 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. **[6]:** 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. **[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. @@ -686,12 +701,12 @@ Semantic conventions for individual database systems SHOULD document what `db.re | `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 | ![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 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mysql` | MySQL | ![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) | @@ -699,7 +714,7 @@ Semantic conventions for individual database systems SHOULD document what `db.re | `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 | ![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) | diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 2b54c03471..3dae9e03d8 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -12,10 +12,10 @@ linkTitle: Metrics - [Database operation](#database-operation) - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) -- [Experimental](#experimental) - - [Metric: `db.query.limit`](#metric-dbquerylimit) + - [Metric: `db.query.limit`](#metric-dbquerylimit) - [Metric: `db.query.response.item_count`](#metric-dbqueryresponseitem_count) -- [Connection pools](#connection-pools) +- [Experimental](#experimental) + - [Connection pools](#connection-pools) - [Metric: `db.client.connection.count`](#metric-dbclientconnectioncount) - [Metric: `db.client.connection.idle.max`](#metric-dbclientconnectionidlemax) - [Metric: `db.client.connection.idle.min`](#metric-dbclientconnectionidlemin) @@ -230,11 +230,13 @@ of `[ 100, 500, 1000, 1500, 2000]`. **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. 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. **[2]:** If readily available. The operation name MAY be parsed from the query text, in which case it SHOULD be the first operation name found in the query. **[3]:** 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. **[4]:** If the operation failed and status code is available. @@ -280,7 +282,7 @@ of `[ 100, 500, 1000, 1500, 2000]`. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.query.response.item_count` | Histogram | `{count}` | Actual item count returned by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.query.response.item_count` | Histogram | `{count}` | The actual number of records returned by the query. | ![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 | |---|---|---|---|---|---| @@ -293,11 +295,13 @@ of `[ 100, 500, 1000, 1500, 2000]`. **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. 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. **[2]:** If readily available. The operation name MAY be parsed from the query text, in which case it SHOULD be the first operation name found in the query. **[3]:** 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. **[4]:** If the operation failed and status code is available. From 167618e9e3b2e69beb3757a8091bc3ea0f8a17d8 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 9 Oct 2024 19:07:20 +0530 Subject: [PATCH 25/84] wip --- docs/database/cassandra.md | 1 - docs/database/cosmosdb.md | 460 --------------------------- docs/database/couchdb.md | 1 - docs/database/database-metrics.md | 132 -------- docs/database/database-spans.md | 1 - docs/database/elasticsearch.md | 1 - docs/database/hbase.md | 1 - docs/database/mariadb.md | 1 - docs/database/mongodb.md | 1 - docs/database/mssql.md | 1 - docs/database/mysql.md | 1 - docs/database/postgresql.md | 1 - docs/database/redis.md | 1 - docs/database/sql.md | 1 - docs/messaging/azure-messaging.md | 4 +- docs/messaging/gcp-pubsub.md | 2 +- docs/messaging/kafka.md | 2 +- docs/messaging/messaging-metrics.md | 2 +- docs/messaging/messaging-spans.md | 2 +- docs/messaging/rabbitmq.md | 2 +- docs/messaging/rocketmq.md | 2 +- model/database/cosmosdb-metrics.yaml | 9 - 22 files changed, 8 insertions(+), 621 deletions(-) diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index 505819847b..fb99e5b2bf 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -74,7 +74,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[10]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[11]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[12]:** 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. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index ea2c466018..ac84531f4b 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -26,7 +26,6 @@ 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.consistency_level`](/docs/attributes-registry/db.md) | string | Account or request consistency level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![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.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) | @@ -187,7 +186,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[8]:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.DocumentDB` for all operations performed by Cosmos DB client. **[9]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[10]:** 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. @@ -224,17 +222,6 @@ and SHOULD be provided **at span creation time** (if provided at all): | `gateway` | Gateway (HTTP) connections mode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`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) | - - `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 | @@ -285,451 +272,4 @@ and SHOULD be provided **at span creation time** (if provided at all): | `db.cosmosdb.sub_status_code` | `0` | | `db.cosmosdb.request_charge` | `7.43` | -## Azure Cosmos DB - -The following metric instruments describe Azure Cosmos DB client behaviour. - -### Metric: `db.client.operation.duration` - -It captures the total time taken by an Azure Cosmos DB operation. This metric follows the common [db.client.operation.duration] (#metric-dbclientoperationduration)b definition. - -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 `[0.001, 0.005, 0.010, 0.050, 0.100, 0.200, 0.500, 1.000, 2.000, 5.000]`. - -Explaining bucket configuration: - -1. 0.001, 0.005, 0.010 seconds: : These boundaries provide high precision for high-performance workloads, especially when dealing with microservices or low-latency queries. -2. 0.050, 0.100, 0.200 seconds: These intervals capture typical latencies between 50ms and 200ms, common in web applications, offering detailed tracking for normal operational performance. -3. 0.500, 1.000 seconds: These boundaries identify operations that take longer, highlighting potential bottlenecks or slower requests that may need optimization. -4. 2.000, 5.000 seconds: Although Azure Cosmos DB is optimized for sub-second latencies, these buckets are included to track rare, long-running outliers that might exceed 1 second. - -Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. - -### Metric: `db.query.limit` - -It captures the requested page size for Query or Feed operations in Azure Cosmos DB. It helps in identifying patterns in page size requests that could contribute to higher latencies or other performance issues. - -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 `[50, 100, 250, 500, 1000, 2000, 5000]`. - -Explaining bucket configuration: - -1. 50, 100, 250, 500: These small page sizes are common for lightweight queries where quick responses are essential, such as in real-time applications. -2. 1000, 2000: These boundaries capture scenarios where larger datasets are returned in fewer queries, which can be more efficient but might result in longer query execution times. -3. 5000: This boundary is used to capture rare cases where very large page sizes are requested. Although Cosmos DB generally handles larger datasets efficiently, large page sizes can sometimes lead to performance bottlenecks due to increased processing times or network bandwidth limitations. - -Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. - -### Metric: `db.query.response.item_count` - -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 SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters) -of `[10, 50, 100, 250, 500, 1000, 2000, 5000, 10000]`. - -Explaining bucket configuration: - -1. 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. 250, 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. - -Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. - -### Metric: `db.cosmosdb.operation.request_charge` - -It captures the Request Units consumed by each operation in Azure Cosmos DB. Since Request Units serve as a form of currency 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 `[ 3, 6, 9, 10, 50, 100]`. - - - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | -| -------- | --------------- | ----------- | -------------- | --------- | -| `db.cosmosdb.operation.request_charge` | Histogram | `{request_units}` | Request charge 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.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or 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` if response was received | ![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.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [6] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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) | - -**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. -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. - -**[2]:** 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. - -**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. -This attribute has stability level RELEASE CANDIDATE. - -**[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]:** 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. - -**[6]:** 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. - -**[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. - - - -`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) | - - -`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) | - - - - - - - - -### Metric: `db.cosmosdb.operation.regions_contacted` - -It captures the number of regions contacted by the SDK in a multi-region setup. Understanding the SDK's interaction with multiple regions is crucial, as it may contribute to higher latency. In a single-region setup, this value will remain at 1 - -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, 3, 5, 10, 20, 50]`. - - - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | -| -------- | --------------- | ----------- | -------------- | --------- | -| `db.cosmosdb.operation.regions_contacted` | Histogram | `{count}` | Number of regions contacted for 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.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or 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` if response was received | ![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.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [6] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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) | - -**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. -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. - -**[2]:** 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. - -**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. -This attribute has stability level RELEASE CANDIDATE. - -**[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]:** 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. - -**[6]:** 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. - -**[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. - - - -`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) | - - -`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) | - - - - - - - - -### Metric: `db.cosmosdb.client.active_instances` - -It aptures 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 process. Having multiple instances of the SDK client can lead to CPU or memory-related issues. - -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, 3, 5, 10, 50, 100]`. - - - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | -| -------- | --------------- | ----------- | -------------- | --------- | -| `db.cosmosdb.client.active_instances` | Histogram | `{count}` | 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 | -|---|---|---|---|---|---| -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or 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` if response was received | ![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.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [6] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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) | - -**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. -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. - -**[2]:** 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. - -**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. -This attribute has stability level RELEASE CANDIDATE. - -**[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]:** 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. - -**[6]:** 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. - -**[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. - - - -`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) | - - -`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) | - - - - - - - - [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index 3da577dde2..dc2274e6f6 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -48,7 +48,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[7]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[8]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[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. diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 3dae9e03d8..30056e1c13 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -12,8 +12,6 @@ linkTitle: Metrics - [Database operation](#database-operation) - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) - - [Metric: `db.query.limit`](#metric-dbquerylimit) - - [Metric: `db.query.response.item_count`](#metric-dbqueryresponseitem_count) - [Experimental](#experimental) - [Connection pools](#connection-pools) - [Metric: `db.client.connection.count`](#metric-dbclientconnectioncount) @@ -195,136 +193,6 @@ If a database operation involved multiple network calls (for example retries), t |---|---|---| | `_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.query.limit` - -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 `[ 100, 500, 1000, 1500, 2000]`. - - - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | -| -------- | --------------- | ----------- | -------------- | --------- | -| `db.query.limit` | Histogram | `{count}` | Max item count requested by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed) | ![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.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [3] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [4] | ![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. [5] | `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. [6] | `80`; `8080`; `443` | `Conditionally Required` [7] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [8] | `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. -If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. -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. - -**[2]:** If readily available. The operation name MAY be parsed from the query text, in which case it SHOULD be the first operation name found in the query. - -**[3]:** 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. - -**[4]:** If the operation failed and status code is available. - -**[5]:** 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. - -**[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]:** 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. - - - -`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.query.response.item_count` - -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 `[ 100, 500, 1000, 1500, 2000]`. - - - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | -| -------- | --------------- | ----------- | -------------- | --------- | -| `db.query.response.item_count` | Histogram | `{count}` | The actual number of records returned by the query. | ![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.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [3] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [4] | ![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. [5] | `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. [6] | `80`; `8080`; `443` | `Conditionally Required` [7] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [8] | `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. -If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. -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. - -**[2]:** If readily available. The operation name MAY be parsed from the query text, in which case it SHOULD be the first operation name found in the query. - -**[3]:** 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. - -**[4]:** If the operation failed and status code is available. - -**[5]:** 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. - -**[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]:** 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. - - - -`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) | - - - diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index da5b18579d..4e0dbc14a2 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -141,7 +141,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[11]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[12]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[13]:** 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. diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 2cccdc5a36..6af8a63d83 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -81,7 +81,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[11]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. **[12]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[13]:** 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. diff --git a/docs/database/hbase.md b/docs/database/hbase.md index ffc09e0651..bbe3d135ab 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -57,7 +57,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[9]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[10]:** 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. diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md index 894665d15b..d274988559 100644 --- a/docs/database/mariadb.md +++ b/docs/database/mariadb.md @@ -99,7 +99,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[11]:** 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. diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index 9f25c62276..99d531d056 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -54,7 +54,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[9]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[10]:** 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. diff --git a/docs/database/mssql.md b/docs/database/mssql.md index ac80b7125b..1198ca2292 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -69,7 +69,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[11]:** 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. diff --git a/docs/database/mysql.md b/docs/database/mysql.md index a52bd8211c..8e38c695ff 100644 --- a/docs/database/mysql.md +++ b/docs/database/mysql.md @@ -99,7 +99,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[11]:** 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. diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md index cb394a781b..bb276d31b3 100644 --- a/docs/database/postgresql.md +++ b/docs/database/postgresql.md @@ -106,7 +106,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[11]:** 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. diff --git a/docs/database/redis.md b/docs/database/redis.md index f7478e9710..4f197da253 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -63,7 +63,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[9]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[10]:** For **Redis**, the value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`. diff --git a/docs/database/sql.md b/docs/database/sql.md index 1a95d04e92..da73ddd183 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -131,7 +131,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[11]:** 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. diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md index fcd5c05817..ac8252881d 100644 --- a/docs/messaging/azure-messaging.md +++ b/docs/messaging/azure-messaging.md @@ -29,7 +29,7 @@ The following additional attributes are defined: | [`messaging.batch.message_count`](/docs/attributes-registry/messaging.md) | int | The number of messages sent, received, or processed in the scope of the batching operation. [3] | `0`; `1`; `2` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [5] | `MyQueue`; `MyTopic` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | Azure Service Bus [subscription name](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-queues-topics-subscriptions#topics-and-subscriptions). | `subscription-a` | `Conditionally Required` If messages are received from the subscription. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.servicebus.disposition_status`](/docs/attributes-registry/messaging.md) | string | Describes the [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). | `complete`; `abandon`; `dead_letter` | `Conditionally Required` if and only if `messaging.operation` is `settle`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.servicebus.message.delivery_count`](/docs/attributes-registry/messaging.md) | int | Number of deliveries that have been attempted for this message. | `2` | `Conditionally Required` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -148,7 +148,7 @@ The following additional attributes are defined: | [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) | string | Azure Event Hubs [consumer group name](https://learn.microsoft.com/en-us/azure/event-hubs/event-hubs-features#consumer-groups). | `my-group`; `indexer` | `Conditionally Required` On consumer spans. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [5] | `MyQueue`; `MyTopic` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | String representation of the partition id messages are sent to or received from, unique within the Event Hub. | `1` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.eventhubs.message.enqueued_time`](/docs/attributes-registry/messaging.md) | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.id`](/docs/attributes-registry/messaging.md) | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | `Recommended` If span describes operation on a single message. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md index 166f7cbcdc..ccc89ca860 100644 --- a/docs/messaging/gcp-pubsub.md +++ b/docs/messaging/gcp-pubsub.md @@ -28,7 +28,7 @@ For Google Cloud Pub/Sub, the following additional attributes are defined: | [`messaging.batch.message_count`](/docs/attributes-registry/messaging.md) | int | The number of messages sent, received, or processed in the scope of the batching operation. [3] | `0`; `1`; `2` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [5] | `MyQueue`; `MyTopic` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.gcp_pubsub.message.ordering_key`](/docs/attributes-registry/messaging.md) | string | The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. | `ordering_key` | `Conditionally Required` If the message type has an ordering key set. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | Google Pub/Sub [subscription name](https://cloud.google.com/pubsub/docs/subscription-overview). | `subscription-a` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.gcp_pubsub.message.ack_deadline`](/docs/attributes-registry/messaging.md) | int | The ack deadline in seconds set for the modify ack deadline request. | `10` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index 3b1704af26..2a14c0bf45 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -36,7 +36,7 @@ For Apache Kafka, the following additional attributes are defined: | [`messaging.batch.message_count`](/docs/attributes-registry/messaging.md) | int | The number of messages sent, received, or processed in the scope of the batching operation. [2] | `0`; `1`; `2` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [4] | `MyQueue`; `MyTopic` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.kafka.message.tombstone`](/docs/attributes-registry/messaging.md) | boolean | A boolean that is true if the message is a tombstone. | | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.client.id`](/docs/attributes-registry/messaging.md) | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) | string | Kafka [consumer group id](https://docs.confluent.io/platform/current/clients/consumer.html). | `my-group`; `indexer` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md index d116989b58..681a3c887f 100644 --- a/docs/messaging/messaging-metrics.md +++ b/docs/messaging/messaging-metrics.md @@ -57,7 +57,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [4] | `MyQueue`; `MyTopic` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | The name of the destination subscription from which a message is consumed. [6] | `subscription-a` | `Conditionally Required` if applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.template`](/docs/attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [7] | `/customers/{customerId}` | `Conditionally Required` if available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [8] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [8] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | The identifier of the partition messages are sent to or received from, unique within the `messaging.destination.name`. | `1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index da3c82ec7e..f419d0376b 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -354,7 +354,7 @@ Messaging system-specific attributes MUST be defined in the corresponding `messa | [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | The name of the destination subscription from which a message is consumed. [9] | `subscription-a` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.template`](/docs/attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [10] | `/customers/{customerId}` | `Conditionally Required` [11] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.temporary`](/docs/attributes-registry/messaging.md) | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | `Conditionally Required` [12] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [13] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [13] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [14] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.client.id`](/docs/attributes-registry/messaging.md) | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | The identifier of the partition messages are sent to or received from, unique within the `messaging.destination.name`. | `1` | `Recommended` When applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md index 166bde5ce9..065e587684 100644 --- a/docs/messaging/rabbitmq.md +++ b/docs/messaging/rabbitmq.md @@ -27,7 +27,7 @@ In RabbitMQ, the destination is defined by an *exchange* and a *routing key*. | [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | `Required` | ![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. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | `Conditionally Required` If and only if the messaging operation has failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [2] | `MyQueue`; `MyTopic` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [4] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [4] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rabbitmq.destination.routing_key`](/docs/attributes-registry/messaging.md) | string | RabbitMQ message routing key. | `myKey` | `Conditionally Required` If not empty. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rabbitmq.message.delivery_tag`](/docs/attributes-registry/messaging.md) | int | RabbitMQ message delivery tag | `123` | `Conditionally Required` When available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md index 7d2fb86b2f..6a4e9fd686 100644 --- a/docs/messaging/rocketmq.md +++ b/docs/messaging/rocketmq.md @@ -29,7 +29,7 @@ Specific attributes for Apache RocketMQ are defined below. | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | `Conditionally Required` If and only if the messaging operation has failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.batch.message_count`](/docs/attributes-registry/messaging.md) | int | The number of messages sent, received, or processed in the scope of the batching operation. [2] | `0`; `1`; `2` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [4] | `MyQueue`; `MyTopic` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [6] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [6] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rocketmq.message.delay_time_level`](/docs/attributes-registry/messaging.md) | int | The delay time level for delay message, which determines the message delay time. | `3` | `Conditionally Required` [7] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rocketmq.message.delivery_timestamp`](/docs/attributes-registry/messaging.md) | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | `Conditionally Required` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rocketmq.message.group`](/docs/attributes-registry/messaging.md) | string | It is essential for FIFO message. Messages that belong to the same message group are always processed one by one within the same consumer group. | `myMessageGroup` | `Conditionally Required` If the message type is FIFO. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml index 39bd8a5f7f..0451d82147 100644 --- a/model/database/cosmosdb-metrics.yaml +++ b/model/database/cosmosdb-metrics.yaml @@ -8,15 +8,6 @@ groups: stability: experimental extends: attributes.db.cosmosdb.minimal - - id: metric.db.cosmosdb.operation.regions_contacted - type: metric - metric_name: db.cosmosdb.operation.regions_contacted - brief: "Number of regions contacted for the operation" - instrument: histogram - unit: "{count}" - stability: experimental - extends: attributes.db.cosmosdb.minimal - - id: metric.db.cosmosdb.client.active_instances type: metric metric_name: db.cosmosdb.client.active_instances From 15fa6fb5792fcf8451539e6a674e3e6fa46d2b23 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Thu, 10 Oct 2024 11:59:00 +0530 Subject: [PATCH 26/84] removed query imit metrics --- docs/database/couchdb.md | 1 + model/database/metrics.yaml | 9 --------- 2 files changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index dc2274e6f6..3da577dde2 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -48,6 +48,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[7]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[8]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[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. diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index d8b9b9f0dc..ecda74f145 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -135,15 +135,6 @@ groups: - ref: db.client.connection.pool.name requirement_level: required - - id: metric.db.query.limit - type: metric - metric_name: db.query.limit - brief: "Max item count requested by the feed operation (ex. Query, ReadAll, ReadMany, Change Feed) " - instrument: histogram - unit: "{count}" - stability: experimental - extends: attributes.db.client.minimal - - id: metric.db.query.response.item_count type: metric metric_name: db.query.response.item_count From fc03c7ce49ce831be2c0a8b073a82e07e80681e4 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Thu, 10 Oct 2024 12:04:28 +0530 Subject: [PATCH 27/84] add cosmos.md --- docs/database/cosmosdb.md | 13 +++++++++++++ docs/database/couchdb.md | 1 - 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index ac84531f4b..e3d98f52ce 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -26,6 +26,7 @@ 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.consistency_level`](/docs/attributes-registry/db.md) | string | Account or request consistency level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![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.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) | @@ -186,6 +187,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[8]:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.DocumentDB` for all operations performed by Cosmos DB client. **[9]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[10]:** 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. @@ -222,6 +224,17 @@ and SHOULD be provided **at span creation time** (if provided at all): | `gateway` | Gateway (HTTP) connections mode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +`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) | + + `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 | diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index 3da577dde2..dc2274e6f6 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -48,7 +48,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[7]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[8]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[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. From dcb6f1db2fcb11d2d0d4000250047bd90cd6f856 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Fri, 11 Oct 2024 09:33:35 +0530 Subject: [PATCH 28/84] removed operation type --- .../users_sourabhjain_otelcosmosmetrics.yaml | 4 +- docs/attributes-registry/db.md | 24 +-------- docs/database/cosmosdb.md | 7 ++- model/database/registry.yaml | 54 +------------------ model/database/spans.yaml | 3 -- 5 files changed, 9 insertions(+), 83 deletions(-) diff --git a/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml b/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml index a221ba7437..5fc9993298 100644 --- a/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml +++ b/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml @@ -7,10 +7,10 @@ change_type: new_component # The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) -component: db +component: cosmosdb # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). -note: "Added new operation level metrics for Cosmos DB." +note: "Added new 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. diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 202ea83a1a..573b5e44af 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -186,8 +186,8 @@ 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) | +| `Direct` | Direct connection. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Gateway` | Gateway (HTTP) connections mode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `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. @@ -199,26 +199,6 @@ This group defines attributes for Azure Cosmos DB. | `Session` | session | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `Strong` | strong | ![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. - -| 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) | - ## Elasticsearch Attributes This group defines attributes for Elasticsearch. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index e3d98f52ce..04239ecc89 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -25,9 +25,8 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | 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.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.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.consistency_level`](/docs/attributes-registry/db.md) | string | Account or request consistency level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![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.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) | @@ -220,8 +219,8 @@ 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) | +| `Direct` | Direct connection. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `Gateway` | Gateway (HTTP) connections mode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `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. diff --git a/model/database/registry.yaml b/model/database/registry.yaml index dd6b9f8d6e..14691cf2aa 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -461,65 +461,15 @@ groups: type: members: - id: gateway - value: "gateway" + value: "Gateway" brief: Gateway (HTTP) connections mode stability: experimental - id: direct - value: "direct" + value: "Direct" brief: Direct connection. 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 diff --git a/model/database/spans.yaml b/model/database/spans.yaml index f0415725eb..e0ecea0bd4 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -521,9 +521,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: > From 547d7c9cda433ca6d64727f20ad0bdf44bc3ac01 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Fri, 11 Oct 2024 09:06:19 +0530 Subject: [PATCH 29/84] Update model/database/cosmosdb-metrics.yaml Co-authored-by: Liudmila Molkova --- model/database/cosmosdb-metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml index 0451d82147..7e62a7ff84 100644 --- a/model/database/cosmosdb-metrics.yaml +++ b/model/database/cosmosdb-metrics.yaml @@ -4,7 +4,7 @@ groups: metric_name: db.cosmosdb.operation.request_charge brief: "Request charge consumed by the operation." instrument: histogram - unit: "{request_units}" + unit: "{request_unit}" stability: experimental extends: attributes.db.cosmosdb.minimal From 051561da4ac40c06e982a77e2105ddc9d68c255e Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Fri, 11 Oct 2024 09:06:38 +0530 Subject: [PATCH 30/84] Update model/database/metrics.yaml Co-authored-by: Liudmila Molkova --- model/database/metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index ecda74f145..cf73b2089c 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -135,7 +135,7 @@ groups: - ref: db.client.connection.pool.name requirement_level: required - - id: metric.db.query.response.item_count + - id: metric.db.response.item_count type: metric metric_name: db.query.response.item_count brief: "The actual number of records returned by the query." From 790a9ee0b52e71ec81792d64a7fcb5a1f2cd65f9 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Fri, 11 Oct 2024 09:41:08 +0530 Subject: [PATCH 31/84] revert unrelated files --- docs/database/cassandra.md | 1 + docs/database/couchdb.md | 1 + docs/database/database-spans.md | 1 + docs/database/elasticsearch.md | 1 + docs/database/hbase.md | 1 + docs/database/mariadb.md | 1 + docs/database/mongodb.md | 1 + docs/database/mssql.md | 1 + docs/database/mysql.md | 1 + docs/database/postgresql.md | 1 + docs/database/redis.md | 1 + docs/database/sql.md | 1 + docs/messaging/azure-messaging.md | 4 ++-- docs/messaging/gcp-pubsub.md | 2 +- docs/messaging/kafka.md | 2 +- docs/messaging/messaging-metrics.md | 2 +- docs/messaging/messaging-spans.md | 2 +- docs/messaging/rabbitmq.md | 2 +- docs/messaging/rocketmq.md | 2 +- 19 files changed, 20 insertions(+), 8 deletions(-) diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index fb99e5b2bf..505819847b 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -74,6 +74,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[10]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[11]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[12]:** 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. diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index dc2274e6f6..3da577dde2 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -48,6 +48,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[7]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[8]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[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. diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 4e0dbc14a2..da5b18579d 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -141,6 +141,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[11]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[12]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[13]:** 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. diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 6af8a63d83..2cccdc5a36 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -81,6 +81,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[11]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. **[12]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[13]:** 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. diff --git a/docs/database/hbase.md b/docs/database/hbase.md index bbe3d135ab..ffc09e0651 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -57,6 +57,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[9]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[10]:** 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. diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md index d274988559..894665d15b 100644 --- a/docs/database/mariadb.md +++ b/docs/database/mariadb.md @@ -99,6 +99,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[11]:** 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. diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index 99d531d056..9f25c62276 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -54,6 +54,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[9]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[10]:** 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. diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 1198ca2292..ac80b7125b 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -69,6 +69,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[11]:** 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. diff --git a/docs/database/mysql.md b/docs/database/mysql.md index 8e38c695ff..a52bd8211c 100644 --- a/docs/database/mysql.md +++ b/docs/database/mysql.md @@ -99,6 +99,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[11]:** 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. diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md index bb276d31b3..cb394a781b 100644 --- a/docs/database/postgresql.md +++ b/docs/database/postgresql.md @@ -106,6 +106,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[11]:** 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. diff --git a/docs/database/redis.md b/docs/database/redis.md index 4f197da253..f7478e9710 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -63,6 +63,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[9]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[10]:** For **Redis**, the value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`. diff --git a/docs/database/sql.md b/docs/database/sql.md index da73ddd183..1a95d04e92 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -131,6 +131,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[11]:** 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. diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md index ac8252881d..fcd5c05817 100644 --- a/docs/messaging/azure-messaging.md +++ b/docs/messaging/azure-messaging.md @@ -29,7 +29,7 @@ The following additional attributes are defined: | [`messaging.batch.message_count`](/docs/attributes-registry/messaging.md) | int | The number of messages sent, received, or processed in the scope of the batching operation. [3] | `0`; `1`; `2` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [5] | `MyQueue`; `MyTopic` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | Azure Service Bus [subscription name](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-queues-topics-subscriptions#topics-and-subscriptions). | `subscription-a` | `Conditionally Required` If messages are received from the subscription. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.servicebus.disposition_status`](/docs/attributes-registry/messaging.md) | string | Describes the [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). | `complete`; `abandon`; `dead_letter` | `Conditionally Required` if and only if `messaging.operation` is `settle`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.servicebus.message.delivery_count`](/docs/attributes-registry/messaging.md) | int | Number of deliveries that have been attempted for this message. | `2` | `Conditionally Required` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -148,7 +148,7 @@ The following additional attributes are defined: | [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) | string | Azure Event Hubs [consumer group name](https://learn.microsoft.com/en-us/azure/event-hubs/event-hubs-features#consumer-groups). | `my-group`; `indexer` | `Conditionally Required` On consumer spans. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [5] | `MyQueue`; `MyTopic` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | String representation of the partition id messages are sent to or received from, unique within the Event Hub. | `1` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.eventhubs.message.enqueued_time`](/docs/attributes-registry/messaging.md) | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.id`](/docs/attributes-registry/messaging.md) | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | `Recommended` If span describes operation on a single message. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md index ccc89ca860..166f7cbcdc 100644 --- a/docs/messaging/gcp-pubsub.md +++ b/docs/messaging/gcp-pubsub.md @@ -28,7 +28,7 @@ For Google Cloud Pub/Sub, the following additional attributes are defined: | [`messaging.batch.message_count`](/docs/attributes-registry/messaging.md) | int | The number of messages sent, received, or processed in the scope of the batching operation. [3] | `0`; `1`; `2` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [5] | `MyQueue`; `MyTopic` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.gcp_pubsub.message.ordering_key`](/docs/attributes-registry/messaging.md) | string | The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. | `ordering_key` | `Conditionally Required` If the message type has an ordering key set. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | Google Pub/Sub [subscription name](https://cloud.google.com/pubsub/docs/subscription-overview). | `subscription-a` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.gcp_pubsub.message.ack_deadline`](/docs/attributes-registry/messaging.md) | int | The ack deadline in seconds set for the modify ack deadline request. | `10` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index 2a14c0bf45..3b1704af26 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -36,7 +36,7 @@ For Apache Kafka, the following additional attributes are defined: | [`messaging.batch.message_count`](/docs/attributes-registry/messaging.md) | int | The number of messages sent, received, or processed in the scope of the batching operation. [2] | `0`; `1`; `2` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [4] | `MyQueue`; `MyTopic` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.kafka.message.tombstone`](/docs/attributes-registry/messaging.md) | boolean | A boolean that is true if the message is a tombstone. | | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.client.id`](/docs/attributes-registry/messaging.md) | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) | string | Kafka [consumer group id](https://docs.confluent.io/platform/current/clients/consumer.html). | `my-group`; `indexer` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md index 681a3c887f..d116989b58 100644 --- a/docs/messaging/messaging-metrics.md +++ b/docs/messaging/messaging-metrics.md @@ -57,7 +57,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [4] | `MyQueue`; `MyTopic` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | The name of the destination subscription from which a message is consumed. [6] | `subscription-a` | `Conditionally Required` if applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.template`](/docs/attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [7] | `/customers/{customerId}` | `Conditionally Required` if available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [8] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [8] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | The identifier of the partition messages are sent to or received from, unique within the `messaging.destination.name`. | `1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index f419d0376b..da3c82ec7e 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -354,7 +354,7 @@ Messaging system-specific attributes MUST be defined in the corresponding `messa | [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | The name of the destination subscription from which a message is consumed. [9] | `subscription-a` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.template`](/docs/attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [10] | `/customers/{customerId}` | `Conditionally Required` [11] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.temporary`](/docs/attributes-registry/messaging.md) | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | `Conditionally Required` [12] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [13] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [13] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [14] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.client.id`](/docs/attributes-registry/messaging.md) | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | The identifier of the partition messages are sent to or received from, unique within the `messaging.destination.name`. | `1` | `Recommended` When applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md index 065e587684..166bde5ce9 100644 --- a/docs/messaging/rabbitmq.md +++ b/docs/messaging/rabbitmq.md @@ -27,7 +27,7 @@ In RabbitMQ, the destination is defined by an *exchange* and a *routing key*. | [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | `Required` | ![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. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | `Conditionally Required` If and only if the messaging operation has failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [2] | `MyQueue`; `MyTopic` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [4] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [4] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rabbitmq.destination.routing_key`](/docs/attributes-registry/messaging.md) | string | RabbitMQ message routing key. | `myKey` | `Conditionally Required` If not empty. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rabbitmq.message.delivery_tag`](/docs/attributes-registry/messaging.md) | int | RabbitMQ message delivery tag | `123` | `Conditionally Required` When available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md index 6a4e9fd686..7d2fb86b2f 100644 --- a/docs/messaging/rocketmq.md +++ b/docs/messaging/rocketmq.md @@ -29,7 +29,7 @@ Specific attributes for Apache RocketMQ are defined below. | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | `Conditionally Required` If and only if the messaging operation has failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.batch.message_count`](/docs/attributes-registry/messaging.md) | int | The number of messages sent, received, or processed in the scope of the batching operation. [2] | `0`; `1`; `2` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [4] | `MyQueue`; `MyTopic` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [6] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [6] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rocketmq.message.delay_time_level`](/docs/attributes-registry/messaging.md) | int | The delay time level for delay message, which determines the message delay time. | `3` | `Conditionally Required` [7] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rocketmq.message.delivery_timestamp`](/docs/attributes-registry/messaging.md) | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | `Conditionally Required` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rocketmq.message.group`](/docs/attributes-registry/messaging.md) | string | It is essential for FIFO message. Messages that belong to the same message group are always processed one by one within the same consumer group. | `myMessageGroup` | `Conditionally Required` If the message type is FIFO. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | From 47d53b1736aa2ac16aee007a39abc652578a72a3 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Fri, 11 Oct 2024 09:48:26 +0530 Subject: [PATCH 32/84] updated requrst charge url --- model/database/cosmosdb-metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml index 7e62a7ff84..b7cb96e98e 100644 --- a/model/database/cosmosdb-metrics.yaml +++ b/model/database/cosmosdb-metrics.yaml @@ -2,7 +2,7 @@ groups: - id: metric.db.cosmosdb.operation.request_charge type: metric metric_name: db.cosmosdb.operation.request_charge - brief: "Request charge consumed by the operation." + brief: "Request charge consumed by the operation. Refer https://learn.microsoft.com/en-us/azure/cosmos-db/request-units" instrument: histogram unit: "{request_unit}" stability: experimental From 80ab66d8c5660ad91fa4a6e79ea3a4e6a82c07ef Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Fri, 11 Oct 2024 10:02:19 +0530 Subject: [PATCH 33/84] added consistency level link --- docs/database/cosmosdb.md | 5 ++--- model/database/registry.yaml | 2 +- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 04239ecc89..c176f2ff53 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -26,7 +26,7 @@ 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.consistency_level`](/docs/attributes-registry/db.md) | string | Account or request consistency level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `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. Refer https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![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.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) | @@ -277,10 +277,9 @@ 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` | diff --git a/model/database/registry.yaml b/model/database/registry.yaml index 14691cf2aa..d2c885b14e 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -503,7 +503,7 @@ groups: value: "ConsistentPrefix" stability: experimental stability: experimental - brief: Account or request consistency level. + brief: Account or request consistency level. Refer https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels examples: [Eventual, ConsistentPrefix, BoundedStaleness, Strong or Session] - id: registry.db.elasticsearch From 82dee70682782b044b119b0d7b205d5f36f242f4 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Fri, 11 Oct 2024 11:35:31 +0530 Subject: [PATCH 34/84] deprecated operation_type --- docs/attributes-registry/db.md | 47 ++++++++++++++---------- docs/database/cosmosdb.md | 2 +- model/database/cosmosdb-metrics.yaml | 2 +- model/database/registry.yaml | 53 +++++++++++++++++++++++++++- 4 files changed, 83 insertions(+), 21 deletions(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 573b5e44af..3baed7ab79 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -163,24 +163,15 @@ This group defines attributes for Cassandra. This group defines attributes for Azure Cosmos DB. -| Attribute | Type | Description | Examples | Stability | -| ------------------------------------------------------------------------------------------------------------------------------ | ------ | --------------------------------- | -------------------------------------- | ---------------------------------------------------------------- | -| `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.sub_status_code` | int | Cosmos DB sub status code. | `1000`; `1002` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| Attribute | Type | Description | Examples | Stability | -| ------------------------------------ | ------ | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `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.consistency_level` | string | Account or request consistency level. | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.cosmosdb.machine_id` | string | Azure VM Id or hashed machine name or unique generate GUID, whatever is available. | `vmId:4d5ab1c4-d821-43fe-aacf-b61ea1f9c918`; `hashedMachineName:910dc3c9-7d90-074d-95bf-c930100d14d4`; `uuid:703e5e25-1bd3-4a53-ad53-f42f6ec50042` | ![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.sub_status_code` | int | Cosmos DB sub status code. | `1000`; `1002` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| ------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | +| `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.consistency_level` | string | Account or request [consistency level](https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.operation_type` | string | Deprecated, Cosmos DB Operation Type. | `batch`; `create`; `delete` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | +| `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.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. @@ -199,6 +190,26 @@ This group defines attributes for Azure Cosmos DB. | `Session` | session | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `Strong` | strong | ![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. + +| 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) | + ## Elasticsearch Attributes This group defines attributes for Elasticsearch. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index c176f2ff53..0f9c6c007b 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -26,7 +26,7 @@ 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.consistency_level`](/docs/attributes-registry/db.md) | string | Account or request consistency level. Refer https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `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/en-us/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `Conditionally Required` If available. | ![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.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) | diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml index b7cb96e98e..c27ee170c1 100644 --- a/model/database/cosmosdb-metrics.yaml +++ b/model/database/cosmosdb-metrics.yaml @@ -2,7 +2,7 @@ groups: - id: metric.db.cosmosdb.operation.request_charge type: metric metric_name: db.cosmosdb.operation.request_charge - brief: "Request charge consumed by the operation. Refer https://learn.microsoft.com/en-us/azure/cosmos-db/request-units" + brief: "[Request charge](https://learn.microsoft.com/en-us/azure/cosmos-db/request-units) consumed by the operation" instrument: histogram unit: "{request_unit}" stability: experimental diff --git a/model/database/registry.yaml b/model/database/registry.yaml index d2c885b14e..575fc79db2 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -470,6 +470,57 @@ 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 + deprecated: "Removed." + brief: Deprecated, Cosmos DB Operation Type. - id: db.cosmosdb.request_charge type: double stability: experimental @@ -503,7 +554,7 @@ groups: value: "ConsistentPrefix" stability: experimental stability: experimental - brief: Account or request consistency level. Refer https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels + brief: Account or request [consistency level](https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels). examples: [Eventual, ConsistentPrefix, BoundedStaleness, Strong or Session] - id: registry.db.elasticsearch From 4f441fa216e7e7db57f61e7f7c20039849044dfe Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Fri, 11 Oct 2024 23:32:52 +0530 Subject: [PATCH 35/84] Update model/database/registry.yaml Co-authored-by: Liudmila Molkova --- model/database/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/registry.yaml b/model/database/registry.yaml index 575fc79db2..f641602c7d 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -519,7 +519,7 @@ groups: value: "upsert" stability: experimental stability: experimental - deprecated: "Removed." + deprecated: "No replacement at this time." brief: Deprecated, Cosmos DB Operation Type. - id: db.cosmosdb.request_charge type: double From f9a24b7d20f04eb9636de911a4b51a6defd36808 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Fri, 11 Oct 2024 23:33:17 +0530 Subject: [PATCH 36/84] Update .chloggen/users_sourabhjain_otelcosmosmetrics.yaml Co-authored-by: Liudmila Molkova --- .chloggen/users_sourabhjain_otelcosmosmetrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml b/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml index 5fc9993298..b1f3b063c4 100644 --- a/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml +++ b/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml @@ -7,7 +7,7 @@ change_type: new_component # The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) -component: cosmosdb +component: db # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). note: "Added new operation level metrics for Azure Cosmos DB." From 186126490b8dd20616d85084a64f48cd4430f4f8 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Fri, 11 Oct 2024 23:34:07 +0530 Subject: [PATCH 37/84] Update .chloggen/users_sourabhjain_otelcosmosmetrics.yaml Co-authored-by: Liudmila Molkova --- .chloggen/users_sourabhjain_otelcosmosmetrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml b/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml index b1f3b063c4..39193cd3f3 100644 --- a/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml +++ b/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml @@ -4,7 +4,7 @@ # your pull request title with [chore] or use the "Skip Changelog" label. # One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' -change_type: new_component +change_type: enhancement # The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) component: db From 5e8b1b5294535afeb7857a67c341b9f353c5372f Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Fri, 11 Oct 2024 23:34:39 +0530 Subject: [PATCH 38/84] Update model/database/cosmosdb-metrics.yaml Co-authored-by: Liudmila Molkova --- model/database/cosmosdb-metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml index c27ee170c1..8ed38be5f1 100644 --- a/model/database/cosmosdb-metrics.yaml +++ b/model/database/cosmosdb-metrics.yaml @@ -2,7 +2,7 @@ groups: - id: metric.db.cosmosdb.operation.request_charge type: metric metric_name: db.cosmosdb.operation.request_charge - brief: "[Request charge](https://learn.microsoft.com/en-us/azure/cosmos-db/request-units) consumed by the operation" + brief: "[Request charge](https://learn.microsoft.com/azure/cosmos-db/request-units) consumed by the operation" instrument: histogram unit: "{request_unit}" stability: experimental From 210222c888210b92854d823b5d2f5c941c735a86 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Fri, 11 Oct 2024 23:35:00 +0530 Subject: [PATCH 39/84] Update model/database/cosmosdb-metrics.yaml Co-authored-by: Liudmila Molkova --- model/database/cosmosdb-metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml index 8ed38be5f1..778244828f 100644 --- a/model/database/cosmosdb-metrics.yaml +++ b/model/database/cosmosdb-metrics.yaml @@ -13,7 +13,7 @@ groups: metric_name: db.cosmosdb.client.active_instances brief: "Number of active client instances" instrument: histogram - unit: "{count}" + unit: "{instance}" stability: experimental extends: attributes.db.cosmosdb.minimal From dbd8b8e6f78b6bc5c3c622b4d2ad5eaff49694bd Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Fri, 11 Oct 2024 23:35:10 +0530 Subject: [PATCH 40/84] Update model/database/registry.yaml Co-authored-by: Liudmila Molkova --- model/database/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/registry.yaml b/model/database/registry.yaml index f641602c7d..29bfc10529 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -520,7 +520,7 @@ groups: stability: experimental stability: experimental deprecated: "No replacement at this time." - brief: Deprecated, Cosmos DB Operation Type. + brief: Deprecated, no replacement at this time. - id: db.cosmosdb.request_charge type: double stability: experimental From 28a4f280b40e4fc570b0146bb0e5de252e049114 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Fri, 11 Oct 2024 23:35:59 +0530 Subject: [PATCH 41/84] Update model/database/metrics.yaml Co-authored-by: Liudmila Molkova --- model/database/metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index cf73b2089c..ec542ff2c9 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -140,6 +140,6 @@ groups: metric_name: db.query.response.item_count brief: "The actual number of records returned by the query." instrument: histogram - unit: "{count}" + unit: "{row}" stability: experimental extends: attributes.db.client.minimal From 25f0327885854a51aac5ba01f743bdf471561934 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Sat, 12 Oct 2024 00:24:50 +0530 Subject: [PATCH 42/84] fix ebvrything --- .../users_sourabhjain_otelcosmosmetrics.yaml | 2 +- docs/attributes-registry/db.md | 116 +++++++++--------- docs/database/cosmosdb.md | 44 ++++--- .../deprecated/registry-deprecated.yaml | 51 ++++++++ model/database/metrics.yaml | 4 +- model/database/registry.yaml | 59 ++------- model/database/spans.yaml | 6 + 7 files changed, 153 insertions(+), 129 deletions(-) diff --git a/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml b/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml index 39193cd3f3..092310bdc8 100644 --- a/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml +++ b/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml @@ -10,7 +10,7 @@ change_type: enhancement component: db # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). -note: "Added new operation level metrics for Azure Cosmos DB." +note: "Added new common `db.client.response.row_count` 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. diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 3baed7ab79..c7248c94f5 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -17,18 +17,19 @@ This group defines the attributes used to describe telemetry in the context of databases. -| Attribute | Type | Description | Examples | Stability | -| ------------------------------------------------------------------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `db.client.connection.pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation SHOULD use a combination of parameters that would make the name unique, for example, combining attributes `server.address`, `server.port`, and `db.namespace`, formatted as `server.address:server.port/db.namespace`. Instrumentations that generate connection pool name following different patterns SHOULD document it. | `myDataSource` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.client.connection.state` | string | The state of a connection in the pool | `idle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.collection.name` | string | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.namespace` | string | The name of the database, fully qualified within the server address and port. [2] | `customers`; `test.users` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.operation.batch.size` | int | The number of queries included in a batch operation. [3] | `2`; `3`; `4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.operation.name` | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `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.text` | string | The database query being executed. [6] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.response.status_code` | string | Database response status code. [7] | `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. [8] | `other_sql`; `adabas`; `cache` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| -------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `db.client.connection.pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation SHOULD use a combination of parameters that would make the name unique, for example, combining attributes `server.address`, `server.port`, and `db.namespace`, formatted as `server.address:server.port/db.namespace`. Instrumentations that generate connection pool name following different patterns SHOULD document it. | `myDataSource` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.connection.state` | string | The state of a connection in the pool | `idle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.collection.name` | string | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.namespace` | string | The name of the database, fully qualified within the server address and port. [2] | `customers`; `test.users` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.operation.batch.size` | int | The number of queries included in a batch operation. [3] | `2`; `3`; `4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.operation.name` | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `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.text` | string | The database query being executed. [6] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.response.row_count` | int | Database response item count. [7] | `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) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. @@ -57,11 +58,14 @@ For batch operations, if the individual operations are known to have the same qu 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. -**[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. +**[7]:** Number of rows returned by the database in response to a query. +This attribute has stability level RELEASE CANDIDATE. + +**[8]:** 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]:** 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. +**[9]:** 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. `db.client.connection.state` 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. @@ -163,15 +167,14 @@ This group defines attributes for Cassandra. This group defines attributes for Azure Cosmos DB. -| Attribute | Type | Description | Examples | Stability | -| ------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| `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.consistency_level` | string | Account or request [consistency level](https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.cosmosdb.operation_type` | string | Deprecated, Cosmos DB Operation Type. | `batch`; `create`; `delete` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | -| `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.sub_status_code` | int | Cosmos DB sub status code. | `1000`; `1002` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| ------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `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.consistency_level` | string | Account or request [consistency level](https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | ![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.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. @@ -190,6 +193,40 @@ This group defines attributes for Azure Cosmos DB. | `Session` | session | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `Strong` | strong | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +## Elasticsearch Attributes + +This group defines attributes for Elasticsearch. + +| Attribute | Type | Description | Examples | Stability | +| ----------------------------------- | ------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [10] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[10]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names. + +## Deprecated Database Attributes + +"Describes deprecated db attributes." + +| Attribute | Type | Description | Examples | Stability | +| ------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `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. | +| `db.jdbc.driver_classname` | string | Removed, no replacement at this time. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed as not used. | +| `db.mongodb.collection` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | +| `db.mssql.instance_name` | string | Deprecated, SQL Server instance is now populated as a part of `db.namespace` attribute. | `MSSQLSERVER` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, no replacement at this time. | +| `db.name` | string | Deprecated, use `db.namespace` instead. | `customers`; `main` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | +| `db.operation` | string | Deprecated, use `db.operation.name` instead. | `findAndModify`; `HMSET`; `SELECT` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.operation.name`. | +| `db.redis.database_index` | int | Deprecated, use `db.namespace` instead. | `0`; `1`; `15` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | +| `db.sql.table` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | +| `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 | @@ -210,39 +247,6 @@ This group defines attributes for Azure Cosmos DB. | `replace` | replace | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `upsert` | upsert | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -## Elasticsearch Attributes - -This group defines attributes for Elasticsearch. - -| Attribute | Type | Description | Examples | Stability | -| --------------------------------------------------------------------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [9] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[9]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names. - -## Deprecated Database Attributes - -"Describes deprecated db attributes." - -| Attribute | Type | Description | Examples | Stability | -| --------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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.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. | -| `db.jdbc.driver_classname` | string | Removed, no replacement at this time. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed as not used. | -| `db.mongodb.collection` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | -| `db.mssql.instance_name` | string | Deprecated, SQL Server instance is now populated as a part of `db.namespace` attribute. | `MSSQLSERVER` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, no replacement at this time. | -| `db.name` | string | Deprecated, use `db.namespace` instead. | `customers`; `main` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | -| `db.operation` | string | Deprecated, use `db.operation.name` instead. | `findAndModify`; `HMSET`; `SELECT` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.operation.name`. | -| `db.redis.database_index` | int | Deprecated, use `db.namespace` instead. | `0`; `1`; `15` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | -| `db.sql.table` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | -| `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. | - ## Deprecated Database Metrics "Describes deprecated db metrics attributes." diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 0f9c6c007b..b351eac821 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -31,17 +31,18 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | [`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.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.response.row_count`](/docs/attributes-registry/db.md) | int | Cosmos DB row count in result set. [5] | `10`; `20` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Cosmos DB status code. [7] | `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. [8] | `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. [9] | `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. [10] | `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.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.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [10] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [11] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [13] | `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` | ![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. [14] | `someval`; `55` | `Opt-In` | ![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. [11] | `2`; `3`; `4` | `Recommended` | ![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 "WuValue"` | `Recommended` [13] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [14] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [15] | `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` | ![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) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -173,35 +174,40 @@ additional values when introducing new operations. **[4]:** If readily available. The operation name MAY be parsed from the query text, in which case it SHOULD be the first operation name found in the query. -**[5]:** 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. +**[5]:** Number of rows returned by the database in response to a query. +This attribute has stability level RELEASE CANDIDATE. + +**[6]:** if response was received and operation type is 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. -**[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. +**[8]:** 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. +**[9]:** 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]:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.DocumentDB` for all operations performed by Cosmos DB client. +**[10]:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.DocumentDB` for all operations performed by Cosmos DB client. -**[9]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +**[11]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. This attribute has stability level RELEASE CANDIDATE. -**[10]:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). +**[12]:** 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. -**[11]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). +**[13]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -**[12]:** 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. +**[14]:** 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. -**[13]:** The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled. +**[15]:** The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled. Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it). Default value is "NS". -**[14]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. +**[16]:** 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 `` SHOULD be the 0-based index. This attribute has stability level RELEASE CANDIDATE. 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 ec542ff2c9..31a507f740 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -135,9 +135,9 @@ groups: - ref: db.client.connection.pool.name requirement_level: required - - id: metric.db.response.item_count + - id: metric.db.client.response.row_count type: metric - metric_name: db.query.response.item_count + metric_name: db.client.response.row_count brief: "The actual number of records returned by the query." instrument: histogram unit: "{row}" diff --git a/model/database/registry.yaml b/model/database/registry.yaml index 29bfc10529..a784f15533 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -114,7 +114,15 @@ groups: This attribute has stability level RELEASE CANDIDATE. examples: ["102", "ORA-17002", "08P01", "404"] + - id: db.response.row_count + type: int + stability: experimental # RELEASE CANDIDATE + brief: Database response item count. + note: > + Number of rows returned by the database in response to a query. + This attribute has stability level RELEASE CANDIDATE. + examples: [10, 30, 1000] - id: db.system brief: The database management system (DBMS) product as identified by the client instrumentation. note: > @@ -470,57 +478,6 @@ 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 - deprecated: "No replacement at this time." - brief: Deprecated, no replacement at this time. - id: db.cosmosdb.request_charge type: double stability: experimental diff --git a/model/database/spans.yaml b/model/database/spans.yaml index e0ecea0bd4..64ada5a357 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -552,6 +552,12 @@ groups: examples: ["200", "201"] requirement_level: conditionally_required: if response was received + - ref: db.response.row_count + brief: > + Cosmos DB row count in result set. + examples: [10, 20] + requirement_level: + conditionally_required: if response was received and operation type is query. - ref: db.cosmosdb.sub_status_code requirement_level: conditionally_required: when response was received and contained sub-code. From 35df1a79e440fa95a7af46c2f1ec86edd2b46fdb Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Mon, 14 Oct 2024 16:56:11 +0530 Subject: [PATCH 43/84] updated docuemnattaion --- docs/database/database-metrics.md | 312 ++++++++++++++++++++++++++++++ 1 file changed, 312 insertions(+) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 30056e1c13..54ce8659c6 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -23,6 +23,11 @@ linkTitle: Metrics - [Metric: `db.client.connection.create_time`](#metric-dbclientconnectioncreate_time) - [Metric: `db.client.connection.wait_time`](#metric-dbclientconnectionwait_time) - [Metric: `db.client.connection.use_time`](#metric-dbclientconnectionuse_time) +- [Azure Cosmos DB](#azure-cosmos-db) + - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration-1) + - [Metric: `db.query.response.row_count`](#metric-dbqueryresponserow_count) + - [Metric: `db.cosmosdb.operation.request_charge`](#metric-dbcosmosdboperationrequest_charge) + - [Metric: `db.cosmosdb.client.active_instances`](#metric-dbcosmosdbclientactive_instances) @@ -423,6 +428,313 @@ This metric is [recommended][MetricRecommended]. |---|---|---|---|---|---| | [`db.client.connection.pool.name`](/docs/attributes-registry/db.md) | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation SHOULD use a combination of parameters that would make the name unique, for example, combining attributes `server.address`, `server.port`, and `db.namespace`, formatted as `server.address:server.port/db.namespace`. Instrumentations that generate connection pool name following different patterns SHOULD document it. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +## Azure Cosmos DB + +The following metric instruments describe Azure Cosmos DB client behaviour. + +### Metric: `db.client.operation.duration` + +It captures the total time taken by an Azure Cosmos DB operation. This metric follows the common [db.client.operation.duration] (#metric-dbclientoperationduration)b definition. + +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 `[ 0.001, 0.005, 0.010, 0.050, 0.100, 0.200, 0.500, 1.000, 2.000, 5.000 ]`. + +Explaining bucket configuration: + +1. 0.001, 0.005, 0.010 seconds: : These boundaries provide high precision for high-performance workloads, especially when dealing with microservices or low-latency queries. +2. 0.050, 0.100, 0.200 seconds: These intervals capture typical latencies between 50ms and 200ms, common in web applications, offering detailed tracking for normal operational performance. +3. 0.500, 1.000 seconds: These boundaries identify operations that take longer, highlighting potential bottlenecks or slower requests that may need optimization. +4. 2.000, 5.000 seconds: Although Azure Cosmos DB is optimized for sub-second latencies, these buckets are included to track rare, long-running outliers that might exceed 1 second. + +Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. + +### Metric: `db.query.response.row_count` + +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 SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters) +of `[10, 50, 100, 250, 500, 1000, 2000, 5000, 10000]`. + +Explaining bucket configuration: + +1. 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. 250, 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. + +Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. + +### Metric: `db.cosmosdb.operation.request_charge` + +It captures the Request Units consumed by each operation in Azure Cosmos DB. Since Request Units serve as a form of currency 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.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.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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/en-us/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or 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` if response was received | ![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.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [6] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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) | + +**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. +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. + +**[2]:** 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. + +**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. +This attribute has stability level RELEASE CANDIDATE. + +**[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]:** 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. + +**[6]:** 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. + +**[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. + + + +`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) | + + +`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) | + + + + + + + + +### Metric: `db.cosmosdb.client.active_instances` + +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 process. Having multiple instances of the SDK client can lead to CPU or memory-related issues. + +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, 3, 5, 10, 50, 100]`. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.cosmosdb.client.active_instances` | Histogram | `{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 | +|---|---|---|---|---|---| +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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/en-us/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or 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` if response was received | ![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.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [6] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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) | + +**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. +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. + +**[2]:** 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. + +**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. +This attribute has stability level RELEASE CANDIDATE. + +**[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]:** 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. + +**[6]:** 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. + +**[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. + + + +`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) | + + +`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) | + + + From 4c326384c0cb7714c9485dce22c1bef832f15fd8 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Mon, 14 Oct 2024 23:44:40 +0530 Subject: [PATCH 44/84] Update model/database/registry.yaml Co-authored-by: Liudmila Molkova --- model/database/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/registry.yaml b/model/database/registry.yaml index a784f15533..e4a7e92b53 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -512,7 +512,7 @@ groups: stability: experimental stability: experimental brief: Account or request [consistency level](https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels). - examples: [Eventual, ConsistentPrefix, BoundedStaleness, Strong or Session] + examples: ["Eventual", "ConsistentPrefix", "BoundedStaleness", "Strong", "Session"] - id: registry.db.elasticsearch type: attribute_group From 1a0cb8f893c1fab22567de6d0bcf94476638147e Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Mon, 14 Oct 2024 23:47:46 +0530 Subject: [PATCH 45/84] Update model/database/registry.yaml Co-authored-by: Liudmila Molkova --- model/database/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/registry.yaml b/model/database/registry.yaml index e4a7e92b53..ea798ca217 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -511,7 +511,7 @@ groups: value: "ConsistentPrefix" stability: experimental stability: experimental - brief: Account or request [consistency level](https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels). + 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 From cdcc6b48769dc793ce2fb52f864fcb2aa745fde1 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Mon, 14 Oct 2024 23:58:11 +0530 Subject: [PATCH 46/84] Updated docs --- docs/attributes-registry/db.md | 20 ++++++++++---------- docs/database/cosmosdb.md | 8 ++++---- docs/database/database-metrics.md | 4 ++-- model/database/registry.yaml | 6 +++--- 4 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index c7248c94f5..b99fa681b7 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -167,21 +167,21 @@ This group defines attributes for Cassandra. This group defines attributes for Azure Cosmos DB. -| Attribute | Type | Description | Examples | Stability | -| ------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `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.consistency_level` | string | Account or request [consistency level](https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | ![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.sub_status_code` | int | Cosmos DB sub status code. | `1000`; `1002` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| ------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `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.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 | 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.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. | 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) | +| `direct` | Direct connection. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gateway` | Gateway (HTTP) connections mode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `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. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index b351eac821..3e39256766 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -25,8 +25,8 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | 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.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.consistency_level`](/docs/attributes-registry/db.md) | string | Account or request [consistency level](https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `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.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 | RU consumed for that 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) | @@ -225,8 +225,8 @@ 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) | +| `direct` | Direct connection. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gateway` | Gateway (HTTP) connections mode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `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. diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 54ce8659c6..9a5587db05 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -502,7 +502,7 @@ Explaining bucket configuration: | [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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/en-us/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `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` if response was received | ![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.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -633,7 +633,7 @@ of `[1, 2, 3, 5, 10, 50, 100]`. | [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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/en-us/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong or Session` | `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` if response was received | ![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.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/database/registry.yaml b/model/database/registry.yaml index ea798ca217..22345e85dc 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -116,7 +116,7 @@ groups: examples: ["102", "ORA-17002", "08P01", "404"] - id: db.response.row_count type: int - stability: experimental # RELEASE CANDIDATE + stability: experimental brief: Database response item count. note: > Number of rows returned by the database in response to a query. @@ -469,11 +469,11 @@ groups: type: members: - id: gateway - value: "Gateway" + value: "gateway" brief: Gateway (HTTP) connections mode stability: experimental - id: direct - value: "Direct" + value: "direct" brief: Direct connection. stability: experimental stability: experimental From 1e5da5abee70e625a4912aea4c0f21e3f68f0967 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Tue, 15 Oct 2024 00:04:09 +0530 Subject: [PATCH 47/84] fix lint review --- docs/database/database-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 9a5587db05..ff0d9ddf3d 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -466,7 +466,7 @@ Explaining bucket configuration: 1. 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. 250, 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. +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. Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. From d27af0f0ab96afac4aebf14d8a78766d1813657e Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Tue, 15 Oct 2024 06:58:05 +0530 Subject: [PATCH 48/84] Update model/database/registry.yaml Co-authored-by: Liudmila Molkova --- model/database/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/registry.yaml b/model/database/registry.yaml index 22345e85dc..ffedfaba68 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -117,7 +117,7 @@ groups: - id: db.response.row_count type: int stability: experimental - brief: Database response item count. + brief: Number of rows returned by the database in response to a query. note: > Number of rows returned by the database in response to a query. From 8c54e01fef1a7a0bf9e2907d97f1965a2f37961a Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Tue, 15 Oct 2024 06:58:32 +0530 Subject: [PATCH 49/84] Update model/database/registry.yaml Co-authored-by: Liudmila Molkova --- model/database/registry.yaml | 4 ---- 1 file changed, 4 deletions(-) diff --git a/model/database/registry.yaml b/model/database/registry.yaml index ffedfaba68..b42a2de6c0 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -118,10 +118,6 @@ groups: type: int stability: experimental brief: Number of rows returned by the database in response to a query. - note: > - Number of rows returned by the database in response to a query. - - This attribute has stability level RELEASE CANDIDATE. examples: [10, 30, 1000] - id: db.system brief: The database management system (DBMS) product as identified by the client instrumentation. From c8c22223fe18ab2b97e6c5095b4e5cf650ed9dff Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Tue, 15 Oct 2024 06:59:33 +0530 Subject: [PATCH 50/84] Update docs/database/database-metrics.md Co-authored-by: Liudmila Molkova --- docs/database/database-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index ff0d9ddf3d..aa9791e555 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -439,7 +439,7 @@ The following metric instruments describe Azure Cosmos DB client behaviour. ### Metric: `db.client.operation.duration` -It captures the total time taken by an Azure Cosmos DB operation. This metric follows the common [db.client.operation.duration] (#metric-dbclientoperationduration)b definition. +It captures the total time taken by an Azure Cosmos DB operation. This metric follows the common [db.client.operation.duration](#metric-dbclientoperationduration) definition. 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) From 7272b9a690ff5522bc7cb2d7f9c2715aa00a47a2 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Tue, 15 Oct 2024 12:34:48 +0530 Subject: [PATCH 51/84] wip --- docs/attributes-registry/db.md | 17 +- docs/database/cosmosdb.md | 271 +++++++++++++++++-- docs/database/database-metrics.md | 385 +++++---------------------- model/database/common.yaml | 29 ++ model/database/cosmosdb-metrics.yaml | 32 +-- 5 files changed, 356 insertions(+), 378 deletions(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index b99fa681b7..2308006e4b 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -27,9 +27,9 @@ This group defines the attributes used to describe telemetry in the context of d | `db.operation.name` | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `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.text` | string | The database query being executed. [6] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.response.row_count` | int | Database response item count. [7] | `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) | +| `db.response.row_count` | int | Number of rows returned by the database in response to a query. | `10`; `30`; `1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.response.status_code` | string | Database response status code. [7] | `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. [8] | `other_sql`; `adabas`; `cache` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. @@ -58,14 +58,11 @@ For batch operations, if the individual operations are known to have the same qu 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. -**[7]:** Number of rows returned by the database in response to a query. -This attribute has stability level RELEASE CANDIDATE. - -**[8]:** 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. +**[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. -**[9]:** 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. +**[8]:** 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. `db.client.connection.state` 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. @@ -200,9 +197,9 @@ This group defines attributes for Elasticsearch. | Attribute | Type | Description | Examples | Stability | | ----------------------------------- | ------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [10] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [9] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[10]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names. +**[9]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names. ## Deprecated Database Attributes diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 3e39256766..4b63cf2139 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -2,7 +2,23 @@ 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) + - [Azure Cosmos DB Metrics](#azure-cosmos-db-metrics) + - [Operation Level](#operation-level) + - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) + - [Metric: `db.client.response.row_count`](#metric-dbclientresponserow_count) + - [Metric: `db.cosmosdb.operation.request_charge`](#metric-dbcosmosdboperationrequest_charge) + - [Metric: `db.cosmosdb.client.active_instances`](#metric-dbcosmosdbclientactive_instances) + + + +# Semantic Conventions for Microsoft Azure Cosmos DB **Status**: [Experimental][DocumentStatus] @@ -31,18 +47,18 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | [`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.row_count`](/docs/attributes-registry/db.md) | int | Cosmos DB row count in result set. [5] | `10`; `20` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Cosmos DB status code. [7] | `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. [8] | `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. [9] | `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. [10] | `Microsoft.DocumentDB` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.row_count`](/docs/attributes-registry/db.md) | int | Cosmos DB row count in result set. | `10`; `20` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Cosmos DB status code. [6] | `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. [7] | `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. [8] | `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. [9] | `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.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.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [12] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [13] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [14] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [15] | `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` | ![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) | +| [`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.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [11] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [12] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [13] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [14] | `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` | ![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. [15] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -174,40 +190,37 @@ additional values when introducing new operations. **[4]:** If readily available. The operation name MAY be parsed from the query text, in which case it SHOULD be the first operation name found in the query. -**[5]:** Number of rows returned by the database in response to a query. -This attribute has stability level RELEASE CANDIDATE. - -**[6]:** if response was received and operation type is query. +**[5]:** if response was received and operation type is 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. +**[6]:** 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]:** 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. +**[7]:** 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. -**[9]:** 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]:** 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. -**[10]:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.DocumentDB` for all operations performed by Cosmos DB client. +**[9]:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.DocumentDB` for all operations performed by Cosmos DB client. -**[11]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +**[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. This attribute has stability level RELEASE CANDIDATE. -**[12]:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). +**[11]:** 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. -**[13]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). +**[12]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -**[14]:** 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. +**[13]:** 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. -**[15]:** The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled. +**[14]:** The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled. Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it). Default value is "NS". -**[16]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. +**[15]:** 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 `` SHOULD be the 0-based index. This attribute has stability level RELEASE CANDIDATE. @@ -289,4 +302,212 @@ and SHOULD be provided **at span creation time** (if provided at all): | `db.cosmosdb.sub_status_code` | `0` | | `db.cosmosdb.request_charge` | `7.43` | +## Azure Cosmos DB Metrics + +### Operation Level + +The following metric instruments describe Azure Cosmos DB client Operation level behaviour. + +#### 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](/doc/database/database-metrics.md#metric-dbclientoperationduration) definition. + +Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. + +#### Metric: `db.client.response.row_count` + +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.row_count](/doc/database/database-metrics.md#metric-dbclientresponserow_count) definition. + +Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. + +#### Metric: `db.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 currency 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.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. +If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. +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. The operation name MAY be parsed from the query text, in which case it SHOULD be the first 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.cosmosdb.client.active_instances` + +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 process. Having multiple instances of the SDK client can lead to CPU or memory-related issues. + +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, 3, 5, 10, 50, 100]`. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.cosmosdb.client.active_instances` | 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 | +|---|---|---|---|---|---| +| [`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. +If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. +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. The operation name MAY be parsed from the query text, in which case it SHOULD be the first 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) | + + + + + + + + [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 aa9791e555..af60d90727 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -12,6 +12,7 @@ linkTitle: Metrics - [Database operation](#database-operation) - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) + - [Metric: `db.client.response.row_count`](#metric-dbclientresponserow_count) - [Experimental](#experimental) - [Connection pools](#connection-pools) - [Metric: `db.client.connection.count`](#metric-dbclientconnectioncount) @@ -23,11 +24,6 @@ linkTitle: Metrics - [Metric: `db.client.connection.create_time`](#metric-dbclientconnectioncreate_time) - [Metric: `db.client.connection.wait_time`](#metric-dbclientconnectionwait_time) - [Metric: `db.client.connection.use_time`](#metric-dbclientconnectionuse_time) -- [Azure Cosmos DB](#azure-cosmos-db) - - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration-1) - - [Metric: `db.query.response.row_count`](#metric-dbqueryresponserow_count) - - [Metric: `db.cosmosdb.operation.request_charge`](#metric-dbcosmosdboperationrequest_charge) - - [Metric: `db.cosmosdb.client.active_instances`](#metric-dbcosmosdbclientactive_instances) @@ -198,6 +194,78 @@ If a database operation involved multiple network calls (for example retries), t |---|---|---| | `_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.response.row_count` + +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 `[10, 50, 100, 250, 500, 1000, 2000, 5000, 10000]`. + +Explaining bucket configuration: + +1. 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. 250, 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.row_count` | Histogram | `{row}` | The actual number of records returned by the query. | ![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.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [3] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [4] | ![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. [5] | `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. [6] | `80`; `8080`; `443` | `Conditionally Required` [7] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [8] | `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. +If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. +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. + +**[2]:** If readily available. The operation name MAY be parsed from the query text, in which case it SHOULD be the first operation name found in the query. + +**[3]:** 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. + +**[4]:** If the operation failed and status code is available. + +**[5]:** 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. + +**[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]:** 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. + + + +`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) | + + + @@ -428,313 +496,6 @@ This metric is [recommended][MetricRecommended]. |---|---|---|---|---|---| | [`db.client.connection.pool.name`](/docs/attributes-registry/db.md) | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation SHOULD use a combination of parameters that would make the name unique, for example, combining attributes `server.address`, `server.port`, and `db.namespace`, formatted as `server.address:server.port/db.namespace`. Instrumentations that generate connection pool name following different patterns SHOULD document it. | `myDataSource` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - - - - - -## Azure Cosmos DB - -The following metric instruments describe Azure Cosmos DB client behaviour. - -### Metric: `db.client.operation.duration` - -It captures the total time taken by an Azure Cosmos DB operation. This metric follows the common [db.client.operation.duration](#metric-dbclientoperationduration) definition. - -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 `[ 0.001, 0.005, 0.010, 0.050, 0.100, 0.200, 0.500, 1.000, 2.000, 5.000 ]`. - -Explaining bucket configuration: - -1. 0.001, 0.005, 0.010 seconds: : These boundaries provide high precision for high-performance workloads, especially when dealing with microservices or low-latency queries. -2. 0.050, 0.100, 0.200 seconds: These intervals capture typical latencies between 50ms and 200ms, common in web applications, offering detailed tracking for normal operational performance. -3. 0.500, 1.000 seconds: These boundaries identify operations that take longer, highlighting potential bottlenecks or slower requests that may need optimization. -4. 2.000, 5.000 seconds: Although Azure Cosmos DB is optimized for sub-second latencies, these buckets are included to track rare, long-running outliers that might exceed 1 second. - -Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. - -### Metric: `db.query.response.row_count` - -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 SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters) -of `[10, 50, 100, 250, 500, 1000, 2000, 5000, 10000]`. - -Explaining bucket configuration: - -1. 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. 250, 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. - -Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. - -### Metric: `db.cosmosdb.operation.request_charge` - -It captures the Request Units consumed by each operation in Azure Cosmos DB. Since Request Units serve as a form of currency 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.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.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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` if response was received | ![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.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [6] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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) | - -**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. -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. - -**[2]:** 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. - -**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. -This attribute has stability level RELEASE CANDIDATE. - -**[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]:** 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. - -**[6]:** 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. - -**[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. - - - -`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) | - - -`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) | - - - - - - - - -### Metric: `db.cosmosdb.client.active_instances` - -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 process. Having multiple instances of the SDK client can lead to CPU or memory-related issues. - -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, 3, 5, 10, 50, 100]`. - - - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | -| -------- | --------------- | ----------- | -------------- | --------- | -| `db.cosmosdb.client.active_instances` | Histogram | `{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 | -|---|---|---|---|---|---| -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [3] | `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` if response was received | ![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.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [5] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [6] | `other_sql`; `adabas`; `cache` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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) | - -**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. -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. - -**[2]:** 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. - -**[3]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. -This attribute has stability level RELEASE CANDIDATE. - -**[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]:** 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. - -**[6]:** 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. - -**[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. - - - -`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) | - - -`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) | - - - diff --git a/model/database/common.yaml b/model/database/common.yaml index 72a6cdac89..c3b146cc89 100644 --- a/model/database/common.yaml +++ b/model/database/common.yaml @@ -30,3 +30,32 @@ groups: generic one, the original exception SHOULD be preferred. 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. diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml index 778244828f..fd86e68c54 100644 --- a/model/database/cosmosdb-metrics.yaml +++ b/model/database/cosmosdb-metrics.yaml @@ -12,37 +12,7 @@ groups: type: metric metric_name: db.cosmosdb.client.active_instances brief: "Number of active client instances" - instrument: histogram + instrument: updowncounter unit: "{instance}" stability: experimental extends: attributes.db.cosmosdb.minimal - - - id: attributes.db.cosmosdb.minimal - type: attribute_group - brief: 'Azure Cosmos DB attributes' - attributes: - - ref: db.system - requirement_level: - conditionally_required: if available - - ref: server.port - requirement_level: - conditionally_required: If not default (443). - - ref: db.collection.name - requirement_level: - conditionally_required: if available - - ref: db.namespace - requirement_level: - conditionally_required: If available. - - ref: db.operation.name - requirement_level: required - - ref: server.address - requirement_level: required - - ref: db.response.status_code - requirement_level: - conditionally_required: if response was received - - ref: db.cosmosdb.sub_status_code - requirement_level: - conditionally_required: if response was received - - ref: db.cosmosdb.consistency_level - requirement_level: - conditionally_required: If available. From 68f844464a85e5231aca29e3012c21289d200463 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Tue, 15 Oct 2024 14:51:07 +0530 Subject: [PATCH 52/84] improved doc --- docs/database/cosmosdb.md | 31 ++++++++++++++----------------- 1 file changed, 14 insertions(+), 17 deletions(-) diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 4b63cf2139..a026e02dbe 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -9,12 +9,11 @@ linkTitle: Cosmos DB - [Semantic Conventions for Microsoft Azure Cosmos DB](#semantic-conventions-for-microsoft-azure-cosmos-db) - [Attributes](#attributes) - [Example](#example) - - [Azure Cosmos DB Metrics](#azure-cosmos-db-metrics) - - [Operation Level](#operation-level) - - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) - - [Metric: `db.client.response.row_count`](#metric-dbclientresponserow_count) - - [Metric: `db.cosmosdb.operation.request_charge`](#metric-dbcosmosdboperationrequest_charge) - - [Metric: `db.cosmosdb.client.active_instances`](#metric-dbcosmosdbclientactive_instances) + - [Operation Level Metrics](#operation-level-metrics) + - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) + - [Metric: `db.client.response.row_count`](#metric-dbclientresponserow_count) + - [Metric: `db.cosmosdb.operation.request_charge`](#metric-dbcosmosdboperationrequest_charge) + - [Metric: `db.cosmosdb.client.active_instances`](#metric-dbcosmosdbclientactive_instances) @@ -302,29 +301,27 @@ and SHOULD be provided **at span creation time** (if provided at all): | `db.cosmosdb.sub_status_code` | `0` | | `db.cosmosdb.request_charge` | `7.43` | -## Azure Cosmos DB Metrics - -### Operation Level +## Operation Level Metrics The following metric instruments describe Azure Cosmos DB client Operation level behaviour. -#### Metric: `db.client.operation.duration` +### 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](/doc/database/database-metrics.md#metric-dbclientoperationduration) definition. +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.cosmosdb.operation.request_charge` metrics for dimensions. +Refer [db.cosmosdb.operation.request_charge](#metric-dbcosmosdboperationrequest_charge) metrics for dimensions. -#### Metric: `db.client.response.row_count` +### Metric: `db.client.response.row_count` 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.row_count](/doc/database/database-metrics.md#metric-dbclientresponserow_count) definition. +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.row_count](/docs/database/database-metrics.md#metric-dbclientresponserow_count) definition. -Refer `db.cosmosdb.operation.request_charge` metrics for dimensions. +Refer [db.cosmosdb.operation.request_charge](#metric-dbcosmosdboperationrequest_charge) metrics for dimensions. -#### Metric: `db.cosmosdb.operation.request_charge` +### Metric: `db.cosmosdb.operation.request_charge` This metric is [required][MetricRequired]. @@ -420,7 +417,7 @@ and SHOULD be provided **at span creation time** (if provided at all): -#### Metric: `db.cosmosdb.client.active_instances` +### Metric: `db.cosmosdb.client.active_instances` This metric is [required][MetricRequired]. From dad7e47543b882f5cdf4c69205cd2122d66a9ff3 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Tue, 15 Oct 2024 16:26:51 +0530 Subject: [PATCH 53/84] bettre doc --- docs/database/database-metrics.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index af60d90727..98d2ab1441 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -12,8 +12,9 @@ linkTitle: Metrics - [Database operation](#database-operation) - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) - - [Metric: `db.client.response.row_count`](#metric-dbclientresponserow_count) - [Experimental](#experimental) + - [Database Response](#database-response) + - [Metric: `db.client.response.row_count`](#metric-dbclientresponserow_count) - [Connection pools](#connection-pools) - [Metric: `db.client.connection.count`](#metric-dbclientconnectioncount) - [Metric: `db.client.connection.idle.max`](#metric-dbclientconnectionidlemax) @@ -199,7 +200,13 @@ If a database operation involved multiple network calls (for example retries), t -### Metric: `db.client.response.row_count` +## Experimental + +### Database Response + +The following metric instruments describe database query response. + +#### Metric: `db.client.response.row_count` This metric is [recommended][MetricRecommended]. @@ -271,8 +278,6 @@ Instrumentations SHOULD document how `error.type` is populated. -## Experimental - ### Connection pools The following metric instruments describe database client connection pool operations. From ed71a97e78fc3aa10315d2c6d80654fd291404fd Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Tue, 15 Oct 2024 16:55:45 +0530 Subject: [PATCH 54/84] remove hstogram buckets --- docs/database/cosmosdb.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index a026e02dbe..01d4347484 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -423,10 +423,6 @@ 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 process. Having multiple instances of the SDK client can lead to CPU or memory-related issues. -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, 3, 5, 10, 50, 100]`. - From 04a43310334f0ffdf6de4c6a761913066bc8740d Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 07:26:18 +0530 Subject: [PATCH 55/84] updated after conflict --- docs/database/cosmosdb.md | 10 ---------- docs/database/database-metrics.md | 4 ---- 2 files changed, 14 deletions(-) diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 01d4347484..87c06cd92b 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -386,8 +386,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[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): @@ -403,15 +401,12 @@ and SHOULD be provided **at span creation time** (if provided at all): | `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) | - - @@ -471,8 +466,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[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): @@ -488,15 +481,12 @@ and SHOULD be provided **at span creation time** (if provided at all): | `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) | - - diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 98d2ab1441..9dbab08698 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -263,16 +263,12 @@ Instrumentations SHOULD document how `error.type` is populated. **[8]:** 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. - - `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) | - - From 277bff832b1ce8cca1a562cf24867bef0e2eebdc Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 15:35:57 +0530 Subject: [PATCH 56/84] Update model/database/spans.yaml Co-authored-by: Liudmila Molkova --- model/database/spans.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/spans.yaml b/model/database/spans.yaml index 64ada5a357..454e419eaf 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -557,7 +557,7 @@ groups: Cosmos DB row count in result set. examples: [10, 20] requirement_level: - conditionally_required: if response was received and operation type is query. + 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. From 7d2ba808a6dfc63881b2b8748a9fed45bddd40c7 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 15:36:36 +0530 Subject: [PATCH 57/84] Update model/database/registry.yaml Co-authored-by: Liudmila Molkova --- model/database/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/registry.yaml b/model/database/registry.yaml index b42a2de6c0..cfbf5a9b05 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -117,7 +117,7 @@ groups: - id: db.response.row_count type: int stability: experimental - brief: Number of rows returned by the database in response to a query. + brief: Number of rows returned by the database in response. examples: [10, 30, 1000] - id: db.system brief: The database management system (DBMS) product as identified by the client instrumentation. From 02a880b8a1d60951b89b36b9987f2fa62aa1b4d6 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 15:36:48 +0530 Subject: [PATCH 58/84] Update model/database/metrics.yaml Co-authored-by: Liudmila Molkova --- model/database/metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index 31a507f740..a81701ecf0 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -138,7 +138,7 @@ groups: - id: metric.db.client.response.row_count type: metric metric_name: db.client.response.row_count - brief: "The actual number of records returned by the query." + brief: "The actual number of records returned by the database operation." instrument: histogram unit: "{row}" stability: experimental From a800740a79efb470669a562794a6ae9ee60a05de Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 15:38:15 +0530 Subject: [PATCH 59/84] Update docs/database/database-metrics.md Co-authored-by: Liudmila Molkova --- docs/database/database-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 9dbab08698..ef920f82c5 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -13,7 +13,7 @@ linkTitle: Metrics - [Database operation](#database-operation) - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) - [Experimental](#experimental) - - [Database Response](#database-response) + - [Database operations](#database-operations) - [Metric: `db.client.response.row_count`](#metric-dbclientresponserow_count) - [Connection pools](#connection-pools) - [Metric: `db.client.connection.count`](#metric-dbclientconnectioncount) From 927a414ab68f0344fd4f24aca465e55468321f5f Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 15:39:16 +0530 Subject: [PATCH 60/84] Update docs/database/cosmosdb.md Co-authored-by: Liudmila Molkova --- docs/database/cosmosdb.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 87c06cd92b..aa209a28bf 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -303,7 +303,7 @@ and SHOULD be provided **at span creation time** (if provided at all): ## Operation Level Metrics -The following metric instruments describe Azure Cosmos DB client Operation level behaviour. +The following metrics provide insights into Azure Cosmos DB client operation performance and behavior. ### Metric: `db.client.operation.duration` From cb2078a84af1e2602695ae074868c90f8569ac58 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 15:54:26 +0530 Subject: [PATCH 61/84] updated histogram boundaried for row_count --- docs/database/database-metrics.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index ef920f82c5..cb6454bd7d 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -212,11 +212,11 @@ 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 `[10, 50, 100, 250, 500, 1000, 2000, 5000, 10000]`. +of `[1, 10, 50, 100, 250, 500, 1000, 2000, 5000, 10000]`. Explaining bucket configuration: -1. 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. +1. 1, 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. 250, 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. From 1ce3f28a283458e1d8d9b481816a82d7f1f5c2ed Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 15:59:57 +0530 Subject: [PATCH 62/84] updated doc --- docs/attributes-registry/db.md | 2 +- docs/database/cosmosdb.md | 42 +++++++++++++++---------------- docs/database/database-metrics.md | 4 +-- 3 files changed, 23 insertions(+), 25 deletions(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 2308006e4b..352d58b279 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -27,7 +27,7 @@ This group defines the attributes used to describe telemetry in the context of d | `db.operation.name` | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `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.text` | string | The database query being executed. [6] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.response.row_count` | int | Number of rows returned by the database in response to a query. | `10`; `30`; `1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.response.row_count` | int | Number of rows returned by the database in response. | `10`; `30`; `1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.response.status_code` | string | Database response status code. [7] | `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. [8] | `other_sql`; `adabas`; `cache` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index aa209a28bf..bd862ec927 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -46,18 +46,18 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | [`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.row_count`](/docs/attributes-registry/db.md) | int | Cosmos DB row count in result set. | `10`; `20` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Cosmos DB status code. [6] | `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. [7] | `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. [8] | `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. [9] | `Microsoft.DocumentDB` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.row_count`](/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.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.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [11] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [12] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [13] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [14] | `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` | ![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. [15] | `someval`; `55` | `Opt-In` | ![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.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [10] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [11] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [13] | `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` | ![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. [14] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -189,37 +189,35 @@ additional values when introducing new operations. **[4]:** If readily available. The operation name MAY be parsed from the query text, in which case it SHOULD be the first operation name found in the query. -**[5]:** if response was received and operation type is query. - -**[6]:** 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. +**[5]:** 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. -**[7]:** 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. +**[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. -**[8]:** 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]:** 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. -**[9]:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.DocumentDB` for all operations performed by Cosmos DB client. +**[8]:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.DocumentDB` for all operations performed by Cosmos DB client. -**[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +**[9]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. This attribute has stability level RELEASE CANDIDATE. -**[11]:** For sanitization see [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). +**[10]:** 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. -**[12]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). +**[11]:** SHOULD be collected by default only if there is sanitization that excludes sensitive information. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -**[13]:** 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. +**[12]:** 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. -**[14]:** The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled. +**[13]:** The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled. Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it). Default value is "NS". -**[15]:** Query parameters should only be captured when `db.query.text` is parameterized with placeholders. +**[14]:** 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 `` SHOULD be the 0-based index. This attribute has stability level RELEASE CANDIDATE. diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index cb6454bd7d..87f155114f 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -13,7 +13,7 @@ linkTitle: Metrics - [Database operation](#database-operation) - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) - [Experimental](#experimental) - - [Database operations](#database-operations) + - [Database Response](#database-response) - [Metric: `db.client.response.row_count`](#metric-dbclientresponserow_count) - [Connection pools](#connection-pools) - [Metric: `db.client.connection.count`](#metric-dbclientconnectioncount) @@ -230,7 +230,7 @@ Explaining bucket configuration: | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.client.response.row_count` | Histogram | `{row}` | The actual number of records returned by the query. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.response.row_count` | 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 | |---|---|---|---|---|---| From b22d885ee49c1076fe89d6c4489532dbd8c489d0 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 16:18:52 +0530 Subject: [PATCH 63/84] update database metrics --- docs/database/database-metrics.md | 105 ++++++++++++++++++++++++++---- model/database/metrics.yaml | 24 +++++++ 2 files changed, 115 insertions(+), 14 deletions(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 87f155114f..a4734fb33c 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -208,7 +208,7 @@ The following metric instruments describe database query response. #### Metric: `db.client.response.row_count` -This metric is [recommended][MetricRecommended]. +This metric is [required][MetricRequired]. 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) @@ -234,34 +234,111 @@ Explaining bucket configuration: | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [3] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [4] | ![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. [5] | `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. [6] | `80`; `8080`; `443` | `Conditionally Required` [7] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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) | +| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [12] | `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. [13] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[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. +If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. +This attribute has stability level RELEASE CANDIDATE. + +**[3]:** If readily available. The collection name MAY be parsed from the query text, in which case it SHOULD be the first 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. -**[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. +**[5]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. 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. -**[2]:** If readily available. The operation name MAY be parsed from the query text, in which case it SHOULD be the first operation name found in the query. +**[6]:** If readily available. The operation name MAY be parsed from the query text, in which case it SHOULD be the first operation name found in the query. -**[3]:** 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. +**[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. -**[4]:** If the operation failed and status code is available. +**[8]:** If the operation failed and status code is available. -**[5]:** 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. +**[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. -**[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. +**[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. -**[7]:** If using a port other than the default port for this DBMS and if `server.address` is set. +**[11]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[8]:** 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. +**[12]:** 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. + +**[13]:** 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. + +`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. diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index a81701ecf0..655b3fd674 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -143,3 +143,27 @@ groups: unit: "{row}" stability: experimental extends: attributes.db.client.minimal + attributes: + - ref: db.collection.name + requirement_level: + conditionally_required: > + If readily available. The collection name MAY be parsed from the query text, + in which case it SHOULD be the first collection name in the query. + - 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. \ No newline at end of file From d6482d3d6256e89c7c2f8795859714c4bedd155f Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 16:55:47 +0530 Subject: [PATCH 64/84] updated docs --- docs/database/cosmosdb.md | 57 +++------------------------- model/database/cosmosdb-metrics.yaml | 12 +++++- 2 files changed, 16 insertions(+), 53 deletions(-) diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index bd862ec927..3b7a7c39cb 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -429,61 +429,14 @@ It captures the number of active instances at any given time. Best practices dic | 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. -If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. -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. The operation name MAY be parsed from the query text, in which case it SHOULD be the first 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) +| [`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) | -`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. +**[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. -| 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. +**[2]:** If using a port other than the default port for this DBMS and if `server.address` is set. -| 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) | +**[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. diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml index fd86e68c54..c1d2786cd3 100644 --- a/model/database/cosmosdb-metrics.yaml +++ b/model/database/cosmosdb-metrics.yaml @@ -15,4 +15,14 @@ groups: instrument: updowncounter unit: "{instance}" stability: experimental - extends: attributes.db.cosmosdb.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: 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. From df9563d52e710f2aeaa14272b5e5155a5a6ff5d4 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 16:58:10 +0530 Subject: [PATCH 65/84] added eos --- model/database/metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index 655b3fd674..91cdc1c861 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -166,4 +166,4 @@ groups: recommended: If and only if `network.peer.address` is set. - ref: db.namespace requirement_level: - conditionally_required: If available. \ No newline at end of file + conditionally_required: If available. From 4a0aec0d25607c683011ca9ab1972b8307dd4b84 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 22:11:33 +0530 Subject: [PATCH 66/84] fix identation --- model/database/cosmosdb-metrics.yaml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml index c1d2786cd3..dace0cb56f 100644 --- a/model/database/cosmosdb-metrics.yaml +++ b/model/database/cosmosdb-metrics.yaml @@ -16,13 +16,13 @@ groups: 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. + # 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. From 48dbde6cc193287ddea66066a37c4ecb8813a775 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 22:21:28 +0530 Subject: [PATCH 67/84] Update docs/attributes-registry/db.md Co-authored-by: Justine Cocchi --- docs/attributes-registry/db.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 352d58b279..47530bb41b 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -169,7 +169,7 @@ 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.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 | RU consumed for that operation | `46.18`; `1.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.request_charge` | double | RU 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) | From 3165fbc08a85592a50f0b3cb38d7bd3d1d747097 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 22:21:41 +0530 Subject: [PATCH 68/84] Update docs/database/cosmosdb.md Co-authored-by: Justine Cocchi --- docs/database/cosmosdb.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 3b7a7c39cb..acf52b70d3 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -414,7 +414,7 @@ and SHOULD be provided **at span creation time** (if provided at all): 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 process. Having multiple instances of the SDK client can lead to CPU or memory-related issues. +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. From bf35cfdd7249e25de98af626900b5d25b04236e9 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 22:21:51 +0530 Subject: [PATCH 69/84] Update docs/database/cosmosdb.md Co-authored-by: Justine Cocchi --- docs/database/cosmosdb.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index acf52b70d3..3b6cf42a20 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -323,7 +323,7 @@ Refer [db.cosmosdb.operation.request_charge](#metric-dbcosmosdboperationrequest_ 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 currency within the Azure Cosmos DB database, monitoring their usage is crucial to avoid throttling. +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) From a1dbe8918c1daa5dff16f67b964a254c582b2833 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 22:22:13 +0530 Subject: [PATCH 70/84] Update docs/attributes-registry/db.md Co-authored-by: Justine Cocchi --- docs/attributes-registry/db.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 47530bb41b..2f2cf5fc2d 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -178,7 +178,7 @@ 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.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. From 18fd7dc46a045e92ba859c563ab05b48ebb8a118 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 22:23:10 +0530 Subject: [PATCH 71/84] Update docs/attributes-registry/db.md Co-authored-by: Justine Cocchi --- docs/attributes-registry/db.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 2f2cf5fc2d..038b6e5bda 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -170,7 +170,7 @@ This group defines attributes for Azure Cosmos DB. | `db.cosmosdb.connection_mode` | string | Cosmos client connection mode. | `gateway`; `direct` | ![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 | RU 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.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. From 6b62a17d7497a4d1a100f8c61dd9dbba475e75ff Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 16 Oct 2024 22:43:00 +0530 Subject: [PATCH 72/84] update text change --- docs/attributes-registry/db.md | 10 +++++----- docs/database/cosmosdb.md | 6 +++--- model/database/registry.yaml | 6 +++--- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 038b6e5bda..5df6c2efcd 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -169,15 +169,15 @@ 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.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 | RU 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.request_charge` | double | RU 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. -| Value | Description | Stability | -| --------- | ------------------------------- | ---------------------------------------------------------------- | -| `direct` | Direct connection. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Value | Description | Stability | +| --------- | -------------------------- | ---------------------------------------------------------------- | +| `direct` | Direct connection. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gateway` | Gateway (HTTP) connection. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `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. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 3b6cf42a20..dfc584e52b 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -42,7 +42,7 @@ 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.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 | RU consumed for that operation | `46.18`; `1.0` | `Conditionally Required` when available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.cosmosdb.request_charge`](/docs/attributes-registry/db.md) | double | RU 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) | @@ -52,7 +52,7 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | [`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.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [10] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | `Recommended` [11] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -236,7 +236,7 @@ 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.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. diff --git a/model/database/registry.yaml b/model/database/registry.yaml index cfbf5a9b05..1d7741ab90 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -466,7 +466,7 @@ groups: members: - id: gateway value: "gateway" - brief: Gateway (HTTP) connections mode + brief: Gateway (HTTP) connection. stability: experimental - id: direct value: "direct" @@ -477,12 +477,12 @@ groups: - id: db.cosmosdb.request_charge type: double stability: experimental - brief: RU consumed for that operation + brief: RU 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 From 974f77c98c76c7cc6cef35f086ca98333fb7b9d2 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Fri, 18 Oct 2024 07:20:16 +0530 Subject: [PATCH 73/84] resolved merge conflicts --- docs/attributes-registry/db.md | 86 +++++++++++++++++----------------- docs/database/cosmosdb.md | 22 --------- 2 files changed, 43 insertions(+), 65 deletions(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 5df6c2efcd..48302e919e 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -17,19 +17,19 @@ This group defines the attributes used to describe telemetry in the context of databases. -| Attribute | Type | Description | Examples | Stability | -| -------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `db.client.connection.pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation SHOULD use a combination of parameters that would make the name unique, for example, combining attributes `server.address`, `server.port`, and `db.namespace`, formatted as `server.address:server.port/db.namespace`. Instrumentations that generate connection pool name following different patterns SHOULD document it. | `myDataSource` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.client.connection.state` | string | The state of a connection in the pool | `idle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.collection.name` | string | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.namespace` | string | The name of the database, fully qualified within the server address and port. [2] | `customers`; `test.users` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.operation.batch.size` | int | The number of queries included in a batch operation. [3] | `2`; `3`; `4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.operation.name` | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `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.text` | string | The database query being executed. [6] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.response.row_count` | int | Number of rows returned by the database in response. | `10`; `30`; `1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.response.status_code` | string | Database response status code. [7] | `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. [8] | `other_sql`; `adabas`; `cache` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| ------------------------------------------------------------------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `db.client.connection.pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation SHOULD use a combination of parameters that would make the name unique, for example, combining attributes `server.address`, `server.port`, and `db.namespace`, formatted as `server.address:server.port/db.namespace`. Instrumentations that generate connection pool name following different patterns SHOULD document it. | `myDataSource` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.connection.state` | string | The state of a connection in the pool | `idle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.collection.name` | string | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.namespace` | string | The name of the database, fully qualified within the server address and port. [2] | `customers`; `test.users` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.operation.batch.size` | int | The number of queries included in a batch operation. [3] | `2`; `3`; `4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.operation.name` | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `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.text` | string | The database query being executed. [6] | `SELECT * FROM wuser_table where username = ?`; `SET mykey "WuValue"` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.response.row_count` | int | Number of rows returned by the database in response. | `10`; `30`; `1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.response.status_code` | string | Database response status code. [7] | `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. [8] | `other_sql`; `adabas`; `cache` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query and it SHOULD match the value provided in the query text including any schema and database name prefix. @@ -164,14 +164,14 @@ This group defines attributes for Cassandra. This group defines attributes for Azure Cosmos DB. -| Attribute | Type | Description | Examples | Stability | -| ------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `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.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 | RU 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) | +| Attribute | Type | Description | Examples | Stability | +| ------------------------------------------------------------------------------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `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.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 | RU 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. @@ -194,10 +194,10 @@ This group defines attributes for Azure Cosmos DB. This group defines attributes for Elasticsearch. -| Attribute | Type | Description | Examples | Stability | -| ----------------------------------- | ------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [9] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| --------------------------------------------------------------------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [9] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[9]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names. @@ -205,24 +205,24 @@ This group defines attributes for Elasticsearch. "Describes deprecated db attributes." -| Attribute | Type | Description | Examples | Stability | -| ------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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. | -| `db.jdbc.driver_classname` | string | Removed, no replacement at this time. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed as not used. | -| `db.mongodb.collection` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | -| `db.mssql.instance_name` | string | Deprecated, SQL Server instance is now populated as a part of `db.namespace` attribute. | `MSSQLSERVER` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, no replacement at this time. | -| `db.name` | string | Deprecated, use `db.namespace` instead. | `customers`; `main` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | -| `db.operation` | string | Deprecated, use `db.operation.name` instead. | `findAndModify`; `HMSET`; `SELECT` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.operation.name`. | -| `db.redis.database_index` | int | Deprecated, use `db.namespace` instead. | `0`; `1`; `15` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | -| `db.sql.table` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | -| `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. | +| Attribute | Type | Description | Examples | Stability | +| --------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `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. | +| `db.jdbc.driver_classname` | string | Removed, no replacement at this time. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed as not used. | +| `db.mongodb.collection` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | +| `db.mssql.instance_name` | string | Deprecated, SQL Server instance is now populated as a part of `db.namespace` attribute. | `MSSQLSERVER` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, no replacement at this time. | +| `db.name` | string | Deprecated, use `db.namespace` instead. | `customers`; `main` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | +| `db.operation` | string | Deprecated, use `db.operation.name` instead. | `findAndModify`; `HMSET`; `SELECT` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.operation.name`. | +| `db.redis.database_index` | int | Deprecated, use `db.namespace` instead. | `0`; `1`; `15` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.namespace`. | +| `db.sql.table` | string | Deprecated, use `db.collection.name` instead. | `mytable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.collection.name`. | +| `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. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index dfc584e52b..0186ed8243 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -238,7 +238,6 @@ and SHOULD be provided **at span creation time** (if provided at all): | `direct` | Direct connection. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gateway` | Gateway (HTTP) connection. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - `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 | @@ -249,27 +248,6 @@ and SHOULD be provided **at span creation time** (if provided at all): | `Session` | session | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `Strong` | strong | ![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. - -| 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) | - `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 | From cb1d45ae09f753740fc277d0ba1314aa6d91dff3 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Sat, 19 Oct 2024 08:08:12 +0530 Subject: [PATCH 74/84] updated docs --- docs/attributes-registry/db.md | 2 +- docs/database/cosmosdb.md | 18 +++++++++++++---- docs/database/database-metrics.md | 33 +++++++++++++++++++++++++------ 3 files changed, 42 insertions(+), 11 deletions(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 0057f883fc..2eb13801e2 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -28,7 +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.row_count` | int | Number of rows returned by the database in response. | `10`; `30`; `1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.response.row_count` | int | Number of rows returned by the database in response. | `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) | diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index c1b6a58b4d..8f9166774a 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -348,12 +348,22 @@ Explaining bucket configuration: **[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. -If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. -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. +**[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. The operation name MAY be parsed from the query text, in which case it SHOULD be the first operation name found in the query. +**[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. diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 4926320667..52c9b83a5c 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -288,8 +288,19 @@ Explaining bucket configuration: 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. -If the collection name is parsed from the query text, it SHOULD be the first collection name found in the query 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, otherwise `db.collection.name` SHOULD NOT be captured. + +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. The collection name MAY be parsed from the query text, in which case it SHOULD be the first collection name in the query. @@ -299,12 +310,22 @@ Semantic conventions for individual database systems SHOULD document what `db.na 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. -If the operation name is parsed from the query text, it SHOULD be the first operation name found in the query. -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. +**[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. The operation name MAY be parsed from the query text, in which case it SHOULD be the first operation name found in the query. +**[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. From 89b3b55ff4ec94c1b35790cf46312487b99462d4 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Tue, 22 Oct 2024 06:39:30 +0530 Subject: [PATCH 75/84] updateed docs --- docs/attributes-registry/db.md | 62 ++++++++++++---------------- docs/database/cosmosdb.md | 8 ++-- docs/database/database-metrics.md | 8 ++-- model/database/cosmosdb-metrics.yaml | 4 +- 4 files changed, 37 insertions(+), 45 deletions(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index f55a05ae65..37f5295a33 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.row_count` | int | Number of rows returned by the database in response. | `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 | RU 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.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. | @@ -260,23 +252,23 @@ This group defines attributes for Elasticsearch. `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) | +| 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) | +| `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 diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 8f9166774a..c300460e59 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -13,7 +13,7 @@ linkTitle: Cosmos DB - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) - [Metric: `db.client.response.row_count`](#metric-dbclientresponserow_count) - [Metric: `db.cosmosdb.operation.request_charge`](#metric-dbcosmosdboperationrequest_charge) - - [Metric: `db.cosmosdb.client.active_instances`](#metric-dbcosmosdbclientactive_instances) + - [Metric: `db.cosmosdb.client.active_instance.count`](#metric-dbcosmosdbclientactive_instancecount) @@ -407,13 +407,13 @@ and SHOULD be provided **at span creation time** (if provided at all): -### Metric: `db.cosmosdb.client.active_instances` +### Metric: `db.cosmosdb.client.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. - + @@ -422,7 +422,7 @@ It captures the number of active instances at any given time. Best practices dic | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.cosmosdb.client.active_instances` | UpDownCounter | `{instance}` | Number of active client instances | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.cosmosdb.client.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 | |---|---|---|---|---|---| diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 52c9b83a5c..84c34fe793 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -247,16 +247,16 @@ The following metric instruments describe database query response. #### Metric: `db.client.response.row_count` -This metric is [required][MetricRequired]. +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, 10, 50, 100, 250, 500, 1000, 2000, 5000, 10000]`. +of `[1, 2, 5, 10, 20, 50, 100, 200, 500, 1000, 2000, 5000, 10000]`. Explaining bucket configuration: -1. 1, 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. 250, 500, 1000: These values represent typical workloads where moderate amounts of data are returned in each query. +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. diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml index dace0cb56f..ae96998e6f 100644 --- a/model/database/cosmosdb-metrics.yaml +++ b/model/database/cosmosdb-metrics.yaml @@ -8,9 +8,9 @@ groups: stability: experimental extends: attributes.db.cosmosdb.minimal - - id: metric.db.cosmosdb.client.active_instances + - id: metric.db.cosmosdb.client.active_instance.count type: metric - metric_name: db.cosmosdb.client.active_instances + metric_name: db.cosmosdb.client.active_instance.count brief: "Number of active client instances" instrument: updowncounter unit: "{instance}" From b7244bbc14072f00051c6302eb078f99ed7cf75e Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Tue, 22 Oct 2024 08:36:15 +0530 Subject: [PATCH 76/84] Update model/database/registry.yaml Co-authored-by: Trask Stalnaker --- model/database/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/registry.yaml b/model/database/registry.yaml index 5dc18032ea..1615145dc3 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -511,7 +511,7 @@ groups: - id: db.cosmosdb.request_charge type: double stability: experimental - brief: RU consumed for the operation. + brief: Request units consumed for the operation. examples: [46.18, 1.0] - id: db.cosmosdb.request_content_length type: int From 80f5659bfb2164db8b6c5d89571971ad712796ae Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Tue, 22 Oct 2024 08:36:40 +0530 Subject: [PATCH 77/84] Update model/database/registry.yaml Co-authored-by: Trask Stalnaker --- model/database/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/database/registry.yaml b/model/database/registry.yaml index 1615145dc3..1ccc746539 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -151,7 +151,7 @@ groups: - id: db.response.row_count type: int stability: experimental - brief: Number of rows returned by the database in response. + 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. From 7db12e89adb354270726935055e429f6a3d0aaac Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Tue, 22 Oct 2024 15:15:23 +0530 Subject: [PATCH 78/84] updated docs --- docs/attributes-registry/db.md | 4 ++-- docs/database/cosmosdb.md | 22 +++++++++++----------- model/database/cosmosdb-metrics.yaml | 8 ++++---- 3 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 37f5295a33..8a44b421bf 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -28,7 +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.row_count` | int | Number of rows returned by the database in response. | `10`; `30`; `1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.response.row_count` | 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) | @@ -195,7 +195,7 @@ 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.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 | RU consumed for the operation. | `46.18`; `1.0` | ![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) | diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index c300460e59..f80d45c368 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -12,8 +12,8 @@ linkTitle: Cosmos DB - [Operation Level Metrics](#operation-level-metrics) - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) - [Metric: `db.client.response.row_count`](#metric-dbclientresponserow_count) - - [Metric: `db.cosmosdb.operation.request_charge`](#metric-dbcosmosdboperationrequest_charge) - - [Metric: `db.cosmosdb.client.active_instance.count`](#metric-dbcosmosdbclientactive_instancecount) + - [Metric: `db.client.cosmosdb.operation.request_charge`](#metric-dbclientcosmosdboperationrequest_charge) + - [Metric: `db.client.cosmosdb.active_instance.count`](#metric-dbclientcosmosdbactive_instancecount) @@ -42,7 +42,7 @@ 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.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 | RU consumed for the operation. | `46.18`; `1.0` | `Conditionally Required` when 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) | @@ -296,7 +296,7 @@ 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.cosmosdb.operation.request_charge](#metric-dbcosmosdboperationrequest_charge) metrics for dimensions. +Refer [db.client.cosmosdb.operation.request_charge](#metric-dbclientcosmosdboperationrequest_charge) metrics for dimensions. ### Metric: `db.client.response.row_count` @@ -304,9 +304,9 @@ 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.row_count](/docs/database/database-metrics.md#metric-dbclientresponserow_count) definition. -Refer [db.cosmosdb.operation.request_charge](#metric-dbcosmosdboperationrequest_charge) metrics for dimensions. +Refer [db.client.cosmosdb.operation.request_charge](#metric-dbclientcosmosdboperationrequest_charge) metrics for dimensions. -### Metric: `db.cosmosdb.operation.request_charge` +### Metric: `db.client.cosmosdb.operation.request_charge` This metric is [required][MetricRequired]. @@ -323,7 +323,7 @@ Explaining bucket configuration: 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. - + @@ -332,7 +332,7 @@ Explaining bucket configuration: | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.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) | +| `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 | |---|---|---|---|---|---| @@ -407,13 +407,13 @@ and SHOULD be provided **at span creation time** (if provided at all): -### Metric: `db.cosmosdb.client.active_instance.count` +### 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. - + @@ -422,7 +422,7 @@ It captures the number of active instances at any given time. Best practices dic | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.cosmosdb.client.active_instance.count` | UpDownCounter | `{instance}` | Number of active client instances | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.cosmosdb.client.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 | |---|---|---|---|---|---| diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml index ae96998e6f..ef34c0dc3a 100644 --- a/model/database/cosmosdb-metrics.yaml +++ b/model/database/cosmosdb-metrics.yaml @@ -1,16 +1,16 @@ groups: - - id: metric.db.cosmosdb.operation.request_charge + - id: metric.db.client.cosmosdb.operation.request_charge type: metric - metric_name: db.cosmosdb.operation.request_charge + 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.cosmosdb.client.active_instance.count + - id: metric.db.client.cosmosdb.active_instance.count type: metric - metric_name: db.cosmosdb.client.active_instance.count + metric_name: db.client.cosmosdb.client.active_instance.count brief: "Number of active client instances" instrument: updowncounter unit: "{instance}" From e6147526818c7e4a13c15fec70f7d3cbc1d9f9cf Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Wed, 23 Oct 2024 11:20:52 +0530 Subject: [PATCH 79/84] renamed metrics --- docs/database/cosmosdb.md | 2 +- model/database/cosmosdb-metrics.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index f80d45c368..2e64b37a62 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -422,7 +422,7 @@ It captures the number of active instances at any given time. Best practices dic | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.client.cosmosdb.client.active_instance.count` | UpDownCounter | `{instance}` | Number of active client instances | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `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 | |---|---|---|---|---|---| diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml index ef34c0dc3a..3946880699 100644 --- a/model/database/cosmosdb-metrics.yaml +++ b/model/database/cosmosdb-metrics.yaml @@ -10,7 +10,7 @@ groups: - id: metric.db.client.cosmosdb.active_instance.count type: metric - metric_name: db.client.cosmosdb.client.active_instance.count + metric_name: db.client.cosmosdb.active_instance.count brief: "Number of active client instances" instrument: updowncounter unit: "{instance}" From 3f0efe304892491878e77846990c46b6d2ab2212 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Fri, 25 Oct 2024 23:06:08 +0530 Subject: [PATCH 80/84] fix row count metrics name --- .chloggen/users_sourabhjain_otelcosmosmetrics.yaml | 2 +- docs/database/cosmosdb.md | 6 +++--- docs/database/database-metrics.md | 4 ++-- model/database/metrics.yaml | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml b/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml index 092310bdc8..aef284d717 100644 --- a/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml +++ b/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml @@ -10,7 +10,7 @@ change_type: enhancement 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.row_count` database metric and several operation level metrics for Azure Cosmos DB." +note: "Added new common `db.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. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 2e64b37a62..0485133386 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -11,7 +11,7 @@ linkTitle: Cosmos DB - [Example](#example) - [Operation Level Metrics](#operation-level-metrics) - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) - - [Metric: `db.client.response.row_count`](#metric-dbclientresponserow_count) + - [Metric: `db.response.returned_rows`](#metric-dbresponsereturned_rows) - [Metric: `db.client.cosmosdb.operation.request_charge`](#metric-dbclientcosmosdboperationrequest_charge) - [Metric: `db.client.cosmosdb.active_instance.count`](#metric-dbclientcosmosdbactive_instancecount) @@ -298,11 +298,11 @@ It captures the total time taken by an Azure Cosmos DB operation. This metric fo Refer [db.client.cosmosdb.operation.request_charge](#metric-dbclientcosmosdboperationrequest_charge) metrics for dimensions. -### Metric: `db.client.response.row_count` +### Metric: `db.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.row_count](/docs/database/database-metrics.md#metric-dbclientresponserow_count) definition. +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.response.returned_rows](/docs/database/database-metrics.md#metric-dbclientresponserow_count) definition. Refer [db.client.cosmosdb.operation.request_charge](#metric-dbclientcosmosdboperationrequest_charge) metrics for dimensions. diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 84c34fe793..052d244cff 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -260,7 +260,7 @@ Explaining bucket configuration: 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. - + @@ -269,7 +269,7 @@ Explaining bucket configuration: | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.client.response.row_count` | Histogram | `{row}` | The actual number of records returned by the database operation. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.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 | |---|---|---|---|---|---| diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index b9979e1185..a75e93569c 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -132,9 +132,9 @@ groups: - ref: db.client.connection.pool.name requirement_level: required - - id: metric.db.client.response.row_count + - id: metric.db.response.returned_rows type: metric - metric_name: db.client.response.row_count + metric_name: db.response.returned_rows brief: "The actual number of records returned by the database operation." instrument: histogram unit: "{row}" From 11f1faa6282ccef0cd9e907e1019cc5c56dfd5fe Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Sat, 26 Oct 2024 06:37:16 +0530 Subject: [PATCH 81/84] updated row_count to retiurned_rows --- .chloggen/users_sourabhjain_otelcosmosmetrics.yaml | 2 +- docs/attributes-registry/db.md | 2 +- docs/database/cosmosdb.md | 8 ++++---- docs/database/database-metrics.md | 8 ++++---- model/database/metrics.yaml | 4 ++-- model/database/registry.yaml | 2 +- model/database/spans.yaml | 2 +- 7 files changed, 14 insertions(+), 14 deletions(-) diff --git a/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml b/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml index aef284d717..34a4940925 100644 --- a/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml +++ b/.chloggen/users_sourabhjain_otelcosmosmetrics.yaml @@ -10,7 +10,7 @@ change_type: enhancement 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.response.returned_rows` database metric and several operation level metrics for Azure Cosmos DB." +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. diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 8a44b421bf..bc6f42e7f4 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -28,7 +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.row_count` | int | Number of rows returned by the operation. | `10`; `30`; `1000` | ![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) | diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 0485133386..3b75b969ae 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -11,7 +11,7 @@ linkTitle: Cosmos DB - [Example](#example) - [Operation Level Metrics](#operation-level-metrics) - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) - - [Metric: `db.response.returned_rows`](#metric-dbresponsereturned_rows) + - [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) @@ -46,7 +46,7 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | [`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.row_count`](/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.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) | @@ -298,11 +298,11 @@ It captures the total time taken by an Azure Cosmos DB operation. This metric fo Refer [db.client.cosmosdb.operation.request_charge](#metric-dbclientcosmosdboperationrequest_charge) metrics for dimensions. -### Metric: `db.response.returned_rows` +### 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.response.returned_rows](/docs/database/database-metrics.md#metric-dbclientresponserow_count) definition. +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. diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 052d244cff..dde8c2d0b6 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -14,7 +14,7 @@ linkTitle: Metrics - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration) - [Experimental](#experimental) - [Database Response](#database-response) - - [Metric: `db.client.response.row_count`](#metric-dbclientresponserow_count) + - [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) @@ -245,7 +245,7 @@ and SHOULD be provided **at span creation time** (if provided at all): The following metric instruments describe database query response. -#### Metric: `db.client.response.row_count` +#### Metric: `db.client.response.returned_rows` This metric is [recommended][MetricRecommended]. @@ -260,7 +260,7 @@ Explaining bucket configuration: 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. - + @@ -269,7 +269,7 @@ Explaining bucket configuration: | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.response.returned_rows` | Histogram | `{row}` | The actual number of records returned by the database operation. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `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 | |---|---|---|---|---|---| diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index a75e93569c..bf114d122b 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -132,9 +132,9 @@ groups: - ref: db.client.connection.pool.name requirement_level: required - - id: metric.db.response.returned_rows + - id: metric.db.client.response.returned_rows type: metric - metric_name: db.response.returned_rows + metric_name: db.client.response.returned_rows brief: "The actual number of records returned by the database operation." instrument: histogram unit: "{row}" diff --git a/model/database/registry.yaml b/model/database/registry.yaml index 1ccc746539..c67c035cc2 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -148,7 +148,7 @@ groups: This attribute has stability level RELEASE CANDIDATE. examples: ["102", "ORA-17002", "08P01", "404"] - - id: db.response.row_count + - id: db.response.returned_rows type: int stability: experimental brief: Number of rows returned by the operation. diff --git a/model/database/spans.yaml b/model/database/spans.yaml index ac877d88f0..bf2a6e76a6 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -570,7 +570,7 @@ groups: examples: ["200", "201"] requirement_level: conditionally_required: if response was received - - ref: db.response.row_count + - ref: db.response.returned_rows brief: > Cosmos DB row count in result set. examples: [10, 20] From 9a8cb9abc6f19528ec6577364a520a373a0479c5 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Sun, 27 Oct 2024 06:58:36 +0530 Subject: [PATCH 82/84] Update model/database/metrics.yaml Co-authored-by: Trask Stalnaker --- model/database/metrics.yaml | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index bf114d122b..5ae4d801b9 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -139,13 +139,8 @@ groups: instrument: histogram unit: "{row}" stability: experimental - extends: attributes.db.client.minimal + extends: attributes.db.client.with_query_and_collection attributes: - - ref: db.collection.name - requirement_level: - conditionally_required: > - If readily available. The collection name MAY be parsed from the query text, - in which case it SHOULD be the first collection name in the query. - ref: db.system # TODO: Not adding to the minimal because of https://github.com/open-telemetry/build-tools/issues/192 requirement_level: required @@ -164,3 +159,5 @@ groups: - ref: db.namespace requirement_level: conditionally_required: If available. + - ref: db.query.text + requirement_level: opt_in From 1daad9ce9b578e118754e39555eaa15ba1600ef7 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Sun, 27 Oct 2024 07:06:35 +0530 Subject: [PATCH 83/84] update docs --- docs/database/database-metrics.md | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index dde8c2d0b6..a82e7ccbd8 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -280,9 +280,11 @@ Explaining bucket configuration: | [`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) | -| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [12] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this database system. | ![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. [13] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![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. @@ -303,7 +305,7 @@ SHOULD NOT be captured. This attribute has stability level RELEASE CANDIDATE. -**[3]:** If readily available. The collection name MAY be parsed from the query text, in which case it SHOULD be the first collection name in the query. +**[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. @@ -341,10 +343,26 @@ Instrumentations SHOULD document how `error.type` is populated. **[11]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[12]:** 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. +**[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. -**[13]:** 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. +**[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. From 164d7e9db749ee01ddb43bfb3ba0a435351133ac Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Tue, 29 Oct 2024 00:52:48 +0530 Subject: [PATCH 84/84] added returned_rows attribute --- docs/database/cassandra.md | 1 + 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/spans.yaml | 1 + 8 files changed, 8 insertions(+) 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/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/spans.yaml b/model/database/spans.yaml index bf2a6e76a6..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