Skip to content

Commit d963d60

Browse files
lmolkovatrask
lmolkova
and
trask
authored
Clarify notes on system-specific databases for operation and collection names (#1863)
Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>
1 parent c863656 commit d963d60

14 files changed

+133
-126
lines changed

‎.chloggen/1863.yaml

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
change_type: enhancement
2+
component: db
3+
note: Add database-specific notes on db.operation.name and db.collection.name for
4+
Cassandra, Cosmos DB, HBase, MongoDB, and Redis, covering their batch/bulk
5+
terms and lack of cross-table queries.
6+
issues: [1863, 1573]

‎docs/attributes-registry/db.md

+6-5
Original file line numberDiff line numberDiff line change
@@ -26,13 +26,14 @@ This group defines the attributes used to describe telemetry in the context of d
2626
| <a id="db-response-status-code" href="#db-response-status-code">`db.response.status_code`</a> | string | Database response status code. [8] | `102`; `ORA-17002`; `08P01`; `404` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
2727
| <a id="db-system-name" href="#db-system-name">`db.system.name`</a> | string | The database management system (DBMS) product as identified by the client instrumentation. [9] | `other_sql`; `softwareag.adabas`; `actian.ingres` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
2828

29-
**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
29+
**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application
30+
without attempting to do any case normalization.
3031

3132
The collection name SHOULD NOT be extracted from `db.query.text`,
32-
unless the query format is known to only ever have a single collection name present.
33+
when the database system supports cross-table queries in non-batch operations.
3334

34-
For batch operations, if the individual operations are known to have the same collection name
35-
then that collection name SHOULD be used.
35+
For batch operations, if the individual operations are known to have the same
36+
collection name then that collection name SHOULD be used.
3637

3738
**[2] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
3839
Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system.
@@ -44,7 +45,7 @@ It is RECOMMENDED to capture the value as provided by the application without at
4445
without attempting to do any case normalization.
4546

4647
The operation name SHOULD NOT be extracted from `db.query.text`,
47-
unless the query format is known to only ever have a single operation name present.
48+
when the database system supports cross-table queries in non-batch operations.
4849

4950
For batch operations, if the individual operations are known to have the same operation name
5051
then that operation name SHOULD be used prepended by `BATCH `,

‎docs/database/cassandra.md

+5-7
Original file line numberDiff line numberDiff line change
@@ -53,15 +53,13 @@ The following table outlines the span attributes applicable to Cassandra.
5353
| [`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) |
5454
| [`db.operation.parameter.<key>`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `<key>` being the parameter name, and the attribute value being a string representation of the parameter value. [18] | `someval`; `55` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
5555

56-
**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
57-
58-
The collection name SHOULD NOT be extracted from `db.query.text`,
59-
unless the query format is known to only ever have a single collection name present.
56+
**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application
57+
without attempting to do any case normalization.
6058

6159
For batch operations, if the individual operations are known to have the same collection name
6260
then that collection name SHOULD be used.
6361

64-
**[2] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query.
62+
**[2] `db.collection.name`:** If readily available and if a database call is performed on a single collection.
6563

6664
**[3] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
6765
Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system.
@@ -71,14 +69,14 @@ It is RECOMMENDED to capture the value as provided by the application without at
7169
without attempting to do any case normalization.
7270

7371
The operation name SHOULD NOT be extracted from `db.query.text`,
74-
unless the query format is known to only ever have a single operation name present.
72+
when the database system supports cross-table queries in non-batch operations.
7573

7674
For batch operations, if the individual operations are known to have the same operation name
7775
then that operation name SHOULD be used prepended by `BATCH `,
7876
otherwise `db.operation.name` SHOULD be `BATCH` or some other database
7977
system specific term if more applicable.
8078

81-
**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
79+
**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call.
8280

8381
**[6] `db.response.status_code`:** All Cassandra protocol error codes SHOULD be considered errors.
8482

‎docs/database/cosmosdb.md

+15-23
Original file line numberDiff line numberDiff line change
@@ -193,7 +193,7 @@ If none of them applies, it's RECOMMENDED to use language-agnostic representatio
193193
client method name in snake_case. Instrumentations SHOULD document
194194
additional values when introducing new operations.
195195

196-
**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
196+
**[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call.
197197

198198
**[6] `db.response.status_code`:** Response codes in the 4xx and 5xx range SHOULD be considered errors.
199199

@@ -345,50 +345,42 @@ Explaining bucket configuration:
345345
| [`azure.cosmosdb.response.sub_status_code`](/docs/attributes-registry/azure.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` when response was received and contained sub-code. | ![Development](https://img.shields.io/badge/-development-blue) |
346346
| [`db.collection.name`](/docs/attributes-registry/db.md) | string | Cosmos DB container name. [1] | `public.users`; `customers` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
347347
| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
348-
| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [2] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
349-
| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [4] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [5] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
350-
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [6] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
351-
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Conditionally Required` [8] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
352-
| [`azure.cosmosdb.operation.contacted_regions`](/docs/attributes-registry/azure.md) | string[] | List of regions contacted during operation in the order that they were contacted. If there is more than one region listed, it indicates that the operation was performed on multiple regions i.e. cross-regional call. [9] | `["North Central US", "Australia East", "Australia Southeast"]` | `Recommended` If available | ![Development](https://img.shields.io/badge/-development-blue) |
353-
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
348+
| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [2] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` If readily available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
349+
| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [3] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [4] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
350+
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [5] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
351+
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Conditionally Required` [7] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
352+
| [`azure.cosmosdb.operation.contacted_regions`](/docs/attributes-registry/azure.md) | string[] | List of regions contacted during operation in the order that they were contacted. If there is more than one region listed, it indicates that the operation was performed on multiple regions i.e. cross-regional call. [8] | `["North Central US", "Australia East", "Australia Southeast"]` | `Recommended` If available | ![Development](https://img.shields.io/badge/-development-blue) |
353+
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
354354

355355
**[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
356356

357-
The collection name SHOULD NOT be extracted from `db.query.text`,
358-
unless the query format is known to only ever have a single collection name present.
359-
360-
For batch operations, if the individual operations are known to have the same collection name
361-
then that collection name SHOULD be used.
362-
363357
**[2] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application
364358
without attempting to do any case normalization.
365359

366360
The operation name SHOULD NOT be extracted from `db.query.text`,
367-
unless the query format is known to only ever have a single operation name present.
361+
when the database system supports cross-table queries in non-batch operations.
368362

369363
For batch operations, if the individual operations are known to have the same operation name
370364
then that operation name SHOULD be used prepended by `BATCH `,
371365
otherwise `db.operation.name` SHOULD be `BATCH` or some other database
372366
system specific term if more applicable.
373367

374-
**[3] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
375-
376-
**[4] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
368+
**[3] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
377369
Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
378370

379-
**[5] `db.response.status_code`:** If the operation failed and status code is available.
371+
**[4] `db.response.status_code`:** If the operation failed and status code is available.
380372

381-
**[6] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
373+
**[5] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
382374
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
383375
Instrumentations SHOULD document how `error.type` is populated.
384376

385-
**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
377+
**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
386378

387-
**[8] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
379+
**[7] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
388380

389-
**[9] `azure.cosmosdb.operation.contacted_regions`:** Region name matches the format of `displayName` in [Azure Location API](https://learn.microsoft.com/rest/api/subscription/subscriptions/list-locations?view=rest-subscription-2021-10-01&tabs=HTTP#location)
381+
**[8] `azure.cosmosdb.operation.contacted_regions`:** Region name matches the format of `displayName` in [Azure Location API](https://learn.microsoft.com/rest/api/subscription/subscriptions/list-locations?view=rest-subscription-2021-10-01&tabs=HTTP#location)
390382

391-
**[10] `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.
383+
**[9] `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.
392384

393385
---
394386

0 commit comments

Comments
 (0)