Database span name clarification and improvements

docs/attributes-registry/db.md

@@ -105,7 +105,7 @@
 | `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` |
 | `db.cassandra.table` | string | The name of the primary Cassandra table that the operation is acting upon, including the keyspace name (if applicable). [1] | `mytable` |
 
-**[1]:** This mirrors the db.sql.table attribute but references cassandra rather than sql. It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set.
+**[1]:** This mirrors the `db.sql.table` attribute but references `cassandra` rather than `sql`. It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set.
 
 `db.cassandra.consistency_level` MUST be one of the following:
 

docs/database/cassandra.md

@@ -12,6 +12,10 @@ described on this page.
 
 `db.system` MUST be set to `"cassandra"`.
 
+## Span name
+
+Cassandra spans SHOULD be named according to the following pattern: `{db.name}.{db.cassandra.table} {db.operation}`
+
 ## Call-level attributes
 
 <!-- semconv db.cassandra(full,tag=call-level-tech-specific-cassandra) -->
@@ -26,7 +30,7 @@ described on this page.
 | [`db.cassandra.table`](../attributes-registry/db.md) | string | The name of the primary Cassandra table that the operation is acting upon, including the keyspace name (if applicable). [1] | `mytable` | Recommended |
 | [`db.name`](../attributes-registry/db.md) | string | The keyspace name in Cassandra. [2] | `mykeyspace` | Conditionally Required: If applicable. |
 
-**[1]:** This mirrors the db.sql.table attribute but references cassandra rather than sql. It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set.
+**[1]:** This mirrors the `db.sql.table` attribute but references `cassandra` rather than `sql`. It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set.
 
 **[2]:** For Cassandra the `db.name` should be set to the Cassandra keyspace name.
 

docs/database/cosmosdb.md

@@ -11,6 +11,10 @@ extend and override the [Database Semantic Conventions](database-spans.md)
 that describe common database operations attributes in addition to the Semantic Conventions
 described on this page.
 
+## Span name
+
+CosmosDB spans SHOULD be named according to the following pattern: `{db.name}.{db.cosmosdb.container} {db.operation}`
+
 ## Call-level attributes
 
 `db.system` MUST be set to `"cosmosdb"`.
@@ -73,18 +77,18 @@ In addition to Cosmos DB attributes, all spans include
 
 | Key                                  | Value |
 |:-------------------------------------| :------------------- |
-| Span name                            | `"ReadItemsAsync"` |
+| Span name                            | `"shopDb.products ReadItemsAsync"` |
 | `kind`                               | `"internal"` |
 | `az.namespace`                       | `"Microsoft.DocumentDB"` |
 | `db.system`                          | `"cosmosdb"` |
-| `db.name`                            | `"database name"` |
+| `db.name`                            | `"shopDb"` |
 | `db.operation`                       | `"ReadItemsAsync"` |
-| `server.address`                     |  `"account.documents.azure.com"`  |
+| `server.address`                     | `"account.documents.azure.com"` |
 | `db.cosmosdb.client_id`              | `3ba4827d-4422-483f-b59f-85b74211c11d` |
 | `db.cosmosdb.operation_type`         | `Read` |
 | `user_agent.original`                | `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\|` |
 | `db.cosmosdb.connection_mode`        | `"Direct"` |
-| `db.cosmosdb.container`              | `"container name"` |
+| `db.cosmosdb.container`              | `"products"` |
 | `db.cosmosdb.request_content_length` | `20` |
 | `db.cosmosdb.status_code`            | `201` |
 | `db.cosmosdb.sub_status_code`        | `0` |

docs/database/couchdb.md

@@ -12,6 +12,10 @@ described on this page.
 
 `db.system` MUST be set to `"couchdb"`.
 
+## Span name
+
+CouchDB spans SHOULD be named according to the following pattern: `{db.operation}`
+
 ## Call-level attributes
 
 <!-- semconv db.couchdb(full,tag=call-level-tech-specific) -->

docs/database/database-spans.md

@@ -52,15 +52,23 @@ linkTitle: Client Calls
 
 **Span kind:** MUST always be `CLIENT`.
 
