operation count

open-telemetry · Oct 18, 2024 · 2ee5602 · 2ee5602
1 parent 974f77c
commit 2ee5602
Show file tree

Hide file tree

Showing 7 changed files with 219 additions and 22 deletions.
diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md
@@ -169,6 +169,7 @@ This group defines attributes for Azure Cosmos DB.
 | <a id="db-cosmosdb-client-id" href="#db-cosmosdb-client-id">`db.cosmosdb.client_id`</a>                                        | string | Unique Cosmos client instance id.                                                                       | `3ba4827d-4422-483f-b59f-85b74211c11d`                                  | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="db-cosmosdb-connection-mode" href="#db-cosmosdb-connection-mode">`db.cosmosdb.connection_mode`</a>                      | string | Cosmos client connection mode.                                                                          | `gateway`; `direct`                                                     | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="db-cosmosdb-consistency-level" href="#db-cosmosdb-consistency-level">`db.cosmosdb.consistency_level`</a>                | 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) |
+| <a id="db-cosmosdb-regions-contacted" href="#db-cosmosdb-regions-contacted">`db.cosmosdb.regions_contacted`</a>                | string | Comma separated list of regions contacted by Azure Cosmos DB operations.                                | `North Central US,Central US`; `East US 2,North Central US`             | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="db-cosmosdb-request-charge" href="#db-cosmosdb-request-charge">`db.cosmosdb.request_charge`</a>                         | double | RU consumed for the operation.                                                                          | `46.18`; `1.0`                                                          | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="db-cosmosdb-request-content-length" href="#db-cosmosdb-request-content-length">`db.cosmosdb.request_content_length`</a> | int    | Request payload size in bytes.                                                                          |                                                                         | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="db-cosmosdb-sub-status-code" href="#db-cosmosdb-sub-status-code">`db.cosmosdb.sub_status_code`</a>                      | 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
diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md
@@ -11,6 +11,7 @@ linkTitle: Metrics
 <!-- toc -->
 
 - [Database operation](#database-operation)
+  - [Metric: `db.client.operation.count`](#metric-dbclientoperationcount)
   - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration)
 - [Experimental](#experimental)
   - [Database Response](#database-response)
@@ -56,6 +57,140 @@ linkTitle: Metrics
 
 ## Database operation
 
+### Metric: `db.client.operation.count`
+
+This metric is [required][MetricRequired].
+
+<!-- semconv metric.db.client.operation.count -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+| Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `db.client.operation.count` | Counter | `{operations}` | The numbers of client operations. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `other_sql`; `adabas`; `cache` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [2] | `public.users`; `customers` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [4] | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [5] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [7] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [9] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Conditionally Required` [11] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`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.
+
+**[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.
+
+**[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.
+
+**[7]:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
+Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
+This attribute has stability level RELEASE CANDIDATE.
+
+**[8]:** If the operation failed and status code is available.
+
+**[9]:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
+When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
+Instrumentations SHOULD document how `error.type` is populated.
+
+**[10]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+
+**[11]:** If using a port other than the default port for this DBMS and if `server.address` is set.
+
+**[12]:** 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.
+
+| 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) |
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
 ### Metric: `db.client.operation.duration`
 
 **Status**: [Release Candidate][DocumentStatus]

diff --git a/model/database/common.yaml b/model/database/common.yaml
@@ -59,3 +59,8 @@ groups:
       - ref: db.cosmosdb.consistency_level
         requirement_level:
           conditionally_required: If available.
+      - ref: db.cosmosdb.regions_contacted
+        brief: >
+          List of regions contacted by the client during a given operation.
+        requirement_level:
+          conditionally_required: If available
diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml
@@ -34,6 +34,39 @@ groups:
         requirement_level:
           conditionally_required: If available.
 
+  - id: metric.db.client.operation.count
+    type: metric
+    metric_name: db.client.operation.count
+    brief: "The numbers of client operations."
+    instrument: counter
+    unit: "{operations}"
+    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.
+
   - id: metric.db.client.connection.count
     type: metric
     metric_name: db.client.connection.count

diff --git a/model/database/registry.yaml b/model/database/registry.yaml
@@ -509,6 +509,11 @@ groups:
         stability: experimental
         brief: Account or request [consistency level](https://learn.microsoft.com/azure/cosmos-db/consistency-levels).
         examples: ["Eventual", "ConsistentPrefix", "BoundedStaleness", "Strong", "Session"]
+      - id: db.cosmosdb.regions_contacted
+        type: string
+        stability: experimental
+        brief: Comma separated list of regions contacted by Azure Cosmos DB operations.
+        examples: ["North Central US,Central US", "East US 2,North Central US"]
 
   - id: registry.db.elasticsearch
     type: attribute_group

diff --git a/model/database/spans.yaml b/model/database/spans.yaml
@@ -707,3 +707,8 @@ groups:
       - ref: db.cosmosdb.consistency_level
         requirement_level:
           conditionally_required: If available.
+      - ref: db.cosmosdb.regions_contacted
+        note: >
+            When `db.cosmosdb.regions_contacted` attribute is populated, it would indicate than the operation was performed on multiple regions i.e. cross-regional call.
+        requirement_level:
+          conditionally_required: If available.