diff --git a/.chloggen/add-db-operation-time-and-memory-metrics.yaml b/.chloggen/add-db-operation-time-and-memory-metrics.yaml new file mode 100755 index 000000000..2b518b4a5 --- /dev/null +++ b/.chloggen/add-db-operation-time-and-memory-metrics.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: db + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add database operation metrics related to memory and time spent + +# 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: [ 723 ] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 89b9510cb..8bb8311d9 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -106,9 +106,10 @@ of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. | [`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) | | [`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` [9] | ![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. [10] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this database system. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`thread.id`](/docs/attributes-registry/thread.md) | int | Current "managed" thread ID (as opposed to OS thread ID). | `42` | `Conditionally Required` [10] | ![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. [11] | `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. [11] | `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. [12] | `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. @@ -134,10 +135,12 @@ For batch operations, if the individual operations are known to have the same op **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[10]:** 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. +**[10]:** If available and stable for the lifetime of the operation. + +**[11]:** 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. -**[11]:** 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. diff --git a/model/metrics/database-metrics.yaml b/model/metrics/database-metrics.yaml index 716776b3c..18b720144 100644 --- a/model/metrics/database-metrics.yaml +++ b/model/metrics/database-metrics.yaml @@ -33,6 +33,154 @@ groups: - ref: db.namespace requirement_level: conditionally_required: If available. + - ref: thread.id + requirement_level: + conditionally_required: If available and stable for the lifetime of the operation. + + - id: metric.db.client.operation.wait_time + type: metric + metric_name: db.client.operation.wait_time + brief: "Time spent waiting by database client operations, by category (if available)." + instrument: histogram + unit: "s" + 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. + - ref: thread.id + requirement_level: + conditionally_required: If available and stable for the lifetime of the operation. + + - id: metric.db.client.operation.cpu_time + type: metric + metric_name: db.client.operation.cpu_time + brief: "CPU time spent for database client operations." + instrument: histogram + unit: "s" + 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. + - ref: thread.id + requirement_level: + conditionally_required: If available and stable for the lifetime of the operation. + + - id: metric.db.client.operation.pages_scanned + type: metric + metric_name: db.client.operation.pages_scanned + brief: "Pages scanned for database client operations." + instrument: histogram + unit: "{pages}" + 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. + - ref: thread.id + requirement_level: + conditionally_required: If available and stable for the lifetime of the operation. + + - id: metric.db.client.operation.used_memory + type: metric + metric_name: db.client.operation.used_memory + brief: "Memory used for database client operations." + instrument: histogram + unit: "By" + 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. + - ref: thread.id + requirement_level: + conditionally_required: If available and stable for the lifetime of the operation. + - id: metric.db.client.connection.count type: metric metric_name: db.client.connection.count