Add an option to generate db.query.summary from operation/target, restrict its usage for non-query databases (#2206)
Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>
This commit is contained in:
Liudmila Molkova
GitHub
parent
d6e42db109
commit
b1bfa2ea88
|
|
@ -0,0 +1,4 @@
|
|||
change_type: enhancement
|
||||
component: db
|
||||
note: Add an option to generate `db.query.summary` from operation name and target, remove it from CosmosDB.
|
||||
issues: [2206]
|
||||
|
|
@ -21,7 +21,7 @@ This group defines the attributes used to describe telemetry in the context of d
|
|||
| <a id="db-operation-name" href="#db-operation-name">`db.operation.name`</a> | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` |  |
|
||||
| <a id="db-operation-parameter" href="#db-operation-parameter">`db.operation.parameter.<key>`</a> | string | A database operation parameter, with `<key>` being the parameter name, and the attribute value being a string representation of the parameter value. [5] | `someval`; `55` |  |
|
||||
| <a id="db-query-parameter" href="#db-query-parameter">`db.query.parameter.<key>`</a> | string | A database query parameter, with `<key>` being the parameter name, and the attribute value being a string representation of the parameter value. [6] | `someval`; `55` |  |
|
||||
| <a id="db-query-summary" href="#db-query-summary">`db.query.summary`</a> | string | Low cardinality representation of a database query text. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` |  |
|
||||
| <a id="db-query-summary" href="#db-query-summary">`db.query.summary`</a> | string | Low cardinality summary of a database query. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` |  |
|
||||
| <a id="db-query-text" href="#db-query-text">`db.query.text`</a> | string | The database query being executed. [8] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` |  |
|
||||
| <a id="db-response-returned-rows" href="#db-response-returned-rows">`db.response.returned_rows`</a> | int | Number of rows returned by the operation. | `10`; `30`; `1000` |  |
|
||||
| <a id="db-response-status-code" href="#db-response-status-code">`db.response.status_code`</a> | string | Database response status code. [9] | `102`; `ORA-17002`; `08P01`; `404` |  |
|
||||
|
|
@ -81,8 +81,15 @@ Examples:
|
|||
- For a query `"SELECT * FROM users WHERE username = %(username)s;` with parameter
|
||||
`username = "jdoe"`, the attribute `db.query.parameter.username` SHOULD be set to `"jdoe"`.
|
||||
|
||||
**[7] `db.query.summary`:** `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-query-text) section.
|
||||
**[7] `db.query.summary`:** The query summary 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-query)
|
||||
section.
|
||||
|
||||
**[8] `db.query.text`:** 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.
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@ Spans representing calls to a Cassandra database adhere to the general [Semantic
|
|||
| [`cassandra.query.idempotent`](/docs/attributes-registry/cassandra.md) | boolean | Whether or not the query is idempotent. | | `Recommended` |  |
|
||||
| [`cassandra.speculative_execution.count`](/docs/attributes-registry/cassandra.md) | int | The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. | `0`; `2` | `Recommended` |  |
|
||||
| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [11] | `2`; `3`; `4` | `Recommended` |  |
|
||||
| [`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] |  |
|
||||
| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality summary of a database query. [12] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [13] |  |
|
||||
| [`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] |  |
|
||||
| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` |  |
|
||||
| [`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` |  |
|
||||
|
|
@ -102,10 +102,17 @@ Instrumentations SHOULD document how `error.type` is populated.
|
|||
|
||||
**[11] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
|
||||
|
||||
**[12] `db.query.summary`:** `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-query-text) section.
|
||||
**[12] `db.query.summary`:** The query summary describes a class of database queries and is useful
|
||||
as a grouping key, especially when analyzing telemetry for database
|
||||
calls involving complex queries.
|
||||
|
||||
**[13] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
|
||||
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-query)
|
||||
section.
|
||||
|
||||
**[13] `db.query.summary`:** if available through instrumentation hooks or if the instrumentation supports generating a query summary.
|
||||
|
||||
**[14] `db.query.text`:** 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.
|
||||
|
|
|
|||
|
|
@ -63,12 +63,11 @@ Semantic conventions described in this document apply to the call-level spans on
|
|||
| [`azure.client.id`](/docs/attributes-registry/azure.md) | string | The unique identifier of the client instance. | `3ba4827d-4422-483f-b59f-85b74211c11d`; `storage-client-1` | `Recommended` |  |
|
||||
| [`azure.cosmosdb.request.body.size`](/docs/attributes-registry/azure.md) | int | Request payload size in bytes. | | `Recommended` |  |
|
||||
| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [9] | `2`; `3`; `4` | `Recommended` |  |
|
||||
| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [10] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [11] |  |
|
||||
| [`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] |  |
|
||||
| [`db.stored_procedure.name`](/docs/attributes-registry/db.md) | string | The name of a stored procedure within the database. [14] | `GetCustomer` | `Recommended` [15] |  |
|
||||
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [16] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
| [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [17] | `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` |  |
|
||||
| [`db.query.parameter.<key>`](/docs/attributes-registry/db.md) | string | A database query parameter, with `<key>` being the parameter name, and the attribute value being a string representation of the parameter value. [18] | `someval`; `55` | `Opt-In` |  |
|
||||
| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [10] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` |  |
|
||||
| [`db.stored_procedure.name`](/docs/attributes-registry/db.md) | string | The name of a stored procedure within the database. [11] | `GetCustomer` | `Recommended` [12] |  |
|
||||
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [13] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
| [`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` |  |
|
||||
| [`db.query.parameter.<key>`](/docs/attributes-registry/db.md) | string | A database query parameter, with `<key>` being the parameter name, and the attribute value being a string representation of the parameter value. [15] | `someval`; `55` | `Opt-In` |  |
|
||||
|
||||
**[1] `db.operation.name`:** The `db.operation.name` has the following list of well-known values.
|
||||
If one of them applies, then the respective value MUST be used.
|
||||
|
|
@ -212,33 +211,25 @@ Instrumentations SHOULD document how `error.type` is populated.
|
|||
|
||||
**[9] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
|
||||
|
||||
**[10] `db.query.summary`:** `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-query-text) section.
|
||||
|
||||
**[11] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
|
||||
|
||||
**[12] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext).
|
||||
**[10] `db.query.text`:** 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.
|
||||
Parameterized query text SHOULD NOT be sanitized. 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.
|
||||
|
||||
**[13] `db.query.text`:** 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.<key>`](/docs/attributes-registry/db.md)).
|
||||
|
||||
**[14] `db.stored_procedure.name`:** It is RECOMMENDED to capture the value as provided by the application
|
||||
**[11] `db.stored_procedure.name`:** It is RECOMMENDED to capture the value as provided by the application
|
||||
without attempting to do any case normalization.
|
||||
|
||||
For batch operations, if the individual operations are known to have the same
|
||||
stored procedure name then that stored procedure name SHOULD be used.
|
||||
|
||||
**[15] `db.stored_procedure.name`:** If operation applies to a specific stored procedure.
|
||||
**[12] `db.stored_procedure.name`:** If operation applies to a specific stored procedure.
|
||||
|
||||
**[16] `server.address`:** 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] `server.address`:** 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.
|
||||
|
||||
**[17] `user_agent.original`:** The user-agent value is generated by SDK which is a combination of<br> `sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'<br> `direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'<br> `number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'<br> `type_of_machine_architecture` : Machine architecture. e.g. 'X64'<br> `operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'<br> `runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'<br> `failover_information` : Generated key to determine if region failover enabled.
|
||||
**[14] `user_agent.original`:** The user-agent value is generated by SDK which is a combination of<br> `sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'<br> `direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'<br> `number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'<br> `type_of_machine_architecture` : Machine architecture. e.g. 'X64'<br> `operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'<br> `runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'<br> `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".
|
||||
|
||||
**[18] `db.query.parameter.<key>`:** If a query parameter has no name and instead is referenced only by index,
|
||||
**[15] `db.query.parameter.<key>`:** If a query parameter has no name and instead is referenced only by index,
|
||||
then `<key>` SHOULD be the 0-based index.
|
||||
|
||||
`db.query.parameter.<key>` SHOULD match
|
||||
|
|
@ -260,8 +251,6 @@ and SHOULD be provided **at span creation time** (if provided at all):
|
|||
* [`db.collection.name`](/docs/attributes-registry/db.md)
|
||||
* [`db.namespace`](/docs/attributes-registry/db.md)
|
||||
* [`db.operation.name`](/docs/attributes-registry/db.md)
|
||||
* [`db.query.summary`](/docs/attributes-registry/db.md)
|
||||
* [`db.query.text`](/docs/attributes-registry/db.md)
|
||||
* [`server.address`](/docs/attributes-registry/server.md)
|
||||
* [`server.port`](/docs/attributes-registry/server.md)
|
||||
|
||||
|
|
|
|||
|
|
@ -88,7 +88,7 @@ of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`.
|
|||
| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [7] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [8] |  |
|
||||
| [`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. |  |
|
||||
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Conditionally Required` [11] |  |
|
||||
| [`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] |  |
|
||||
| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality summary of a database query. [12] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [13] |  |
|
||||
| [`db.stored_procedure.name`](/docs/attributes-registry/db.md) | string | The name of a stored procedure within the database. [14] | `GetCustomer` | `Recommended` [15] |  |
|
||||
| [`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` If applicable for this database system. |  |
|
||||
| [`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. |  |
|
||||
|
|
@ -143,10 +143,17 @@ Instrumentations SHOULD document how `error.type` is populated.
|
|||
|
||||
**[11] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
|
||||
|
||||
**[12] `db.query.summary`:** `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-query-text) section.
|
||||
**[12] `db.query.summary`:** The query summary describes a class of database queries and is useful
|
||||
as a grouping key, especially when analyzing telemetry for database
|
||||
calls involving complex queries.
|
||||
|
||||
**[13] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
|
||||
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-query)
|
||||
section.
|
||||
|
||||
**[13] `db.query.summary`:** if available through instrumentation hooks or if the instrumentation supports generating a query summary.
|
||||
|
||||
**[14] `db.stored_procedure.name`:** It is RECOMMENDED to capture the value as provided by the application
|
||||
without attempting to do any case normalization.
|
||||
|
|
@ -269,7 +276,7 @@ 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] |  |
|
||||
| [`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. |  |
|
||||
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Conditionally Required` [11] |  |
|
||||
| [`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] |  |
|
||||
| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality summary of a database query. [12] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [13] |  |
|
||||
| [`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. |  |
|
||||
| [`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. |  |
|
||||
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
|
|
@ -323,10 +330,17 @@ Instrumentations SHOULD document how `error.type` is populated.
|
|||
|
||||
**[11] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
|
||||
|
||||
**[12] `db.query.summary`:** `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-query-text) section.
|
||||
**[12] `db.query.summary`:** The query summary describes a class of database queries and is useful
|
||||
as a grouping key, especially when analyzing telemetry for database
|
||||
calls involving complex queries.
|
||||
|
||||
**[13] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
|
||||
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-query)
|
||||
section.
|
||||
|
||||
**[13] `db.query.summary`:** if available through instrumentation hooks or if the instrumentation supports generating a query summary.
|
||||
|
||||
**[14] `network.peer.address`:** 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.
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ linkTitle: Spans
|
|||
- [Span definition](#span-definition)
|
||||
- [Notes and well-known identifiers for `db.system.name`](#notes-and-well-known-identifiers-for-dbsystemname)
|
||||
- [Sanitization of `db.query.text`](#sanitization-of-dbquerytext)
|
||||
- [Generating a summary of the query text](#generating-a-summary-of-the-query-text)
|
||||
- [Generating a summary of the query](#generating-a-summary-of-the-query)
|
||||
- [Semantic conventions for specific database technologies](#semantic-conventions-for-specific-database-technologies)
|
||||
|
||||
<!-- tocstop -->
|
||||
|
|
@ -119,7 +119,7 @@ classify as errors.
|
|||
| [`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. |  |
|
||||
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Conditionally Required` [11] |  |
|
||||
| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [12] | `2`; `3`; `4` | `Recommended` |  |
|
||||
| [`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] |  |
|
||||
| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality summary of a database query. [13] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [14] |  |
|
||||
| [`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] |  |
|
||||
| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` |  |
|
||||
| [`db.stored_procedure.name`](/docs/attributes-registry/db.md) | string | The name of a stored procedure within the database. [17] | `GetCustomer` | `Recommended` [18] |  |
|
||||
|
|
@ -178,10 +178,17 @@ Instrumentations SHOULD document how `error.type` is populated.
|
|||
|
||||
**[12] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
|
||||
|
||||
**[13] `db.query.summary`:** `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-query-text) section.
|
||||
**[13] `db.query.summary`:** The query summary describes a class of database queries and is useful
|
||||
as a grouping key, especially when analyzing telemetry for database
|
||||
calls involving complex queries.
|
||||
|
||||
**[14] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
|
||||
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-query)
|
||||
section.
|
||||
|
||||
**[14] `db.query.summary`:** if available through instrumentation hooks or if the instrumentation supports generating a query summary.
|
||||
|
||||
**[15] `db.query.text`:** 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.
|
||||
|
|
@ -331,10 +338,11 @@ and can help control cardinality for users who choose to (optionally) add `db.qu
|
|||
When performing sanitization, instrumentation MAY truncate the sanitized value
|
||||
for performance considerations (since sanitizing has a performance cost).
|
||||
|
||||
## Generating a summary of the query text
|
||||
## Generating a summary of the query
|
||||
|
||||
The `db.query.summary` attribute captures a shortened representation of a query text
|
||||
which SHOULD have low-cardinality and SHOULD NOT contain any dynamic or sensitive data.
|
||||
The `db.query.summary` attribute can be used to capture a shortened representation
|
||||
of the query. It SHOULD have low-cardinality and SHOULD NOT contain any dynamic
|
||||
or sensitive data.
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
|
|
@ -347,8 +355,18 @@ which SHOULD have low-cardinality and SHOULD NOT contain any dynamic or sensitiv
|
|||
> only contain information that has a significant impact on the query, database,
|
||||
> or application performance.
|
||||
|
||||
Instrumentations that support query parsing SHOULD generate a query summary when
|
||||
one is not readily available from other sources.
|
||||
Instrumentation SHOULD set the query summary if it is readily available through
|
||||
instrumentation hooks or other sources.
|
||||
|
||||
Otherwise:
|
||||
|
||||
- When instrumenting higher-level APIs that build queries internally - for example,
|
||||
those that create a table or execute a stored procedure - instrumentations SHOULD
|
||||
generate a `db.query.summary` from available operation(s) and target(s) using the
|
||||
format described in this section.
|
||||
|
||||
- When instrumenting APIs that operate at the query level, instrumentations that
|
||||
support query parsing SHOULD generate a query summary based on the `db.query.text`.
|
||||
|
||||
The summary SHOULD preserve the following parts of query in the order they were provided:
|
||||
|
||||
|
|
@ -431,6 +449,17 @@ name or target).
|
|||
|
||||
the corresponding `db.query.summary` is `SELECT "song list" 'artists'`.
|
||||
|
||||
- Stored procedure is executed using convenience API such as one available in
|
||||
[Microsoft.Data.SqlClient](https://learn.microsoft.com/dotnet/api/microsoft.data.sqlclient.sqlcommand.commandtype):
|
||||
|
||||
```csharp
|
||||
var command = new SqlCommand();
|
||||
command.CommandType = CommandType.StoredProcedure;
|
||||
command.CommandText = "some_stored_procedure";
|
||||
```
|
||||
|
||||
the corresponding `db.query.summary` is `EXECUTE some_stored_procedure`, `db.query.text` is not populated.
|
||||
|
||||
Semantic conventions for individual database systems or specialized instrumentations
|
||||
MAY specify a different `db.query.summary` format as long as produced summary remains
|
||||
relatively short and its cardinality remains low comparing to the `db.query.text`.
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ Spans representing calls to MariaDB adhere to the general [Semantic Conventions
|
|||
| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [6] | `public.users`; `customers` | `Recommended` [7] |  |
|
||||
| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [8] | `2`; `3`; `4` | `Recommended` |  |
|
||||
| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [9] | `EXECUTE`; `INSERT` | `Recommended` [10] |  |
|
||||
| [`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] |  |
|
||||
| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality summary of a database query. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] |  |
|
||||
| [`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] |  |
|
||||
| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` |  |
|
||||
| [`db.stored_procedure.name`](/docs/attributes-registry/db.md) | string | The name of a stored procedure within the database. [15] | `GetCustomer` | `Recommended` [16] |  |
|
||||
|
|
@ -80,10 +80,17 @@ Instrumentations SHOULD document how `error.type` is populated.
|
|||
|
||||
**[10] `db.operation.name`:** If the operation is executed via a higher-level API that does not support multiple operation names.
|
||||
|
||||
**[11] `db.query.summary`:** `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-query-text) section.
|
||||
**[11] `db.query.summary`:** The query summary describes a class of database queries and is useful
|
||||
as a grouping key, especially when analyzing telemetry for database
|
||||
calls involving complex queries.
|
||||
|
||||
**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
|
||||
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-query)
|
||||
section.
|
||||
|
||||
**[12] `db.query.summary`:** if available through instrumentation hooks or if the instrumentation supports generating a query summary.
|
||||
|
||||
**[13] `db.query.text`:** 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.
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ Spans representing calls to a MySQL Server adhere to the general [Semantic Conve
|
|||
| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [6] | `public.users`; `customers` | `Recommended` [7] |  |
|
||||
| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [8] | `2`; `3`; `4` | `Recommended` |  |
|
||||
| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [9] | `EXECUTE`; `INSERT` | `Recommended` [10] |  |
|
||||
| [`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] |  |
|
||||
| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality summary of a database query. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] |  |
|
||||
| [`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] |  |
|
||||
| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` |  |
|
||||
| [`db.stored_procedure.name`](/docs/attributes-registry/db.md) | string | The name of a stored procedure within the database. [15] | `GetCustomer` | `Recommended` [16] |  |
|
||||
|
|
@ -80,10 +80,17 @@ Instrumentations SHOULD document how `error.type` is populated.
|
|||
|
||||
**[10] `db.operation.name`:** If the operation is executed via a higher-level API that does not support multiple operation names.
|
||||
|
||||
**[11] `db.query.summary`:** `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-query-text) section.
|
||||
**[11] `db.query.summary`:** The query summary describes a class of database queries and is useful
|
||||
as a grouping key, especially when analyzing telemetry for database
|
||||
calls involving complex queries.
|
||||
|
||||
**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
|
||||
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-query)
|
||||
section.
|
||||
|
||||
**[12] `db.query.summary`:** if available through instrumentation hooks or if the instrumentation supports generating a query summary.
|
||||
|
||||
**[13] `db.query.text`:** 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.
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ Spans representing calls to a Oracle SQL Database adhere to the general [Semanti
|
|||
| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [6] | `public.users`; `customers` | `Recommended` [7] |  |
|
||||
| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [8] | `2`; `3`; `4` | `Recommended` |  |
|
||||
| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [9] | `EXECUTE`; `INSERT` | `Recommended` [10] |  |
|
||||
| [`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] |  |
|
||||
| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality summary of a database query. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] |  |
|
||||
| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = :mykey` | `Recommended` [14] |  |
|
||||
| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` |  |
|
||||
| [`db.stored_procedure.name`](/docs/attributes-registry/db.md) | string | The name of a stored procedure within the database. [15] | `GetCustomer` | `Recommended` [16] |  |
|
||||
|
|
@ -77,10 +77,17 @@ Instrumentations SHOULD document how `error.type` is populated.
|
|||
|
||||
**[10] `db.operation.name`:** If the operation is executed via a higher-level API that does not support multiple operation names.
|
||||
|
||||
**[11] `db.query.summary`:** `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-query-text) section.
|
||||
**[11] `db.query.summary`:** The query summary describes a class of database queries and is useful
|
||||
as a grouping key, especially when analyzing telemetry for database
|
||||
calls involving complex queries.
|
||||
|
||||
**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
|
||||
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-query)
|
||||
section.
|
||||
|
||||
**[12] `db.query.summary`:** if available through instrumentation hooks or if the instrumentation supports generating a query summary.
|
||||
|
||||
**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../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.
|
||||
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ Spans representing calls to a PostgreSQL database adhere to the general [Semanti
|
|||
| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [6] | `public.users`; `customers` | `Recommended` [7] |  |
|
||||
| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [8] | `2`; `3`; `4` | `Recommended` |  |
|
||||
| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [9] | `EXECUTE`; `INSERT` | `Recommended` [10] |  |
|
||||
| [`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] |  |
|
||||
| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality summary of a database query. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] |  |
|
||||
| [`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] |  |
|
||||
| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` |  |
|
||||
| [`db.stored_procedure.name`](/docs/attributes-registry/db.md) | string | The name of a stored procedure within the database. [15] | `GetCustomer` | `Recommended` [16] |  |
|
||||
|
|
@ -88,10 +88,17 @@ Instrumentations SHOULD document how `error.type` is populated.
|
|||
|
||||
**[10] `db.operation.name`:** If the operation is executed via a higher-level API that does not support multiple operation names.
|
||||
|
||||
**[11] `db.query.summary`:** `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-query-text) section.
|
||||
**[11] `db.query.summary`:** The query summary describes a class of database queries and is useful
|
||||
as a grouping key, especially when analyzing telemetry for database
|
||||
calls involving complex queries.
|
||||
|
||||
**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
|
||||
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-query)
|
||||
section.
|
||||
|
||||
**[12] `db.query.summary`:** if available through instrumentation hooks or if the instrumentation supports generating a query summary.
|
||||
|
||||
**[13] `db.query.text`:** 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.
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ Spans representing calls to Microsoft SQL Server adhere to the general [Semantic
|
|||
| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [6] | `public.users`; `customers` | `Recommended` [7] |  |
|
||||
| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [8] | `2`; `3`; `4` | `Recommended` |  |
|
||||
| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [9] | `EXECUTE`; `INSERT` | `Recommended` [10] |  |
|
||||
| [`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] |  |
|
||||
| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality summary of a database query. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] |  |
|
||||
| [`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] |  |
|
||||
| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` |  |
|
||||
| [`db.stored_procedure.name`](/docs/attributes-registry/db.md) | string | The name of a stored procedure within the database. [15] | `GetCustomer` | `Recommended` [16] |  |
|
||||
|
|
@ -85,10 +85,17 @@ Instrumentations SHOULD document how `error.type` is populated.
|
|||
|
||||
**[10] `db.operation.name`:** If the operation is executed via a higher-level API that does not support multiple operation names.
|
||||
|
||||
**[11] `db.query.summary`:** `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-query-text) section.
|
||||
**[11] `db.query.summary`:** The query summary describes a class of database queries and is useful
|
||||
as a grouping key, especially when analyzing telemetry for database
|
||||
calls involving complex queries.
|
||||
|
||||
**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
|
||||
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-query)
|
||||
section.
|
||||
|
||||
**[12] `db.query.summary`:** if available through instrumentation hooks or if the instrumentation supports generating a query summary.
|
||||
|
||||
**[13] `db.query.text`:** 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.
|
||||
|
|
|
|||
|
|
@ -58,7 +58,7 @@ Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic co
|
|||
| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [6] | `public.users`; `customers` | `Recommended` [7] |  |
|
||||
| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [8] | `2`; `3`; `4` | `Recommended` |  |
|
||||
| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [9] | `EXECUTE`; `INSERT` | `Recommended` [10] |  |
|
||||
| [`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] |  |
|
||||
| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality summary of a database query. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] |  |
|
||||
| [`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] |  |
|
||||
| [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` |  |
|
||||
| [`db.stored_procedure.name`](/docs/attributes-registry/db.md) | string | The name of a stored procedure within the database. [15] | `GetCustomer` | `Recommended` [16] |  |
|
||||
|
|
@ -137,10 +137,17 @@ Instrumentations SHOULD document how `error.type` is populated.
|
|||
|
||||
**[10] `db.operation.name`:** If the operation is executed via a higher-level API that does not support multiple operation names.
|
||||
|
||||
**[11] `db.query.summary`:** `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-query-text) section.
|
||||
**[11] `db.query.summary`:** The query summary describes a class of database queries and is useful
|
||||
as a grouping key, especially when analyzing telemetry for database
|
||||
calls involving complex queries.
|
||||
|
||||
**[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization.
|
||||
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-query)
|
||||
section.
|
||||
|
||||
**[12] `db.query.summary`:** if available through instrumentation hooks or if the instrumentation supports generating a query summary.
|
||||
|
||||
**[13] `db.query.text`:** 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.
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@ groups:
|
|||
- ref: db.query.text
|
||||
- ref: db.query.summary
|
||||
requirement_level:
|
||||
recommended: if readily available or if instrumentation supports query summarization.
|
||||
recommended: if available through instrumentation hooks or if the instrumentation supports generating a query summary.
|
||||
|
||||
- id: attributes.db.client.with_query_and_collection
|
||||
extends: attributes.db.client.with_query
|
||||
|
|
|
|||
|
|
@ -106,16 +106,16 @@ groups:
|
|||
type: string
|
||||
stability: release_candidate
|
||||
brief: >
|
||||
Low cardinality representation of a database query text.
|
||||
note: >
|
||||
`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.
|
||||
Low cardinality summary of a database query.
|
||||
note: |
|
||||
The query summary 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-query-text)
|
||||
[Generating query summary](/docs/database/database-spans.md#generating-a-summary-of-the-query)
|
||||
section.
|
||||
examples:
|
||||
[
|
||||
|
|
|
|||
|
|
@ -749,7 +749,7 @@ groups:
|
|||
type: span
|
||||
stability: development
|
||||
span_kind: client
|
||||
extends: trace.db.common.query_and_collection
|
||||
extends: trace.db.common.minimal
|
||||
brief: >
|
||||
Cosmos DB instrumentations include call-level spans that represent logical database
|
||||
calls and adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md).
|
||||
|
|
@ -786,6 +786,7 @@ groups:
|
|||
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
|
||||
sampling_relevant: true
|
||||
- ref: azure.cosmosdb.request.body.size
|
||||
- ref: db.response.status_code
|
||||
brief: >
|
||||
|
|
@ -956,6 +957,9 @@ groups:
|
|||
- ref: azure.cosmosdb.operation.contacted_regions
|
||||
requirement_level:
|
||||
conditionally_required: If available.
|
||||
- ref: db.query.text # TODO: this might not be the right attribute to use here - https://github.com/open-telemetry/semantic-conventions/issues/2213
|
||||
- ref: db.query.parameter
|
||||
requirement_level: opt_in
|
||||
- id: span.db.oracledb.client
|
||||
type: span
|
||||
stability: development
|
||||
|
|
|
|||
Loading…
Reference in New Issue