-The **span name** SHOULD be set to a low cardinality value representing the statement executed on the database.
+## Span name
+
+Database spans MUST follow the overall guidelines for [span names](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.26.0/specification/trace/api.md#span).
+
+The span name SHOULD include database name, table or container name and the operation being performed in the following format:
+`{db.name}.{table name} {operation}`
+
+The `{table name}` is not applicable to some databases and SHOULD be specified in tech-specific database conventions. For example, it matches `db.sql.table` for SQL database, `db.cassandra.table` for Cassandra and `db.mongodb.collection` for MongoDB.
+
+The `{operation}` SHOULD be set to a low cardinality value representing the operation executed on the database.
 It MAY be a stored procedure name (without arguments), DB statement without variable arguments, operation name, etc.
-Since SQL statements may have very high cardinality even without arguments, SQL spans SHOULD be named the
-following way, unless the statement is known to be of low cardinality:
-`<db.operation> <db.name>.<db.sql.table>`, provided that `db.operation` and `db.sql.table` are available.
-If `db.sql.table` is not available due to its semantics, the span SHOULD be named `<db.operation> <db.name>`.
-It is not recommended to attempt any client-side parsing of `db.statement` just to get these properties,
+
+It is NOT RECOMMENDED to attempt any client-side parsing of `db.statement` to get span name components,
 they should only be used if the library being instrumented already provides them.
-When it's otherwise impossible to get any meaningful span name, `db.name` or the tech-specific database name MAY be used.
+
+When it's otherwise impossible to get any meaningful span name, `db.name`, or the tech-specific database name SHOULD be used.
+If no low-cardinality information is available, `db.system` SHOULD be used as a fallback.
 
 ## Connection-level attributes
 

docs/database/hbase.md

@@ -12,6 +12,10 @@ described on this page.
 
 `db.system` MUST be set to `"hbase"`.
 
+## Span name
+
+HBase spans SHOULD be named according to the following pattern: `{db.name}`
+
 ## Call-level attributes
 
 <!-- semconv db.hbase(full,tag=call-level-tech-specific) -->

docs/database/mongodb.md

@@ -12,6 +12,10 @@ described on this page.
 
 `db.system` MUST be set to `"mongodb"`.
 
+## Span name
+
+MongoDB spans SHOULD be named according to the following pattern: `{db.name}.{db.mongodb.collection} {db.operation}`
+
 ## Call-level attributes
 
 <!-- semconv db.mongodb(full,tag=call-level-tech-specific) -->
@@ -24,7 +28,7 @@ described on this page.
 
 | Key | Value |
 | :---------------------- | :----------------------------------------------------------- |
-| Span name               | `"products.findAndModify"` |
+| Span name               | `"shopDb.products findAndModify"` |
 | `db.system`             | `"mongodb"` |
 | `db.connection_string`  | not set |
 | `db.user`               | `"the_user"` |

docs/database/mssql.md

@@ -12,15 +12,22 @@ described on this page.
 
 `db.system` MUST be set to `"mssql"`.
 
+## Span name
+
+MSSQL span name SHOULD match [SQL span names](./sql.md#span-name)
+
 ## Connection-level attributes
 
 <!-- semconv db.mssql(full,tag=connection-level-tech-specific) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | [`db.jdbc.driver_classname`](../attributes-registry/db.md) | string | The fully-qualified class name of the [Java Database Connectivity (JDBC)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) driver used to connect. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | Recommended |
 | [`db.mssql.instance_name`](../attributes-registry/db.md) | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [1] | `MSSQLSERVER` | Recommended |
+| [`db.sql.table`](../attributes-registry/db.md) | string | The name of the primary table that the operation is acting upon, including the database name (if applicable). [2] | `public.users`; `customers` | Recommended |
 
 **[1]:** If setting a `db.mssql.instance_name`, `server.port` is no longer required (but still recommended if non-standard).
+
+**[2]:** It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set.
 <!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md

docs/database/redis.md

@@ -12,6 +12,12 @@ described on this page.
 
 `db.system` MUST be set to `"redis"`.
 
+## Span name
+
+Redis spans SHOULD be named the following way:
+- `{db.redis.database_index} {db.statement}` if `db.statement` without variable arguments is available and know to be of a low cardinality.
+- `{db.redis.database_index}` otherwise.
+
 ## Call-level attributes
 
 <!-- semconv db.redis(full,tag=call-level-tech-specific) -->
@@ -32,7 +38,7 @@ Furthermore, `db.name` is not specified as there is no database name in Redis an
 
 | Key                       | Value |
 |:--------------------------| :-------------------------------------------- |
-| Span name                 | `"HMSET myhash"` |
+| Span name                 | `"15 HMSET myhash"` |
 | `db.system`               | `"redis"` |
 | `db.connection_string`    | not set |
 | `db.user`                 | not set |

docs/database/sql.md

@@ -10,6 +10,15 @@ The SQL databases Semantic Conventions extend and override the [Database Semanti
 that describe common database operations attributes in addition to the Semantic Conventions
 described on this page.
 
+## Span name
+
+SQL spans SHOULD be named the following way:
+- `{db.name} {db.statement}` if `db.statement` without variable arguments is available and know to be of a low cardinality.
+- `{db.name}.{db.sql.table} {db.operation}`, provided that `db.operation` and `db.sql.table` are available.
+  - If `db.sql.table` is not available due to its semantics, the span SHOULD be named `{db.name} {db.operation}`
+  - If `db.operation` is not available, the span SHOULD be named `{db.name}`
+  - If no information is available, the span SHOULD be named `{db.system}`
+
 ## Call-level attributes
 
 <!-- semconv db.sql(full,tag=call-level-tech-specific) -->
@@ -22,11 +31,11 @@ described on this page.
 
 ## Example
 
-This is an example of attributes for a MySQL database span:
+This is an example of attributes for a MySQL database span when `db.statement` contains variable arguments:
 
 | Key                     | Value |
 |:------------------------| :----------------------------------------------------------- |
-| Span name               | `"SELECT ShopDb.orders"` |
+| Span name               | `"ShopDb.orders SELECT"` |
 | `db.system`             | `"mysql"` |
 | `db.connection_string`  | `"Server=shopdb.example.com;Database=ShopDb;Uid=billing_user;TableCache=true;UseCompression=True;MinimumPoolSize=10;MaximumPoolSize=50;"` |
 | `db.user`               | `"billing_user"` |
@@ -40,4 +49,22 @@ This is an example of attributes for a MySQL database span:
 | `db.operation`          | `"SELECT"` |
 | `db.sql.table`          | `"orders"` |
 
+This is an example of attributes for a MySQL database span when `db.statement` is available without variable arguments:
+
+| Key                     | Value |
+|:------------------------| :----------------------------------------------------------- |
+| Span name               | `"ShopDb SELECT * FROM orders WHERE order_id = ?"` |
+| `db.system`             | `"mysql"` |
+| `db.connection_string`  | `"Server=shopdb.example.com;Database=ShopDb;Uid=billing_user;TableCache=true;UseCompression=True;MinimumPoolSize=10;MaximumPoolSize=50;"` |
+| `db.user`               | `"billing_user"` |
+| `server.address`        | `"shopdb.example.com"` |
+| `server.port`           | `3306` |
+| `network.peer.address`  | `"192.0.2.12"` |
+| `network.peer.port`     | `3306` |
+| `network.transport`     | `"tcp"` |
+| `db.name`               | `"ShopDb"` |
+| `db.statement`          | `"SELECT * FROM orders WHERE order_id = ?"` |
+| `db.operation`          | `"SELECT"` |
+| `db.sql.table`          | `"orders"` |
+
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md

model/registry/db.yaml

@@ -66,7 +66,7 @@ groups:
         type: string
         brief: The name of the primary Cassandra 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.
+          This mirrors the `db.sql.table` attribute but references `cassandra` rather than `sql`.
           It is not recommended to attempt any client-side parsing of
           `db.statement` just to get this property, but it should be set if
           it is provided by the library being instrumented.

model/trace/database.yaml

@@ -59,6 +59,8 @@ groups:
     attributes:
       - ref: db.mssql.instance_name
         tag: connection-level-tech-specific
+      - ref: db.sql.table
+        tag: connection-level-tech-specific
 
   - id: db.cassandra
     type: span