fix(db): Clarify db.query.text and db.query.summary attributes (#208)

* fix(db): Clarify `db.query.text` and `db.query.summary` attributes

* changelog

* single example, generate, format

* leave changelog as-is

Author: Lms24

generated/attributes/all.md

@@ -49,8 +49,8 @@ Total attributes: 423
 | [`db.namespace`](./db.md#dbnamespace) | The name of the database being accessed. |
 | [`db.operation.name`](./db.md#dboperationname) | The name of the operation being executed. |
 | [`db.query.parameter.\<key\>`](./db.md#dbqueryparameterkey) | A query parameter used in db.query.text, with <key> being the parameter name, and the attribute value being a string representation of the parameter value. |
-| [`db.query.summary`](./db.md#dbquerysummary) | A database query being executed. Should be paramaterized. The full version of the query is in `db.query.text`. |
-| [`db.query.text`](./db.md#dbquerytext) | The database query being executed. Should be the full query, not a parameterized version. The parameterized version is in `db.query.summary`. |
+| [`db.query.summary`](./db.md#dbquerysummary) | A shortened representation of operation(s) in the full query. This attribute must be low-cardinality and should only contain the operation table names. |
+| [`db.query.text`](./db.md#dbquerytext) | The database parameterized query being executed. Any parameter values (filters, insertion values, etc) should be replaced with parameter placeholders. If applicable, use `db.query.parameter.<key>` to add the parameter value. |
 | [`db.redis.connection`](./db.md#dbredisconnection) | The redis connection name. |
 | [`db.redis.parameters`](./db.md#dbredisparameters) | The array of command parameters given to a redis command. |
 | [`db.system.name`](./db.md#dbsystemname) | An identifier for the database management system (DBMS) product being used. See [OpenTelemetry docs](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-spans.md#notes-and-well-known-identifiers-for-dbsystem) for a list of well-known identifiers. |

generated/attributes/db.md

@@ -71,25 +71,25 @@ A query parameter used in db.query.text, with \<key\> being the parameter name,
 
 ### db.query.summary
 
-A database query being executed. Should be paramaterized. The full version of the query is in `db.query.text`.
+A shortened representation of operation(s) in the full query. This attribute must be low-cardinality and should only contain the operation table names.
 
 | Property | Value |
 | --- | --- |
 | Type | `string` |
 | Has PII | maybe |
 | Exists in OpenTelemetry | Yes |
-| Example | `SELECT * FROM users` |
+| Example | `SELECT users;` |
 
 ### db.query.text
 
-The database query being executed. Should be the full query, not a parameterized version. The parameterized version is in `db.query.summary`.
+The database parameterized query being executed. Any parameter values (filters, insertion values, etc) should be replaced with parameter placeholders. If applicable, use `db.query.parameter.\<key\>` to add the parameter value.
 
 | Property | Value |
 | --- | --- |
 | Type | `string` |
 | Has PII | maybe |
 | Exists in OpenTelemetry | Yes |
-| Example | `SELECT * FROM users` |
+| Example | `SELECT * FROM users WHERE id = $1` |
 | Aliases | `db.statement` |
 
 ### db.redis.connection

javascript/sentry-conventions/src/attributes.ts

@@ -1391,15 +1391,15 @@ export type DB_QUERY_PARAMETER_KEY_TYPE = string;
 // Path: model/attributes/db/db__query__summary.json
 
 /**
- * A database query being executed. Should be paramaterized. The full version of the query is in `db.query.text`. `db.query.summary`
+ * A shortened representation of operation(s) in the full query. This attribute must be low-cardinality and should only contain the operation table names. `db.query.summary`
  *
  * Attribute Value Type: `string` {@link DB_QUERY_SUMMARY_TYPE}
  *
  * Contains PII: maybe
  *
  * Attribute defined in OTEL: Yes
  *
- * @example "SELECT * FROM users"
+ * @example "SELECT users;"
  */
 export const DB_QUERY_SUMMARY = 'db.query.summary';
 
@@ -1411,7 +1411,7 @@ export type DB_QUERY_SUMMARY_TYPE = string;
 // Path: model/attributes/db/db__query__text.json
 
 /**
- * The database query being executed. Should be the full query, not a parameterized version. The parameterized version is in `db.query.summary`. `db.query.text`
+ * The database parameterized query being executed. Any parameter values (filters, insertion values, etc) should be replaced with parameter placeholders. If applicable, use `db.query.parameter.<key>` to add the parameter value. `db.query.text`
  *
  * Attribute Value Type: `string` {@link DB_QUERY_TEXT_TYPE}
  *
@@ -1421,7 +1421,7 @@ export type DB_QUERY_SUMMARY_TYPE = string;
  *
  * Aliases: {@link DB_STATEMENT} `db.statement`
  *
- * @example "SELECT * FROM users"
+ * @example "SELECT * FROM users WHERE id = $1"
  */
 export const DB_QUERY_TEXT = 'db.query.text';
 
@@ -10408,23 +10408,23 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
   },
   [DB_QUERY_SUMMARY]: {
     brief:
-      'A database query being executed. Should be paramaterized. The full version of the query is in `db.query.text`.',
+      'A shortened representation of operation(s) in the full query. This attribute must be low-cardinality and should only contain the operation table names.',
     type: 'string',
     pii: {
       isPii: 'maybe',
     },
     isInOtel: true,
-    example: 'SELECT * FROM users',
+    example: 'SELECT users;',
   },
   [DB_QUERY_TEXT]: {
     brief:
-      'The database query being executed. Should be the full query, not a parameterized version. The parameterized version is in `db.query.summary`.',
+      'The database parameterized query being executed. Any parameter values (filters, insertion values, etc) should be replaced with parameter placeholders. If applicable, use `db.query.parameter.<key>` to add the parameter value.',
     type: 'string',
     pii: {
       isPii: 'maybe',
     },
     isInOtel: true,
-    example: 'SELECT * FROM users',
+    example: 'SELECT * FROM users WHERE id = $1',
     aliases: [DB_STATEMENT],
   },
   [DB_REDIS_CONNECTION]: {

model/attributes/db/db__query__summary.json

@@ -1,10 +1,10 @@
 {
   "key": "db.query.summary",
-  "brief": "A database query being executed. Should be paramaterized. The full version of the query is in `db.query.text`.",
+  "brief": "A shortened representation of operation(s) in the full query. This attribute must be low-cardinality and should only contain the operation table names.",
   "type": "string",
   "pii": {
     "key": "maybe"
   },
   "is_in_otel": true,
-  "example": "SELECT * FROM users"
+  "example": "SELECT users;"
 }

model/attributes/db/db__query__text.json

@@ -1,11 +1,11 @@
 {
   "key": "db.query.text",
-  "brief": "The database query being executed. Should be the full query, not a parameterized version. The parameterized version is in `db.query.summary`.",
+  "brief": "The database parameterized query being executed. Any parameter values (filters, insertion values, etc) should be replaced with parameter placeholders. If applicable, use `db.query.parameter.<key>` to add the parameter value.",
   "type": "string",
   "pii": {
     "key": "maybe"
   },
   "is_in_otel": true,
-  "example": "SELECT * FROM users",
+  "example": "SELECT * FROM users WHERE id = $1",
   "alias": ["db.statement"]
 }

python/src/sentry_conventions/attributes.py

@@ -901,23 +901,23 @@ class ATTRIBUTE_NAMES(metaclass=_AttributeNamesMeta):
 
     # Path: model/attributes/db/db__query__summary.json
     DB_QUERY_SUMMARY: Literal["db.query.summary"] = "db.query.summary"
-    """A database query being executed. Should be paramaterized. The full version of the query is in `db.query.text`.
+    """A shortened representation of operation(s) in the full query. This attribute must be low-cardinality and should only contain the operation table names.
 
     Type: str
     Contains PII: maybe
     Defined in OTEL: Yes
-    Example: "SELECT * FROM users"
+    Example: "SELECT users;"
     """
 
     # Path: model/attributes/db/db__query__text.json
     DB_QUERY_TEXT: Literal["db.query.text"] = "db.query.text"
-    """The database query being executed. Should be the full query, not a parameterized version. The parameterized version is in `db.query.summary`.
+    """The database parameterized query being executed. Any parameter values (filters, insertion values, etc) should be replaced with parameter placeholders. If applicable, use `db.query.parameter.<key>` to add the parameter value.
 
     Type: str
     Contains PII: maybe
     Defined in OTEL: Yes
     Aliases: db.statement
-    Example: "SELECT * FROM users"
+    Example: "SELECT * FROM users WHERE id = $1"
     """
 
     # Path: model/attributes/db/db__redis__connection.json
@@ -5367,18 +5367,18 @@ class ATTRIBUTE_NAMES(metaclass=_AttributeNamesMeta):
         example="db.query.parameter.foo='123'",
     ),
     "db.query.summary": AttributeMetadata(
-        brief="A database query being executed. Should be paramaterized. The full version of the query is in `db.query.text`.",
+        brief="A shortened representation of operation(s) in the full query. This attribute must be low-cardinality and should only contain the operation table names.",
         type=AttributeType.STRING,
         pii=PiiInfo(isPii=IsPii.MAYBE),
         is_in_otel=True,
-        example="SELECT * FROM users",
+        example="SELECT users;",
     ),
     "db.query.text": AttributeMetadata(
-        brief="The database query being executed. Should be the full query, not a parameterized version. The parameterized version is in `db.query.summary`.",
+        brief="The database parameterized query being executed. Any parameter values (filters, insertion values, etc) should be replaced with parameter placeholders. If applicable, use `db.query.parameter.<key>` to add the parameter value.",
         type=AttributeType.STRING,
         pii=PiiInfo(isPii=IsPii.MAYBE),
         is_in_otel=True,
-        example="SELECT * FROM users",
+        example="SELECT * FROM users WHERE id = $1",
         aliases=["db.statement"],
     ),
     "db.redis.connection": AttributeMetadata(