Database semantic conventions: Add db.table, allow SQL keyword as db.…

…operation (#1141) * Add db.table to database semantic conventions * Fix spacing in db semantic conventions * Move db.table to SQL-specific call level attributes * Clarify instructions for setting db.operation to a SQL keyword * Specify that db.sql.table MUST NOT be set when not applicable Co-authored-by: Armin Ruech <[email protected]> * Add db.table and db.operation to CHANGELOG Co-authored-by: Armin Ruech <[email protected]>
open-telemetry · Nov 9, 2020 · 1954360 · 1954360
1 parent 15e35f0
commit 1954360
Show file tree

Hide file tree

Showing 3 changed files with 37 additions and 7 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -59,6 +59,8 @@ New:
   ([#1074](https://github.com/open-telemetry/opentelemetry-specification/pull/1074))
 - Add semantic conventions for system metrics
   ([#937](https://github.com/open-telemetry/opentelemetry-specification/pull/937))
+- Add `db.table` and `db.operation` to semantic conventions
+  ([#1141](https://github.com/open-telemetry/opentelemetry-specification/pull/1141))
 - Add OTEL_TRACE_SAMPLER env variable definition
   ([#1136](https://github.com/open-telemetry/opentelemetry-specification/pull/1136/))
 

diff --git a/semantic_conventions/trace/database.yaml b/semantic_conventions/trace/database.yaml
@@ -191,12 +191,15 @@ groups:
             conditional: Required, if `db.statement` is not applicable.
           brief: >
             The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations)
-            such as `findAndModify`.
+            such as `findAndModify`, or the SQL keyword.
           note: >
-            While it would semantically make sense to set this, e.g., to a SQL keyword like `SELECT` or `INSERT`,
-            it is not recommended to attempt any client-side parsing of `db.statement` just to get this property
-            (the back end can do that if required).
-          examples: ['findAndModify', 'HMSET']
+            When setting this to an SQL keyword, it is not recommended to
+            attempt any client-side parsing of `db.statement` just to get this
+            property, but it should be set if the operation name is provided by
+            the library being instrumented.
+            If the SQL statement has an ambiguous operation, or performs more
+            than one operation, this value may be omitted.
+          examples: ['findAndModify', 'HMSET', 'SELECT']
         - ref: net.peer.name
           tag: connection-level
           required:
@@ -294,10 +297,32 @@ groups:
             The collection being accessed within the database stated in `db.name`.
           examples: [ 'customers', 'products' ]
 
+    - id: db.sql
+      prefix: 'db.sql'
+      extends: 'db'
+      brief: >
+        Call-level attrbiutes for SQL databases
+      attributes:
+        - id: table
+          tag: call-level-tech-specific
+          type: string
+          required:
+            conditional: Recommended if available.
+          brief: The name of the primary table that the operation is acting upon, including the schema name (if applicable).
+          note: >
+            It is not recommended to attempt any client-side parsing of
+            `db.statement` just to get this property, but it should be set if
+            it is provided by the library being instrumented.
+            If the operation is acting upon an anonymous table, or more than one table, this
+            value MUST NOT be set.
+          examples: ['public.users', 'customers']
+
+
     - id: db.tech
       brief: "Semantic convention group for specific technologies"
       constraints:
         - include: 'db.cassandra'
         - include: 'db.hbase'
         - include: 'db.redis'
         - include: 'db.mongodb'
+        - include: 'db.sql'
diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md
@@ -135,15 +135,15 @@ Usually only one `db.name` will be used per connection though.
 |---|---|---|---|---|
 | `db.name` | string | If no [tech-specific attribute](#call-level-attributes-for-specific-technologies) is defined, this attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`<br>`main` | Conditional [2] |
 | `db.statement` | string | The database statement being executed. [3] | `SELECT * FROM wuser_table`<br>`SET mykey "WuValue"` | Conditional<br>Required if applicable. |
-| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`. [4] | `findAndModify`<br>`HMSET` | Conditional<br>Required, if `db.statement` is not applicable. |
+| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. [4] | `findAndModify`<br>`HMSET`<br>`SELECT` | Conditional<br>Required, if `db.statement` is not applicable. |
 
 **[1]:** In some SQL databases, the database name to be used is called "schema name".
 
 **[2]:** Required, if applicable and no more-specific attribute is defined.
 
 **[3]:** The value may be sanitized to exclude sensitive information.
 
-**[4]:** While it would semantically make sense to set this, e.g., to a SQL keyword like `SELECT` or `INSERT`, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property (the back end can do that if required).
+**[4]:** When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted.
 <!-- endsemconv -->
 
 For **Redis**, the value provided for `db.statement` SHOULD correspond to the syntax of the Redis CLI.
@@ -165,8 +165,11 @@ For example, when retrieving a document, `db.operation` would be set to (literal
 | `db.hbase.namespace` | string | The [HBase namespace](https://hbase.apache.org/book.html#_namespace) being accessed. To be used instead of the generic `db.name` attribute. | `default` | Yes |
 | `db.redis.database_index` | number | The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. | `0`<br>`1`<br>`15` | Conditional [1] |
 | `db.mongodb.collection` | string | The collection being accessed within the database stated in `db.name`. | `customers`<br>`products` | Yes |
+| `db.sql.table` | string | The name of the primary table that the operation is acting upon, including the schema name (if applicable). [2] | `public.users`<br>`customers` | Conditional<br>Recommended if available. |
 
 **[1]:** Required, if other than the default database (`0`).
+
+**[2]:** It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set.
 <!-- endsemconv -->
 
 ## Examples