provide system-specific db status code notes

Author: Liudmila Molkova

docs/database/mariadb.md

@@ -42,7 +42,9 @@ Instrumentation SHOULD document if `db.namespace` reflects the database provided
 
 It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
 
-**[2] `db.response.status_code`:** When [SQLSTATE](https://mariadb.com/kb/en/sqlstate/) is available, SQLSTATE of "Class 02" or higher SHOULD be considered errors.). When SQLSTATE is not available, all Maria DB error codes SHOULD be considered errors.
+**[2] `db.response.status_code`:** MariaDB uses vendor-specific error codes on all errors and reports [SQLSTATE](https://mariadb.com/kb/en/sqlstate/) in some cases.
+MariaDB error codes are more granular than SQLSTATE, so MariaDB instrumentations SHOULD set the `db.response.status_code` to this known error code.
+When SQLSTATE is available, SQLSTATE of "Class 02" or higher SHOULD be considered errors. When SQLSTATE is not available, all MariaDB error codes SHOULD be considered errors.
 
 **[3] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
 When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.

docs/database/mysql.md

@@ -22,7 +22,7 @@ The Semantic Conventions for *MySQL* extend and override the [Database Semantic
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
 | [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection. [1] | `products`; `customers` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
-| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html). [2] | `1005`; `MY-010016` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
+| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html) recorded as a string. [2] | `1005`; `MY-010016` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
 | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` [5] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
@@ -42,7 +42,7 @@ Instrumentation SHOULD document if `db.namespace` reflects the database provided
 
 It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
 
-**[2] `db.response.status_code`:** All MySQL error codes SHOULD be considered errors.
+**[2] `db.response.status_code`:** MySQL error codes are vendor specific error codes and don't follow [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) conventions. All MySQL error codes SHOULD be considered errors.
 
 **[3] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
 When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.

docs/database/postgresql.md

@@ -49,7 +49,7 @@ Instrumentation SHOULD document if `db.namespace` reflects the user provided whe
 
 It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
 
-**[2] `db.response.status_code`:** Response codes of "Class 02" or higher SHOULD be considered errors.
+**[2] `db.response.status_code`:** PostgreSQL follows SQL standard conventions for [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE). Response codes of "Class 02" or higher SHOULD be considered errors.
 
 **[3] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
 When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.

docs/exceptions/README.md

@@ -7,7 +7,7 @@ path_base_for_github_subdir:
 
 # Semantic Conventions for Exceptions
 
-**Status**: [Mixed][DocumentStatus]
+**Status**: [Stable][DocumentStatus], Unless otherwise specified.
 
 Semantic conventions for Exceptions are defined for the following signals:
 

docs/http/http-spans.md

@@ -118,7 +118,7 @@ When instrumentation detects such errors it SHOULD set span status to `Error`
 and SHOULD set the `error.type` attribute.
 
 Refer to the [Recording Errors](/docs/general/recording-errors.md) document for
-details on how to record span status.
+general considerations on how to record span status.
 
 ## HTTP client
 

model/database/spans.yaml

@@ -187,9 +187,9 @@ groups:
         brief: >
           [PostgreSQL error code](https://www.postgresql.org/docs/current/errcodes-appendix.html).
         note: >
+          PostgreSQL follows SQL standard conventions for [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE).
           Response codes of "Class 02" or higher SHOULD be considered errors.
         examples: ["08000", "08P01"]
-
   - id: span.db.mysql.client
     type: span
     stability: experimental
@@ -214,9 +214,10 @@ groups:
         examples: ["products", "customers"]
       - ref: db.response.status_code
         brief: >
-          [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html).
+          [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html) recorded as a string.
         note: >
-          All MySQL error codes SHOULD be considered errors.
+          MySQL error codes are vendor specific error codes and don't follow [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE)
+          conventions. All MySQL error codes SHOULD be considered errors.
         examples: ["1005", "MY-010016"]
 
   - id: span.db.mariadb.client
@@ -246,12 +247,17 @@ groups:
           [Maria DB error code](https://mariadb.com/kb/en/mariadb-error-code-reference/)
           represented as a string.
         note: >
-          When [SQLSTATE](https://mariadb.com/kb/en/sqlstate/) is available, SQLSTATE of
-          "Class 02" or higher SHOULD be considered errors.). When SQLSTATE is not available,
-          all Maria DB error codes SHOULD be considered errors.
+          MariaDB uses vendor-specific error codes on all errors and reports
+          [SQLSTATE](https://mariadb.com/kb/en/sqlstate/) in some cases.
 
-        examples: ["1008", "3058"]
+          MariaDB error codes are more granular than SQLSTATE, so MariaDB instrumentations
+          SHOULD set the `db.response.status_code` to this known error code.
 
+          When SQLSTATE is available, SQLSTATE of "Class 02" or higher SHOULD be
+          considered errors. When SQLSTATE is not available, all MariaDB error
+          codes SHOULD be considered errors.
+
+        examples: ["1008", "3058"]
   - id: span.db.cassandra.client
     type: span
     span_kind: client