diff --git a/.chloggen/974.yaml b/.chloggen/974.yaml new file mode 100644 index 0000000000..5be41e3283 --- /dev/null +++ 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 index 5e38a20aa4..80ea0bc7a9 100644 --- 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 index eaded43c6e..919a736301 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -10,6 +10,7 @@ linkTitle: Client Calls +- [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: -` .`, 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 ` `. - -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). + + + +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). + + +Semantic conventions for individual database systems MAY specify different span name format. + +The `{target}` 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 index 7d874c3f09..7a48550c8f 100644 --- 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 index ec3c6cd77e..25706de783 100644 --- 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