Define sampling relevant attributes for database client spans (#1166)

Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>

.chloggen/1166.yaml

@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: breaking
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: db
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Sampling relevant attributes defined for database client spans
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [ 1019 ]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:

docs/database/cassandra.md

@@ -10,7 +10,7 @@ The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend a
 that describe common database operations attributes in addition to the Semantic Conventions
 described on this page.
 
-`db.system` MUST be set to `"cassandra"`.
+`db.system` MUST be set to `"cassandra"` and SHOULD be provided **at span creation time**.
 
 ## Attributes
 
@@ -75,6 +75,16 @@ If a parameter has no name and instead is referenced only by index, then `<key>`
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`db.collection.name`](/docs/attributes-registry/db.md)
+* [`db.namespace`](/docs/attributes-registry/db.md)
+* [`db.operation.name`](/docs/attributes-registry/db.md)
+* [`db.query.text`](/docs/attributes-registry/db.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `db.cassandra.consistency_level` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value  | Description | Stability |

docs/database/cosmosdb.md

@@ -13,7 +13,7 @@ described on this page.
 
 ## Attributes
 
-`db.system` MUST be set to `"cosmosdb"`.
+`db.system` MUST be set to `"cosmosdb"` and SHOULD be provided **at span creation time**.
 
 Cosmos DB instrumentation includes call-level (public API) surface spans and network spans. Depending on the connection mode (Gateway or Direct), network-level spans may also be created.
 
@@ -76,6 +76,16 @@ If a parameter has no name and instead is referenced only by index, then `<key>`
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`db.collection.name`](/docs/attributes-registry/db.md)
+* [`db.namespace`](/docs/attributes-registry/db.md)
+* [`db.operation.name`](/docs/attributes-registry/db.md)
+* [`db.query.text`](/docs/attributes-registry/db.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `db.cosmosdb.connection_mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value  | Description | Stability |

docs/database/couchdb.md

@@ -10,7 +10,7 @@ The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and o
 that describe common database operations attributes in addition to the Semantic Conventions
 described on this page.
 
-`db.system` MUST be set to `"couchdb"`.
+`db.system` MUST be set to `"couchdb"` and SHOULD be provided **at span creation time**.
 
 ## Attributes
 
@@ -43,6 +43,14 @@ described on this page.
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`db.namespace`](/docs/attributes-registry/db.md)
+* [`db.operation.name`](/docs/attributes-registry/db.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value  | Description | Stability |

docs/database/database-spans.md

@@ -142,6 +142,17 @@ If a parameter has no name and instead is referenced only by index, then `<key>`
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`db.collection.name`](/docs/attributes-registry/db.md)
+* [`db.namespace`](/docs/attributes-registry/db.md)
+* [`db.operation.name`](/docs/attributes-registry/db.md)
+* [`db.query.text`](/docs/attributes-registry/db.md)
+* [`db.system`](/docs/attributes-registry/db.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value  | Description | Stability |

docs/database/elasticsearch.md

@@ -10,7 +10,7 @@ The Semantic Conventions for [Elasticsearch](https://www.elastic.co/) extend and
 that describe common database operations attributes in addition to the Semantic Conventions
 described on this page.
 
-`db.system` MUST be set to `"elasticsearch"`.
+`db.system` MUST be set to `"elasticsearch"` and SHOULD be provided **at span creation time**.
 
 ## Span Name
 
@@ -84,6 +84,18 @@ Even though parameterized query text can potentially have sensitive data, by usi
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`db.collection.name`](/docs/attributes-registry/db.md)
+* [`db.namespace`](/docs/attributes-registry/db.md)
+* [`db.operation.name`](/docs/attributes-registry/db.md)
+* [`db.query.text`](/docs/attributes-registry/db.md)
+* [`http.request.method`](/docs/attributes-registry/http.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+* [`url.full`](/docs/attributes-registry/url.md)
+
 `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value  | Description | Stability |

docs/database/hbase.md

@@ -10,7 +10,7 @@ The Semantic Conventions for [HBase](https://hbase.apache.org/) extend and overr
 that describe common database operations attributes in addition to the Semantic Conventions
 described on this page.
 
-`db.system` MUST be set to `"hbase"`.
+`db.system` MUST be set to `"hbase"` and SHOULD be provided **at span creation time**.
 
 ## Attributes
 
@@ -50,6 +50,15 @@ For batch operations, if the individual operations are known to have the same op
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`db.collection.name`](/docs/attributes-registry/db.md)
+* [`db.namespace`](/docs/attributes-registry/db.md)
+* [`db.operation.name`](/docs/attributes-registry/db.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value  | Description | Stability |

docs/database/mongodb.md

@@ -10,7 +10,7 @@ The Semantic Conventions for [MongoDB](https://www.mongodb.com/) extend and over
 that describe common database operations attributes in addition to the Semantic Conventions
 described on this page.
 
-`db.system` MUST be set to `"mongodb"`.
+`db.system` MUST be set to `"mongodb"` and SHOULD be provided **at span creation time**.
 
 ## Attributes
 
@@ -48,6 +48,15 @@ For batch operations, if the individual operations are known to have the same co
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`db.collection.name`](/docs/attributes-registry/db.md)
+* [`db.namespace`](/docs/attributes-registry/db.md)
+* [`db.operation.name`](/docs/attributes-registry/db.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value  | Description | Stability |

docs/database/mssql.md

@@ -10,7 +10,7 @@ The Semantic Conventions for the *Microsoft SQL Server* extend and override the
 that describe common database operations attributes in addition to the Semantic Conventions
 described on this page.
 
-`db.system` MUST be set to `"mssql"`.
+`db.system` MUST be set to `"mssql"` and SHOULD be provided **at span creation time**.
 
 ## Attributes
 
@@ -65,6 +65,16 @@ If a parameter has no name and instead is referenced only by index, then `<key>`
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`db.collection.name`](/docs/attributes-registry/db.md)
+* [`db.namespace`](/docs/attributes-registry/db.md)
+* [`db.operation.name`](/docs/attributes-registry/db.md)
+* [`db.query.text`](/docs/attributes-registry/db.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value  | Description | Stability |

docs/database/redis.md

@@ -10,7 +10,7 @@ The Semantic Conventions for [Redis](https://redis.com/) extend and override the
 that describe common database operations attributes in addition to the Semantic Conventions
 described on this page.
 
-`db.system` MUST be set to `"redis"`.
+`db.system` MUST be set to `"redis"` and SHOULD be provided **at span creation time**.
 
 ## Attributes
 
@@ -63,6 +63,15 @@ If a parameter has no name and instead is referenced only by index, then `<key>`
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`db.namespace`](/docs/attributes-registry/db.md)
+* [`db.operation.name`](/docs/attributes-registry/db.md)
+* [`db.query.text`](/docs/attributes-registry/db.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value  | Description | Stability |

docs/database/sql.md

@@ -104,6 +104,15 @@ If a parameter has no name and instead is referenced only by index, then `<key>`
 
 
 
+The following attributes can be important for making sampling decisions
+and SHOULD be provided **at span creation time** (if provided at all):
+
+* [`db.collection.name`](/docs/attributes-registry/db.md)
+* [`db.operation.name`](/docs/attributes-registry/db.md)
+* [`db.query.text`](/docs/attributes-registry/db.md)
+* [`server.address`](/docs/attributes-registry/server.md)
+* [`server.port`](/docs/attributes-registry/server.md)
+
 `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value  | Description | Stability |

model/trace/database.yaml

@@ -1,10 +1,26 @@
 groups:
-  - id: trace.db.common.query
+  - id: trace.db.common.minimal
     extends: attributes.db.client.minimal
     type: attribute_group
     brief: This group defines the attributes used to perform database client calls.
+    attributes:
+      # TODO: add db.system once https://github.com/open-telemetry/build-tools/issues/192 is possible
+      # - ref: db.system
+      #   sampling_relevant: true
+      - ref: db.operation.name
+        sampling_relevant: true
+      - ref: server.address
+        sampling_relevant: true
+      - ref: server.port
+        sampling_relevant: true
+
+  - id: trace.db.common.query
+    extends: trace.db.common.minimal
+    type: attribute_group
+    brief: This group defines the attributes used to perform database client calls.
     attributes:
       - ref: db.query.text
+        sampling_relevant: true
         requirement_level:
           recommended: >
             Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes
@@ -17,11 +33,12 @@ groups:
         requirement_level: opt_in
 
   - id: trace.db.common.query_and_collection
-    extends: attributes.db.client.minimal
+    extends: trace.db.common.minimal
     type: attribute_group
     brief: This group defines the attributes used to perform database client calls.
     attributes:
       - ref: db.query.text
+        sampling_relevant: true
         requirement_level:
           recommended: >
             SHOULD be collected by default only if there is sanitization that excludes sensitive information.
@@ -29,6 +46,7 @@ groups:
       - ref: db.query.parameter
         requirement_level: opt_in
       - ref: db.collection.name
+        sampling_relevant: true
         requirement_level:
           conditionally_required: >
             If readily available. The collection name MAY be parsed from the query text,
@@ -52,9 +70,11 @@ groups:
         requirement_level:
           recommended: if and only if `network.peer.address` is set.
       - ref: db.system
+        sampling_relevant: true
         # TODO: Not adding to the minimal because of https://github.com/open-telemetry/build-tools/issues/192
         requirement_level: required
       - ref: db.namespace
+        sampling_relevant: true
         requirement_level:
           conditionally_required: If available.
 
@@ -72,6 +92,7 @@ groups:
       Attributes for Microsoft SQL Server
     attributes:
       - ref: db.namespace
+        sampling_relevant: true
         brief: The name of the database, fully qualified within the server address and port.
         note:
           When connecting to a default instance, `db.namespace` SHOULD be set to the name of
@@ -88,6 +109,7 @@ groups:
       Attributes for Cassandra
     attributes:
       - ref: db.namespace
+        sampling_relevant: true
         brief: The Cassandra keyspace name.
         note: For commands that switch the keyspace, this SHOULD be set to the target keyspace (even if the command fails).
         examples: ["mykeyspace"]
@@ -112,11 +134,12 @@ groups:
           recommended: if and only if `network.peer.address` is set.
   - id: db.hbase
     type: span
-    extends: attributes.db.client.minimal
+    extends: trace.db.common.minimal
     brief: >
       Attributes for HBase
     attributes:
       - ref: db.namespace
+        sampling_relevant: true
         brief: The HBase namespace.
         requirement_level:
           conditionally_required: If applicable.
@@ -126,6 +149,7 @@ groups:
           instrumentation SHOULD set `db.namespace` value to `default`.
         examples: ['mynamespace']
       - ref: db.collection.name
+        sampling_relevant: true
         brief: The HBase table name.
         requirement_level:
           conditionally_required: If applicable.
@@ -135,11 +159,12 @@ groups:
 
   - id: db.couchdb
     type: span
-    extends: attributes.db.client.minimal
+    extends: trace.db.common.minimal
     brief: >
       Attributes for CouchDB
     attributes:
       - ref: db.operation.name
+        sampling_relevant: true
         brief: >
           The HTTP method + the target REST route.
         examples: ['GET /{db}/{docid}']
@@ -150,6 +175,7 @@ groups:
           (literally, i.e., without replacing the placeholders with concrete values):
           [`GET /{db}/{docid}`](https://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid).
       - ref: db.namespace
+        sampling_relevant: true
         requirement_level:
           conditionally_required: If available.
         note: ""  # overriding the base note
@@ -161,6 +187,7 @@ groups:
       Attributes for Redis
     attributes:
       - ref: db.namespace
+        sampling_relevant: true
         brief: >
           The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select)
           (captured as a string).
@@ -176,6 +203,7 @@ groups:
           For commands that switch the database, this SHOULD be set to the target database (even if the command fails).
         examples: ["0", "1", "15"]
       - ref: db.query.text
+        sampling_relevant: true
         brief: >
           The full syntax of the Redis CLI command.
         examples: ["HMSET myhash field1 'Hello' field2 'World'"]
@@ -194,21 +222,24 @@ groups:
 
   - id: db.mongodb
     type: span
-    extends: attributes.db.client.minimal
+    extends: trace.db.common.minimal
     brief: >
       Attributes for MongoDB
     attributes:
       - ref: db.operation.name
+        sampling_relevant: true
         brief: >
           The name of the command being executed.
         note: >
           See [MongoDB database commands](https://www.mongodb.com/docs/manual/reference/command/).
         examples: ['findAndModify', 'getMore', 'update']
       - ref: db.collection.name
+        sampling_relevant: true
         brief:
           The MongoDB collection being accessed within the database stated in `db.namespace`.
         requirement_level: required
       - ref: db.namespace
+        sampling_relevant: true
         brief: The MongoDB database name.
         requirement_level:
           conditionally_required: If available.
@@ -216,11 +247,12 @@ groups:
 
   - id: db.elasticsearch
     type: span
-    extends: attributes.db.client.minimal
+    extends: trace.db.common.minimal
     brief: >
       Attributes for Elasticsearch
     attributes:
       - ref: http.request.method
+        sampling_relevant: true
         requirement_level: required
       - ref: db.operation.name
         requirement_level: required
@@ -229,9 +261,11 @@ groups:
           (see the [Elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json)).
         examples: [ 'search', 'ml.close_job', 'cat.aliases' ]
       - ref: url.full
+        sampling_relevant: true
         requirement_level: required
         examples: [ 'https://localhost:9200/index/_search?q=user.id:kimchy' ]
       - ref: db.query.text
+        sampling_relevant: true
         requirement_level:
           recommended: >
             Should be collected by default for search-type queries and only if there is sanitization that excludes
@@ -239,15 +273,15 @@ groups:
         brief: The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string.
         examples: [ '"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"' ]
       - ref: db.collection.name
+        sampling_relevant: true
         requirement_level: recommended
         brief: The index or data stream against which the query is executed.
         note: >
           The query may target multiple indices or data streams, in which case it SHOULD be a comma separated list of those.
           If the query doesn't target a specific index, this field MUST NOT be set.
         examples: [ 'my_index', 'index1, index2' ]
-      - ref: server.address
-      - ref: server.port
       - ref: db.namespace
+        sampling_relevant: true
         note: >
           When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header.
         brief: The name of the Elasticsearch cluster which the client connects to.
@@ -342,6 +376,7 @@ groups:
         requirement_level:
           conditionally_required: when available
       - ref: db.namespace
+        sampling_relevant: true
         requirement_level:
           conditionally_required: If available.
         note: ""  # overriding the base note