Database: update span name (#974)

Co-authored-by: Trask Stalnaker <[email protected]> Co-authored-by: Joao Grassi <[email protected]>
open-telemetry · May 2, 2024 · 1279742 · 1279742
1 parent 30402c4
commit 1279742
Show file tree

Hide file tree

Showing 5 changed files with 34 additions and 15 deletions.
diff --git a/.chloggen/974.yaml b/.chloggen/974.yaml
@@ -0,0 +1,7 @@
+change_type: breaking
+
+component: db
+
+note: Clarify database span name format and fallback values.
+
+issues: [974, 704]
diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md
@@ -71,7 +71,7 @@ In addition to Cosmos DB attributes, all spans include
 
 | Key                                  | Value |
 |:-------------------------------------| :------------------- |
-| Span name                            | `"ReadItemsAsync"` |
+| Span name                            | `"ReadItemsAsync orders"` |
 | `kind`                               | `"internal"` |
 | `az.namespace`                       | `"Microsoft.DocumentDB"` |
 | `db.system`                          | `"cosmosdb"` |

diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md
@@ -10,6 +10,7 @@ linkTitle: Client Calls
 
 <!-- toc -->
 
+- [Name](#name)
 - [Common attributes](#common-attributes)
   - [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem)
 - [Semantic Conventions for specific database technologies](#semantic-conventions-for-specific-database-technologies)
@@ -51,21 +52,32 @@ 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.
-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.name> <db.namespace>.<db.collection.name>`, provided that `db.operation.name` and `db.collection.name` are available.
-If `db.collection.name` is not available due to its semantics, the span SHOULD be named `<db.operation.name> <db.namespace>`.
-
-It is not recommended to attempt any client-side parsing of `db.query.text` just to get these properties,
-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.namespace` or the tech-specific database name MAY be used.
-
 Span that describes database call SHOULD cover the duration of the corresponding call as if it was observed by the caller (such as client application).
 For example, if a transient issue happened and was retried within this database call, the corresponding span should cover the duration of the logical operation
 with all retries.
 
+## Name
+
+Database spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/trace/api.md#span).
+
+<!-- markdown-link-check-disable -->
+<!-- HTML anchors are not supported https://github.com/tcort/markdown-link-check/issues/225-->
+The **span name** SHOULD be `{db.operation.name} {target}` if there is a
+(low-cardinality) `db.operation.name` available (see below for the exact definition of the [`{target}`](#target-placeholder) placeholder).
+
+If there is no (low-cardinality) `db.operation.name` available, database span names
+SHOULD be [`{target}`](#target-placeholder).
+<!-- markdown-link-check-enable -->
+
+Semantic conventions for individual database systems MAY specify different span name format.
+
+The <span id="target-placeholder">`{target}`</span> SHOULD adhere to one of the following values, arranged in prioritized order, provided they are accessible:
+
+- `db.collection.name`
+- `db.namespace`
+- `server.address:server.port`
+- `db.system`
+
 ## Common attributes
 
 These attributes will usually be the same for all operations performed over the same database connection.

diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md
@@ -34,7 +34,7 @@ described on this page.
 
 | Key                     | Value |
 |:------------------------| :----------------------------------------------------------- |
-| Span name               | `"products.findAndModify"` |
+| Span name               | `"findAndModify products"` |
 | `db.system`             | `"mongodb"` |
 | `server.address`        | `"mongodb0.example.com"` |
 | `server.port`           | `27017` |

diff --git a/docs/database/redis.md b/docs/database/redis.md
@@ -39,12 +39,12 @@ In this example, Redis is connected using a unix domain socket and therefore the
 
 | Key                       | Value |
 |:--------------------------| :-------------------------------------------- |
-| Span name                 | `"HMSET myhash"` |
+| Span name                 | `"HMSET 15"` |
 | `db.system`               | `"redis"` |
 | `network.peer.address`    | `"/tmp/redis.sock"` |
 | `network.transport`       | `"unix"` |
 | `db.namespace`            | `"15"` |
 | `db.query.text`           | `"HMSET myhash field1 'Hello' field2 'World"` |
-| `db.operation.name`       | not set |
+| `db.operation.name`       | `"HMSET"` |
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md