diff --git a/.chloggen/1069.yaml b/.chloggen/1069.yaml new file mode 100644 index 0000000000..24a7720e98 --- /dev/null +++ b/.chloggen/1069.yaml @@ -0,0 +1,7 @@ +change_type: enhancement + +component: db + +note: 'Update database span name: clarify that target depends on the operation and should not be set when corresponding data is not available.' + +issues: [1045] diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 09d4e0be08..53f2156bc9 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -56,20 +56,25 @@ Database spans MUST follow the overall [guidelines for span names](https://githu 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). +(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). +If neither `{db.operation.name}` nor `{target}` are available, span name SHOULD be `{db.system}`. + 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: +The `{target}` SHOULD describe the entity that the operation is performed against +and SHOULD adhere to one of the following values, provided they are accessible: + +- `db.collection.name` SHOULD be used for data manipulation operations or operations on database collections. +- `db.namespace` SHOULD be used for operations on a specific database namespace. +- `server.address:server.port` SHOULD be used for other operations not targeting any specific database(s) or collection(s) -- `db.collection.name` -- `db.namespace` -- `server.address:server.port` -- `db.system` +If a corresponding `{target}` value is not available for a specific operation, the instrumentation SHOULD omit the `{target}`. +For example, for an operation describing SQL query on an anonymous table like `SELECT * FROM (SELECT * FROM table) t`, span name should be `SELECT`. ## Common attributes