From b06f0565ec5f8b6c5d2c2f97fc7bdd6c3d2ab149 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 7 Nov 2024 17:54:05 -0800 Subject: [PATCH] Generalize db.query.parameter. to db.operation.parameter. --- .chloggen/1559.yaml | 22 +++++++++++++++++++ docs/attributes-registry/db.md | 7 +++--- docs/database/cassandra.md | 8 +++---- docs/database/cosmosdb.md | 8 +++---- docs/database/database-spans.md | 8 +++---- docs/database/mariadb.md | 8 +++---- docs/database/mssql.md | 8 +++---- docs/database/mysql.md | 8 +++---- docs/database/postgresql.md | 8 +++---- docs/database/redis.md | 8 +++---- docs/database/sql.md | 8 +++---- docs/non-normative/db-migration.md | 2 +- .../deprecated/registry-deprecated.yaml | 8 +++++++ model/database/registry.yaml | 9 ++++---- model/database/spans.yaml | 8 +++---- 15 files changed, 80 insertions(+), 48 deletions(-) create mode 100644 .chloggen/1559.yaml diff --git a/.chloggen/1559.yaml b/.chloggen/1559.yaml new file mode 100644 index 0000000000..3c4b353889 --- /dev/null +++ b/.chloggen/1559.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: breaking + +# 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: Generalize `db.query.parameter.` to `db.operation.parameter.` + +# 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: [ 1559 ] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index bc6f42e7f4..02bb9aede5 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -25,7 +25,7 @@ This group defines the attributes used to describe telemetry in the context of d | `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.operation.parameter.` | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [5] | `someval`; `55` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.query.summary` | string | Low cardinality representation of a database query text. [6] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.query.text` | string | The database query being executed. [7] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.response.returned_rows` | int | Number of rows returned by the operation. | `10`; `30`; `1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -71,8 +71,8 @@ system specific term if more applicable. This attribute has stability level RELEASE CANDIDATE. -**[5]:** 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. +**[5]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. **[6]:** `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. @@ -245,6 +245,7 @@ This group defines attributes for Elasticsearch. | `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.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. | `someval`; `55` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `db.operation.parameter`. | | `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`. | diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index ccfa8ad091..1c1d76c5fe 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -40,7 +40,7 @@ The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend a | [`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) | -| [`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. [18] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [18] | `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. @@ -111,14 +111,14 @@ Even though parameterized query text can potentially have sensitive data, by usi This attribute has stability level RELEASE CANDIDATE. **[15]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[16]:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. **[17]:** 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. -**[18]:** 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. +**[18]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 3b75b969ae..228aedcfb4 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -58,7 +58,7 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [12] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [13] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, 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. @@ -217,7 +217,7 @@ Even though parameterized query text can potentially have sensitive data, by usi This attribute has stability level RELEASE CANDIDATE. **[13]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[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. @@ -225,8 +225,8 @@ Parameterized query text SHOULD be collected by default (the query parameter val 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. -If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 06c08b0597..0cd85380c5 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -112,7 +112,7 @@ These attributes will usually be the same for all operations performed over the | [`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) | -| [`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. [19] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [19] | `someval`; `55` | `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. @@ -186,15 +186,15 @@ Even though parameterized query text can potentially have sensitive data, by usi This attribute has stability level RELEASE CANDIDATE. **[16]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[17]:** 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. **[18]:** 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. -**[19]:** 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. +**[19]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md index 99aced8daf..c1f9ab8bac 100644 --- a/docs/database/mariadb.md +++ b/docs/database/mariadb.md @@ -32,7 +32,7 @@ The Semantic Conventions for *MariaDB* extend and override the [Database Semanti | [`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) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, 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. @@ -126,12 +126,12 @@ Even though parameterized query text can potentially have sensitive data, by usi This attribute has stability level RELEASE CANDIDATE. **[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[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]:** 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. +**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 35519e5fd6..c6979a3f72 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -32,7 +32,7 @@ The Semantic Conventions for the *Microsoft SQL Server* extend and override the | [`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) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, 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. @@ -96,12 +96,12 @@ Even though parameterized query text can potentially have sensitive data, by usi This attribute has stability level RELEASE CANDIDATE. **[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[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]:** 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. +**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/database/mysql.md b/docs/database/mysql.md index 65e273688a..a82f4ead1e 100644 --- a/docs/database/mysql.md +++ b/docs/database/mysql.md @@ -32,7 +32,7 @@ The Semantic Conventions for *MySQL* extend and override the [Database Semantic | [`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) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, 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. @@ -126,12 +126,12 @@ Even though parameterized query text can potentially have sensitive data, by usi This attribute has stability level RELEASE CANDIDATE. **[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[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]:** 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. +**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md index 23950fbe41..392c270a16 100644 --- a/docs/database/postgresql.md +++ b/docs/database/postgresql.md @@ -32,7 +32,7 @@ The Semantic Conventions for *PostgreSQL* extend and override the [Database Sema | [`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) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, 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. @@ -133,12 +133,12 @@ Even though parameterized query text can potentially have sensitive data, by usi This attribute has stability level RELEASE CANDIDATE. **[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[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]:** 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. +**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/database/redis.md b/docs/database/redis.md index cc09b36948..0ca3499819 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -31,7 +31,7 @@ The Semantic Conventions for [Redis](https://redis.com/) extend and override the | [`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` | ![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) | -| [`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.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, 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]:** A connection's currently associated database index may change during its lifetime, e.g. from executing `SELECT `. @@ -79,14 +79,14 @@ This attribute has stability level RELEASE CANDIDATE. **[11]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[12]:** 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. -**[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. +**[14]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/database/sql.md b/docs/database/sql.md index 66773c90bd..1caa408be9 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -56,7 +56,7 @@ Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic co | [`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) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, 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. @@ -158,12 +158,12 @@ Even though parameterized query text can potentially have sensitive data, by usi This attribute has stability level RELEASE CANDIDATE. **[14]:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). **[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]:** 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. +**[16]:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. +If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions diff --git a/docs/non-normative/db-migration.md b/docs/non-normative/db-migration.md index eee1011900..596a665a2c 100644 --- a/docs/non-normative/db-migration.md +++ b/docs/non-normative/db-migration.md @@ -51,7 +51,7 @@ to | `db.cosmosdb.container` → `db.collection.name` | | | New: `db.operation.batch.size` | | | New: `db.response.status_code` | | -| New: `db.query.parameter.` | Opt-In | +| New: `db.operation.parameter.` | Opt-In | | New: `error.type` | | diff --git a/model/database/deprecated/registry-deprecated.yaml b/model/database/deprecated/registry-deprecated.yaml index 04bcc26ec3..ce41bced8f 100644 --- a/model/database/deprecated/registry-deprecated.yaml +++ b/model/database/deprecated/registry-deprecated.yaml @@ -36,6 +36,14 @@ groups: deprecated: "Replaced by `db.query.text`." stability: experimental examples: ['SELECT * FROM wuser_table', 'SET mykey "WuValue"'] + - id: db.query.parameter + type: template[string] + brief: > + 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. + deprecated: "Replaced by `db.operation.parameter`." + stability: experimental + examples: ["someval", "55"] - id: db.cassandra.table type: string stability: experimental diff --git a/model/database/registry.yaml b/model/database/registry.yaml index c67c035cc2..2913ed4e64 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -87,18 +87,19 @@ groups: "SELECT * FROM wuser_table where username = ?", 'SET mykey ?', ] - - id: db.query.parameter + - id: db.operation.parameter type: template[string] stability: experimental # RELEASE CANDIDATE brief: > - A query parameter used in `db.query.text`, with `` being the parameter name, + A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. note: > - 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. + If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match + up with the parameterized placeholders present in `db.query.text`. + This attribute has stability level RELEASE CANDIDATE. examples: ["someval", "55"] - id: db.query.summary diff --git a/model/database/spans.yaml b/model/database/spans.yaml index 551b12bed6..0419ff73f0 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -32,10 +32,10 @@ groups: Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, - see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). + see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). - ref: db.query.summary sampling_relevant: true - - ref: db.query.parameter + - ref: db.operation.parameter requirement_level: opt_in - ref: db.collection.name sampling_relevant: true @@ -334,7 +334,7 @@ groups: Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, - see [`db.query.parameter.`](../../docs/attributes-registry/db.md)). + see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). note: > 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`. @@ -352,7 +352,7 @@ groups: The Redis [simple error](https://redis.io/docs/latest/develop/reference/protocol-spec/#simple-errors) prefix. examples: ["ERR", "WRONGTYPE", "CLUSTERDOWN"] - ref: db.operation.batch.size - - ref: db.query.parameter + - ref: db.operation.parameter requirement_level: opt_in - ref: server.address sampling_relevant: true