From 94eec2c49d4450527be02674a05218793bb2f2e8 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 27 Sep 2021 13:44:10 -0700 Subject: [PATCH 01/10] Use db.name more consistently across database types --- CHANGELOG.md | 2 + semantic_conventions/trace/database.yaml | 38 ++++--------------- .../trace/semantic_conventions/database.md | 22 +++++------ 3 files changed, 19 insertions(+), 43 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1b93e83d2bc..b9fa2857fd3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -52,6 +52,8 @@ release. ([#1890](https://github.com/open-telemetry/opentelemetry-specification/pull/1890)) - Add HTTP request and response headers semantic conventions. ([#1898](https://github.com/open-telemetry/opentelemetry-specification/pull/1898)) +- BREAKING: Remove db.cassandra.keyspace and db.hbase.namespace, and clarify db.name + ([# ](https://github.com/open-telemetry/opentelemetry-specification/pull/ )) ### Compatibility diff --git a/semantic_conventions/trace/database.yaml b/semantic_conventions/trace/database.yaml index b05d50b47b2..af60fce03a3 100644 --- a/semantic_conventions/trace/database.yaml +++ b/semantic_conventions/trace/database.yaml @@ -176,15 +176,16 @@ groups: tag: call-level type: string required: - conditional: > - Required, if applicable and no more-specific attribute is defined. + conditional: Required, if applicable. brief: > - If no [tech-specific attribute](#call-level-attributes-for-specific-technologies) - is defined, this attribute is used to report the name of the database being accessed. + This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). note: > In some SQL databases, the database name to be used is called "schema name". + In case there are multiple layers that could be considered for database name + (e.g. Oracle instance name and schema name), + the database name to be used is the more specific layer (e.g. Oracle schema name). examples: [ 'customers', 'main' ] - id: statement tag: call-level @@ -256,13 +257,6 @@ groups: brief: > Call-level attributes for Cassandra attributes: - - id: keyspace - type: string - required: always - tag: call-level-tech-specific-cassandra - brief: > - The name of the keyspace being accessed. To be used instead of the generic `db.name` attribute. - examples: 'mykeyspace' - id: page_size type: int tag: call-level-tech-specific-cassandra @@ -302,7 +296,7 @@ groups: tag: call-level-tech-specific-cassandra required: conditional: Recommended if available. - brief: The name of the primary table that the operation is acting upon, including the schema name (if applicable). + brief: The name of the primary table that the operation is acting upon, including the database name (if applicable). note: > This mirrors the db.sql.table attribute but references cassandra rather than sql. It is not recommended to attempt any client-side parsing of @@ -335,21 +329,6 @@ groups: The data center of the coordinating node for a query. examples: 'us-west-2' - - id: db.hbase - prefix: db.hbase - extends: db - brief: > - Call-level attributes for Apache HBase - attributes: - - id: namespace - type: string - required: always - tag: call-level-tech-specific - brief: > - The [HBase namespace](https://hbase.apache.org/book.html#_namespace) being accessed. - To be used instead of the generic `db.name` attribute. - examples: 'default' - - id: db.redis prefix: db.redis extends: db @@ -384,14 +363,14 @@ groups: prefix: 'db.sql' extends: 'db' brief: > - Call-level attrbiutes for SQL databases + Call-level attributes for SQL databases attributes: - id: table tag: call-level-tech-specific type: string required: conditional: Recommended if available. - brief: The name of the primary table that the operation is acting upon, including the schema name (if applicable). + brief: The name of the primary table that the operation is acting upon, including the database name (if applicable). note: > It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if @@ -404,7 +383,6 @@ groups: brief: "Semantic convention group for specific technologies" constraints: - include: 'db.cassandra' - - include: 'db.hbase' - include: 'db.redis' - include: 'db.mongodb' - include: 'db.sql' diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md index 5e32da167a7..87a446bf1c5 100644 --- a/specification/trace/semantic_conventions/database.md +++ b/specification/trace/semantic_conventions/database.md @@ -147,19 +147,17 @@ Usually only one `db.name` will be used per connection though. | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| -| `db.name` | string | If no [tech-specific attribute](#call-level-attributes-for-specific-technologies) is defined, this attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | Conditional [2] | -| `db.statement` | string | The database statement being executed. [3] | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | Conditional [4] | -| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. [5] | `findAndModify`; `HMSET`; `SELECT` | Required, if `db.statement` is not applicable. | +| `db.name` | string | This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | Required, if applicable. | +| `db.statement` | string | The database statement being executed. [2] | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | Conditional [3] | +| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. [4] | `findAndModify`; `HMSET`; `SELECT` | Required, if `db.statement` is not applicable. | -**[1]:** In some SQL databases, the database name to be used is called "schema name". +**[1]:** In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name). -**[2]:** Required, if applicable and no more-specific attribute is defined. +**[2]:** The value may be sanitized to exclude sensitive information. -**[3]:** The value may be sanitized to exclude sensitive information. +**[3]:** Required if applicable and not explicitly disabled via instrumentation configuration. -**[4]:** Required if applicable and not explicitly disabled via instrumentation configuration. - -**[5]:** When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. +**[4]:** When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. For **Redis**, the value provided for `db.statement` SHOULD correspond to the syntax of the Redis CLI. @@ -177,10 +175,9 @@ For example, when retrieving a document, `db.operation` would be set to (literal | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| -| `db.hbase.namespace` | string | The [HBase namespace](https://hbase.apache.org/book.html#_namespace) being accessed. To be used instead of the generic `db.name` attribute. | `default` | Yes | | `db.redis.database_index` | int | The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. | `0`; `1`; `15` | Conditional [1] | | `db.mongodb.collection` | string | The collection being accessed within the database stated in `db.name`. | `customers`; `products` | Yes | -| `db.sql.table` | string | The name of the primary table that the operation is acting upon, including the schema name (if applicable). [2] | `public.users`; `customers` | Recommended if available. | +| `db.sql.table` | string | The name of the primary table that the operation is acting upon, including the database name (if applicable). [2] | `public.users`; `customers` | Recommended if available. | **[1]:** Required, if other than the default database (`0`). @@ -194,10 +191,9 @@ Separated for clarity. | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| -| `db.cassandra.keyspace` | string | The name of the keyspace being accessed. To be used instead of the generic `db.name` attribute. | `mykeyspace` | Yes | | `db.cassandra.page_size` | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` | No | | `db.cassandra.consistency_level` | string | The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). | `all` | No | -| `db.cassandra.table` | string | The name of the primary table that the operation is acting upon, including the schema name (if applicable). [1] | `mytable` | Recommended if available. | +| `db.cassandra.table` | string | The name of the primary table that the operation is acting upon, including the database name (if applicable). [1] | `mytable` | Recommended if available. | | `db.cassandra.idempotence` | boolean | Whether or not the query is idempotent. | | No | | `db.cassandra.speculative_execution_count` | int | The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. | `0`; `2` | No | | `db.cassandra.coordinator.id` | string | The ID of the coordinating node for a query. | `be13faa2-8574-4d71-926d-27f16cf8a7af` | No | From 58dacf250c52eb1264e8d8b10e5d71188d4ed9d1 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 27 Sep 2021 15:54:07 -0700 Subject: [PATCH 02/10] Update change log with PR # --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b9fa2857fd3..b390b231e92 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -53,7 +53,7 @@ release. - Add HTTP request and response headers semantic conventions. ([#1898](https://github.com/open-telemetry/opentelemetry-specification/pull/1898)) - BREAKING: Remove db.cassandra.keyspace and db.hbase.namespace, and clarify db.name - ([# ](https://github.com/open-telemetry/opentelemetry-specification/pull/ )) + ([#1973](https://github.com/open-telemetry/opentelemetry-specification/pull/1973)) ### Compatibility From 6bb942e3f9cd015d49e58adeea2d2143fb9da6dc Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 28 Sep 2021 20:36:57 -0700 Subject: [PATCH 03/10] Add schema translation --- schemas/1.7.0 | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 schemas/1.7.0 diff --git a/schemas/1.7.0 b/schemas/1.7.0 new file mode 100644 index 00000000000..4d478626f09 --- /dev/null +++ b/schemas/1.7.0 @@ -0,0 +1,12 @@ +file_format: 1.0.0 +schema_url: https://opentelemetry.io/schemas/1.7.0 +versions: + 1.7.0: + spans: + changes: + - rename_attributes: + attribute_map: + db.cassandra.keyspace: db.name + db.hbase.namespace: db.name + 1.5.0: + 1.4.0: From 5e7076e334f570fcaa86e5e67aba1531535fe5cc Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 29 Sep 2021 14:15:23 -0700 Subject: [PATCH 04/10] Add missing 1.6.1 --- schemas/1.7.0 | 1 + 1 file changed, 1 insertion(+) diff --git a/schemas/1.7.0 b/schemas/1.7.0 index 4d478626f09..18e52f00c9f 100644 --- a/schemas/1.7.0 +++ b/schemas/1.7.0 @@ -8,5 +8,6 @@ versions: attribute_map: db.cassandra.keyspace: db.name db.hbase.namespace: db.name + 1.6.1: 1.5.0: 1.4.0: From 424b7fe2551e229490dbd177504014a21256d581 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 29 Sep 2021 14:42:35 -0700 Subject: [PATCH 05/10] Provide db.name guidance for Cassandra and HBase --- specification/trace/semantic_conventions/database.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md index 87a446bf1c5..fff079abf7a 100644 --- a/specification/trace/semantic_conventions/database.md +++ b/specification/trace/semantic_conventions/database.md @@ -168,6 +168,10 @@ If, for example, the [`HMSET` command][] is invoked, `"HMSET myhash field1 'Hell In **CouchDB**, `db.operation` should be set to the HTTP method + the target REST route according to the API reference documentation. For example, when retrieving a document, `db.operation` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`][CouchDB get doc]. +In **Cassandra**, `db.name` should be set to the keyspace name. + +In **HBase**, `db.name` should be set to the HBase namespace. + [CouchDB get doc]: http://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid ### Call-level attributes for specific technologies From a924c5c326fbf16c8607f2e2eda75b0483fff573 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 30 Sep 2021 10:40:47 -0700 Subject: [PATCH 06/10] Use "keyspace" in cassandra doc --- semantic_conventions/trace/database.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic_conventions/trace/database.yaml b/semantic_conventions/trace/database.yaml index af60fce03a3..95bb38c3265 100644 --- a/semantic_conventions/trace/database.yaml +++ b/semantic_conventions/trace/database.yaml @@ -296,7 +296,7 @@ groups: tag: call-level-tech-specific-cassandra required: conditional: Recommended if available. - brief: The name of the primary table that the operation is acting upon, including the database name (if applicable). + brief: The name of the primary table that the operation is acting upon, including the keyspace name (if applicable). note: > This mirrors the db.sql.table attribute but references cassandra rather than sql. It is not recommended to attempt any client-side parsing of From f3c4483c79e455e746e4780b3e7d5f8387497749 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 30 Sep 2021 10:43:13 -0700 Subject: [PATCH 07/10] Update specification/trace/semantic_conventions/database.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christian Neumüller --- specification/trace/semantic_conventions/database.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md index fff079abf7a..dd2102949e8 100644 --- a/specification/trace/semantic_conventions/database.md +++ b/specification/trace/semantic_conventions/database.md @@ -168,9 +168,9 @@ If, for example, the [`HMSET` command][] is invoked, `"HMSET myhash field1 'Hell In **CouchDB**, `db.operation` should be set to the HTTP method + the target REST route according to the API reference documentation. For example, when retrieving a document, `db.operation` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`][CouchDB get doc]. -In **Cassandra**, `db.name` should be set to the keyspace name. +In **Cassandra**, `db.name` SHOULD be set to the keyspace name. -In **HBase**, `db.name` should be set to the HBase namespace. +In **HBase**, `db.name` SHOULD be set to the HBase namespace. [CouchDB get doc]: http://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid From e2fa7b54f0b028f4db45edbbbecb2c64c3e9ee81 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 30 Sep 2021 10:49:59 -0700 Subject: [PATCH 08/10] Move change log entry now that 1.7.0 is released --- CHANGELOG.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bda45ff336c..c6b3479f25e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,9 @@ release. ### Semantic Conventions +- BREAKING: Remove db.cassandra.keyspace and db.hbase.namespace, and clarify db.name + ([#1973](https://github.com/open-telemetry/opentelemetry-specification/pull/1973)) + ### Compatibility ### OpenTelemetry Protocol @@ -82,8 +85,6 @@ release. ([#1890](https://github.com/open-telemetry/opentelemetry-specification/pull/1890)) - Add HTTP request and response headers semantic conventions. ([#1898](https://github.com/open-telemetry/opentelemetry-specification/pull/1898)) -- BREAKING: Remove db.cassandra.keyspace and db.hbase.namespace, and clarify db.name - ([#1973](https://github.com/open-telemetry/opentelemetry-specification/pull/1973)) ### Compatibility From 3e60074f3e18cff4197cbf2f2a0c164c1e486273 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 30 Sep 2021 10:50:40 -0700 Subject: [PATCH 09/10] Fix merge conflict --- schemas/1.8.0 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schemas/1.8.0 b/schemas/1.8.0 index 4c1bf0bc9ac..722cf79f045 100644 --- a/schemas/1.8.0 +++ b/schemas/1.8.0 @@ -1,5 +1,5 @@ file_format: 1.0.0 -schema_url: https://opentelemetry.io/schemas/1.7.0 +schema_url: https://opentelemetry.io/schemas/1.8.0 versions: 1.8.0: spans: From 24a829dd8fbf939cee039adf0b21ce643bfd220b Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 30 Sep 2021 10:53:50 -0700 Subject: [PATCH 10/10] Regenerate markdown --- specification/trace/semantic_conventions/database.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md index dd2102949e8..7fc98350336 100644 --- a/specification/trace/semantic_conventions/database.md +++ b/specification/trace/semantic_conventions/database.md @@ -197,7 +197,7 @@ Separated for clarity. |---|---|---|---|---| | `db.cassandra.page_size` | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` | No | | `db.cassandra.consistency_level` | string | The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). | `all` | No | -| `db.cassandra.table` | string | The name of the primary table that the operation is acting upon, including the database name (if applicable). [1] | `mytable` | Recommended if available. | +| `db.cassandra.table` | string | The name of the primary table that the operation is acting upon, including the keyspace name (if applicable). [1] | `mytable` | Recommended if available. | | `db.cassandra.idempotence` | boolean | Whether or not the query is idempotent. | | No | | `db.cassandra.speculative_execution_count` | int | The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. | `0`; `2` | No | | `db.cassandra.coordinator.id` | string | The ID of the coordinating node for a query. | `be13faa2-8574-4d71-926d-27f16cf8a7af` | No |