Mark database semconv as release candidate

trask · Aug 16, 2024 · 95fc25e · 95fc25e
1 parent b6793e2
commit 95fc25e
Show file tree

Hide file tree

Showing 3 changed files with 62 additions and 49 deletions.
diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md
@@ -4,29 +4,25 @@ linkTitle: Metrics
 
 # Semantic Conventions for Database Metrics
 
-**Status**: [Experimental][DocumentStatus]
-
-The conventions described in this section are specific to SQL and NoSQL clients.
-
-**Disclaimer:** These are initial database client metric instruments
-and attributes but more may be added in the future.
+**Status**: [Mixed][DocumentStatus]
 
 <!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
 
 <!-- toc -->
 
 - [Database operation](#database-operation)
   - [Metric: `db.client.operation.duration`](#metric-dbclientoperationduration)
-- [Connection pools](#connection-pools)
-  - [Metric: `db.client.connection.count`](#metric-dbclientconnectioncount)
-  - [Metric: `db.client.connection.idle.max`](#metric-dbclientconnectionidlemax)
-  - [Metric: `db.client.connection.idle.min`](#metric-dbclientconnectionidlemin)
-  - [Metric: `db.client.connection.max`](#metric-dbclientconnectionmax)
-  - [Metric: `db.client.connection.pending_requests`](#metric-dbclientconnectionpending_requests)
-  - [Metric: `db.client.connection.timeouts`](#metric-dbclientconnectiontimeouts)
-  - [Metric: `db.client.connection.create_time`](#metric-dbclientconnectioncreate_time)
-  - [Metric: `db.client.connection.wait_time`](#metric-dbclientconnectionwait_time)
-  - [Metric: `db.client.connection.use_time`](#metric-dbclientconnectionuse_time)
+- [Experimental](#experimental)
+  - [Connection pools](#connection-pools)
+    - [Metric: `db.client.connection.count`](#metric-dbclientconnectioncount)
+    - [Metric: `db.client.connection.idle.max`](#metric-dbclientconnectionidlemax)
+    - [Metric: `db.client.connection.idle.min`](#metric-dbclientconnectionidlemin)
+    - [Metric: `db.client.connection.max`](#metric-dbclientconnectionmax)
+    - [Metric: `db.client.connection.pending_requests`](#metric-dbclientconnectionpending_requests)
+    - [Metric: `db.client.connection.timeouts`](#metric-dbclientconnectiontimeouts)
+    - [Metric: `db.client.connection.create_time`](#metric-dbclientconnectioncreate_time)
+    - [Metric: `db.client.connection.wait_time`](#metric-dbclientconnectionwait_time)
+    - [Metric: `db.client.connection.use_time`](#metric-dbclientconnectionuse_time)
 
 <!-- tocstop -->
 
@@ -60,7 +56,7 @@ and attributes but more may be added in the future.
 
 ### Metric: `db.client.operation.duration`
 
-**Status**: [Experimental][DocumentStatus]
+**Status**: [Release Candidate][DocumentStatus]
 
 This metric is [required][MetricRequired].
 
@@ -209,11 +205,13 @@ If a database operation involved multiple network calls (for example retries), t
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-## Connection pools
+## Experimental
+
+### Connection pools
 
 The following metric instruments describe database client connection pool operations.
 
-### Metric: `db.client.connection.count`
+#### Metric: `db.client.connection.count`
 
 This metric is [required][MetricRequired].
 
@@ -259,7 +257,8 @@ This metric is [required][MetricRequired].
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-### Metric: `db.client.connection.idle.max`
+
+#### Metric: `db.client.connection.idle.max`
 
 This metric is [recommended][MetricRecommended].
 
@@ -297,7 +296,7 @@ This metric is [recommended][MetricRecommended].
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-### Metric: `db.client.connection.idle.min`
+#### Metric: `db.client.connection.idle.min`
 
 This metric is [recommended][MetricRecommended].
 
@@ -335,7 +334,7 @@ This metric is [recommended][MetricRecommended].
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-### Metric: `db.client.connection.max`
+#### Metric: `db.client.connection.max`
 
 This metric is [recommended][MetricRecommended].
 
@@ -373,7 +372,7 @@ This metric is [recommended][MetricRecommended].
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-### Metric: `db.client.connection.pending_requests`
+#### Metric: `db.client.connection.pending_requests`
 
 This metric is [recommended][MetricRecommended].
 
@@ -411,7 +410,7 @@ This metric is [recommended][MetricRecommended].
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-### Metric: `db.client.connection.timeouts`
+#### Metric: `db.client.connection.timeouts`
 
 This metric is [recommended][MetricRecommended].
 
@@ -449,7 +448,7 @@ This metric is [recommended][MetricRecommended].
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-### Metric: `db.client.connection.create_time`
+#### Metric: `db.client.connection.create_time`
 
 This metric is [recommended][MetricRecommended].
 
@@ -487,7 +486,7 @@ This metric is [recommended][MetricRecommended].
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-### Metric: `db.client.connection.wait_time`
+#### Metric: `db.client.connection.wait_time`
 
 This metric is [recommended][MetricRecommended].
 
@@ -525,7 +524,7 @@ This metric is [recommended][MetricRecommended].
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-### Metric: `db.client.connection.use_time`
+#### Metric: `db.client.connection.use_time`
 
 This metric is [recommended][MetricRecommended].
 

diff --git a/model/metrics/database-metrics.yaml b/model/metrics/database-metrics.yaml
@@ -7,7 +7,7 @@ groups:
       Batch operations SHOULD be recorded as a single operation.
     instrument: histogram
     unit: "s"
-    stability: experimental
+    stability: experimental # RELEASE CANDIDATE
     extends: attributes.db.client.minimal
     attributes:
       - ref: db.collection.name

diff --git a/model/registry/db.yaml b/model/registry/db.yaml
@@ -7,7 +7,7 @@ groups:
     attributes:
       - id: db.collection.name
         type: string
-        stability: experimental
+        stability: experimental # RELEASE CANDIDATE
         brief: The name of a collection (table, container) within the database.
         note: >
           It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
@@ -17,10 +17,12 @@ groups:
 
           For batch operations, if the individual operations are known to have the same collection name
           then that collection name SHOULD be used, otherwise `db.collection.name` SHOULD NOT be captured.
+
+          This attribute has stability level RELEASE CANDIDATE.
         examples: ['public.users', 'customers']
       - id: db.namespace
         type: string
-        stability: experimental
+        stability: experimental # RELEASE CANDIDATE
         brief: >
           The name of the database, fully qualified within the server address and port.
         note: >
@@ -33,10 +35,12 @@ groups:
           means in the context of that system.
 
           It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
+
+          This attribute has stability level RELEASE CANDIDATE.
         examples: [ 'customers', 'test.users' ]
       - id: db.operation.name
         type: string
-        stability: experimental
+        stability: experimental # RELEASE CANDIDATE
         brief: >
           The name of the operation or command being executed.
         note: >
@@ -47,10 +51,12 @@ groups:
           For batch operations, if the individual operations are known to have the same operation name
           then that operation name SHOULD be used prepended by `BATCH `,
           otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable.
+
+          This attribute has stability level RELEASE CANDIDATE.
         examples: ['findAndModify', 'HMSET', 'SELECT']
       - id: db.query.text
         type: string
-        stability: experimental
+        stability: experimental # RELEASE CANDIDATE
         brief: >
           The database query being executed.
         note: >
@@ -63,10 +69,12 @@ groups:
           Even though parameterized query text can potentially have sensitive data, by using a parameterized query
           the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit
           to observability of capturing the static part of the query text by default outweighs the risk.
+
+          This attribute has stability level RELEASE CANDIDATE.
         examples: ['SELECT * FROM wuser_table where username = ?', 'SET mykey "WuValue"']
       - id: db.query.parameter
         type: template[string]
-        stability: experimental
+        stability: experimental # RELEASE CANDIDATE
         brief: >
           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.
@@ -75,21 +83,28 @@ groups:
 
           If a parameter has no name and instead is referenced only by index,
           then `<key>` SHOULD be the 0-based index.
+
+          This attribute has stability level RELEASE CANDIDATE.
         examples: ['someval', '55']
       - id: db.operation.batch.size
         type: int
-        stability: experimental
+        stability: experimental # RELEASE CANDIDATE
         brief: The number of queries included in a [batch operation](/docs/database/database-spans.md#batch-operations).
         note: >
           Operations are only considered batches when they contain two or more operations,
           and so `db.operation.batch.size` SHOULD never be `1`.
+
+          This attribute has stability level RELEASE CANDIDATE.
         examples: [ 2, 3, 4 ]
       - id: db.system
         brief: The database management system (DBMS) product as identified by the client instrumentation.
         note: >
           The actual DBMS may differ from the one identified by the client.
           For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system`
           is set to `postgresql` based on the instrumentation's best knowledge.
+
+          This attribute has stability level RELEASE CANDIDATE.
+        stability: experimental # RELEASE CANDIDATE
         type:
           members:
             - id: other_sql
@@ -145,8 +160,8 @@ groups:
               stability: experimental
             - id: db2
               value: 'db2'
-              brief: 'IBM Db2'
-              stability: experimental
+              brief: 'IBM Db2 (This value has stability level RELEASE CANDIDATE)'
+              stability: experimental # RELEASE CANDIDATE
             - id: derby
               value: 'derby'
               brief: 'Apache Derby'
@@ -182,8 +197,8 @@ groups:
               stability: experimental
             - id: h2
               value: 'h2'
-              brief: 'H2'
-              stability: experimental
+              brief: 'H2 (This value has stability level RELEASE CANDIDATE)'
+              stability: experimental # RELEASE CANDIDATE
             - id: hanadb
               value: 'hanadb'
               brief: 'SAP HANA'
@@ -222,8 +237,8 @@ groups:
               stability: experimental
             - id: mariadb
               value: 'mariadb'
-              brief: 'MariaDB'
-              stability: experimental
+              brief: 'MariaDB (This value has stability level RELEASE CANDIDATE)'
+              stability: experimental # RELEASE CANDIDATE
             - id: maxdb
               value: 'maxdb'
               brief: 'SAP MaxDB'
@@ -238,17 +253,17 @@ groups:
               stability: experimental
             - id: mssql
               value: 'mssql'
-              brief: 'Microsoft SQL Server'
-              stability: experimental
+              brief: 'Microsoft SQL Server (This value has stability level RELEASE CANDIDATE)'
+              stability: experimental # RELEASE CANDIDATE
             - id: mssqlcompact
               value: 'mssqlcompact'
               deprecated: "Removed, use `other_sql` instead."
               brief: "Deprecated, Microsoft SQL Server Compact is discontinued."
               stability: experimental
             - id: mysql
               value: 'mysql'
-              brief: 'MySQL'
-              stability: experimental
+              brief: 'MySQL (This value has stability level RELEASE CANDIDATE)'
+              stability: experimental # RELEASE CANDIDATE
             - id: neo4j
               value: 'neo4j'
               brief: 'Neo4j'
@@ -263,8 +278,8 @@ groups:
               stability: experimental
             - id: oracle
               value: 'oracle'
-              brief: 'Oracle Database'
-              stability: experimental
+              brief: 'Oracle Database (This value has stability level RELEASE CANDIDATE)'
+              stability: experimental # RELEASE CANDIDATE
             - id: pervasive
               value: 'pervasive'
               brief: 'Pervasive PSQL'
@@ -275,8 +290,8 @@ groups:
               stability: experimental
             - id: postgresql
               value: 'postgresql'
-              brief: 'PostgreSQL'
-              stability: experimental
+              brief: 'PostgreSQL (This value has stability level RELEASE CANDIDATE)'
+              stability: experimental # RELEASE CANDIDATE
             - id: progress
               value: 'progress'
               brief: 'Progress Database'
@@ -313,7 +328,6 @@ groups:
               value: 'vertica'
               brief: 'Vertica'
               stability: experimental
-        stability: experimental
       - id: db.client.connection.state
         stability: experimental
         type: