diff --git a/CHANGELOG.md b/CHANGELOG.md index 71e447352f2..81aaba4eadc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,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 diff --git a/schemas/1.8.0 b/schemas/1.8.0 new file mode 100644 index 00000000000..722cf79f045 --- /dev/null +++ b/schemas/1.8.0 @@ -0,0 +1,14 @@ +file_format: 1.0.0 +schema_url: https://opentelemetry.io/schemas/1.8.0 +versions: + 1.8.0: + spans: + changes: + - rename_attributes: + attribute_map: + db.cassandra.keyspace: db.name + db.hbase.namespace: db.name + 1.7.0: + 1.6.1: + 1.5.0: + 1.4.0: diff --git a/semantic_conventions/trace/database.yaml b/semantic_conventions/trace/database.yaml index b05d50b47b2..95bb38c3265 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 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 @@ -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..7fc98350336 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. @@ -170,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 @@ -177,10 +179,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 +195,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 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 |