Merge branch 'main' into add_k8s_ns_phase

.chloggen/1716.yaml

@@ -0,0 +1,4 @@
+change_type: enhancement
+component: docs, db
+note: Add common guidance for recording errors on spans and metrics, clarify DB conventions.
+issues: [1516, 1536, 1716]

CONTRIBUTING.md

@@ -32,6 +32,7 @@ requirements and recommendations.
   - [Auto formatting](#auto-formatting)
   - [Markdown style](#markdown-style)
   - [Misspell check](#misspell-check)
+  - [Update the tables of content](#update-the-tables-of-content)
   - [Markdown link check](#markdown-link-check)
 - [Updating the referenced specification version](#updating-the-referenced-specification-version)
 - [Making a Release](#making-a-release)
@@ -343,6 +344,7 @@ You can also run these fixes individually.
 See:
 
 - [Misspell Correction](#misspell-check)
+- [Update the tables of content](#update-the-tables-of-content)
 - [Update the markdown files](#2-update-the-markdown-files)
 
 ### Markdown style
@@ -389,6 +391,14 @@ To quickly fix typos, use
 make misspell-correction
 ```
 
+### Update the tables of content
+
+To update the tables of content, run:
+
+```bash
+make markdown-toc
+```
+
 ### Markdown link check
 
 To check the validity of links in all markdown files, run the following command:

docs/attributes-registry/artifact.md

@@ -13,7 +13,7 @@ This group describes attributes specific to artifacts. Artifacts are files or ot
 | Attribute | Type | Description | Examples | Stability |
 |---|---|---|---|---|
 | <a id="artifact-attestation-filename" href="#artifact-attestation-filename">`artifact.attestation.filename`</a> | string | The provenance filename of the built attestation which directly relates to the build artifact filename. This filename SHOULD accompany the artifact at publish time. See the [SLSA Relationship](https://slsa.dev/spec/v1.0/distributing-provenance#relationship-between-artifacts-and-attestations) specification for more information. | `golang-binary-amd64-v0.1.0.attestation`; `docker-image-amd64-v0.1.0.intoto.json1`; `release-1.tar.gz.attestation`; `file-name-package.tar.gz.intoto.json1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| <a id="artifact-attestation-hash" href="#artifact-attestation-hash">`artifact.attestation.hash`</a> | string | The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), of the built attestation. Some envelopes in the software attestation space also refer to this as the [digest](https://github.com/in-toto/attestation/blob/main/spec/README.md#in-toto-attestation-framework-spec). | `1b31dfcd5b7f9267bf2ff47651df1cfb9147b9e4df1f335accf65b4cda498408` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| <a id="artifact-attestation-hash" href="#artifact-attestation-hash">`artifact.attestation.hash`</a> | string | The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), of the built attestation. Some envelopes in the [software attestation space](https://github.com/in-toto/attestation/tree/main/spec) also refer to this as the **digest**. | `1b31dfcd5b7f9267bf2ff47651df1cfb9147b9e4df1f335accf65b4cda498408` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="artifact-attestation-id" href="#artifact-attestation-id">`artifact.attestation.id`</a> | string | The id of the build [software attestation](https://slsa.dev/attestation-model). | `123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="artifact-filename" href="#artifact-filename">`artifact.filename`</a> | string | The human readable file name of the artifact, typically generated during build and release processes. Often includes the package name and version in the file name. [1] | `golang-binary-amd64-v0.1.0`; `docker-image-amd64-v0.1.0`; `release-1.tar.gz`; `file-name-package.tar.gz` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="artifact-hash" href="#artifact-hash">`artifact.hash`</a> | string | The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), often found in checksum.txt on a release of the artifact and used to verify package integrity. [2] | `9ff4c52759e2c4ac70b7d517bc7fcdc1cda631ca0045271ddd1b192544f8a3e9` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

docs/attributes-registry/exception.md

@@ -6,30 +6,23 @@
 
 # Exception
 
+- [Exception Attributes](#exception-attributes)
+- [Deprecated Exception Attributes](#deprecated-exception-attributes)
+
 ## Exception Attributes
 
 This document defines the shared attributes used to report a single exception associated with a span or log.
 
 | Attribute | Type | Description | Examples | Stability |
 |---|---|---|---|---|
-| <a id="exception-escaped" href="#exception-escaped">`exception.escaped`</a> | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] |  | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 | <a id="exception-message" href="#exception-message">`exception.message`</a> | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 | <a id="exception-stacktrace" href="#exception-stacktrace">`exception.stacktrace`</a> | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 | <a id="exception-type" href="#exception-type">`exception.type`</a> | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 
-**[1] `exception.escaped`:** An exception is considered to have escaped (or left) the scope of a span,
-if that span is ended while the exception is still logically "in flight".
-This may be actually "in flight" in some languages (e.g. if the exception
-is passed to a Context manager's `__exit__` method in Python) but will
-usually be caught at the point of recording the exception in most languages.
-
-It is usually not possible to determine at the point where an exception is thrown
-whether it will escape the scope of a span.
-However, it is trivial to know that an exception
-will escape, if one checks for an active exception just before ending the span,
-as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception).
-
-It follows that an exception may still escape the scope of the span
-even if the `exception.escaped` attribute was not set or set to false,
-since the event might have been recorded at a time where it was not
-clear whether the exception will escape.
+## Deprecated Exception Attributes
+
+Deprecated exception attributes.
+
+| Attribute | Type | Description | Examples | Stability |
+|---|---|---|---|---|
+| <a id="exception-escaped" href="#exception-escaped">`exception.escaped`</a> | boolean | Indicates that the exception is escaping the scope of the span. |  | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>It's no longer recommended to record exceptions that are handled and do not escape the scope of a span. |

docs/cli/cli-spans.md

@@ -13,7 +13,8 @@ Span kind SHOULD be `INTERNAL` when the traced program is the callee or `CLIENT`
 The span name SHOULD be set to `{process.executable.name}`.
 Instrumentations that have additional context about executed commands MAY use a different low-cardinality span name format and SHOULD document it.
 
-Span status SHOULD be set to `Error` if `{process.exit.code}` is not 0.
+Span status SHOULD be set to `Error` if `{process.exit.code}` is not 0. Refer to the [Recording Errors](/docs/general/recording-errors.md) document for
+additional details on how to record span status.
 
 <!-- TODO: context propagation https://github.com/open-telemetry/semantic-conventions/issues/1612 -->
 

docs/database/cassandra.md

@@ -69,8 +69,7 @@ system specific term if more applicable.
 
 **[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
 
-**[6] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
-Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
+**[6] `db.response.status_code`:** All Cassandra protocol error codes SHOULD be considered errors.
 
 **[7] `db.response.status_code`:** If the operation failed and status code is available.
 

docs/database/cosmosdb.md

@@ -193,8 +193,7 @@ additional values when introducing new operations.
 
 **[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query.
 
-**[6] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
-Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
+**[6] `db.response.status_code`:** Response codes in the 4xx and 5xx range SHOULD be considered errors.
 
 **[7] `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/couchdb.md

@@ -23,16 +23,15 @@ The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and o
 |---|---|---|---|---|---|
 | [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
 | [`db.operation.name`](/docs/attributes-registry/db.md) | string | The HTTP method + the target REST route. [1] | `GET /{db}/{docid}` | `Conditionally Required` If readily available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
-| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | The HTTP response code returned by the Couch DB. [2] | `200`; `201`; `429` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
+| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | The HTTP response code returned by the Couch DB recorded as a string. [2] | `200`; `201`; `429` | `Conditionally Required` [3] | ![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. [4] | `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. [5] | `80`; `8080`; `443` | `Conditionally Required` [6] | ![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. [7] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
 | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 
 **[1] `db.operation.name`:** In **CouchDB**, `db.operation.name` should be set to the HTTP method + the target REST route according to the API reference documentation. For example, when retrieving a document, `db.operation.name` would be set to (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).
 
-**[2] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
-Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
+**[2] `db.response.status_code`:** HTTP response codes in the 4xx and 5xx range SHOULD be considered errors.
 
 **[3] `db.response.status_code`:** If response was received and the HTTP response code is available.
 

docs/database/database-spans.md

@@ -12,7 +12,6 @@ linkTitle: Client Calls
 
 - [Name](#name)
 - [Status](#status)
-  - [Recording exception events](#recording-exception-events)
 - [Common attributes](#common-attributes)
   - [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem)
 - [Sanitization of `db.query.text`](#sanitization-of-dbquerytext)
@@ -89,59 +88,11 @@ For example, for an operation describing SQL query on an anonymous table like `S
 
 ## Status
 
-[Span Status Code][SpanStatus] MUST be left unset if the operation has ended without any errors.
+Refer to the [Recording Errors](/docs/general/recording-errors.md) document for
+details on how to record span status.
 
-Instrumentation SHOULD consider the operation as failed if any of the following is true:
-
-- the `db.response.status_code` value indicates an error
-
-  > [!NOTE]
-  >
-  > The classification of status code as an error depends on the context.
-  > For example, a SQL STATE `02000` (`no_data`) indicates an error when the application
-  > expected the data to be available. However, it is not an error when the
-  > application is simply checking whether the data exists.
-  >
-  > Instrumentations that have additional context about a specific operation MAY use
-  > this context to set the span status more precisely.
-  > Instrumentations that don't have any additional context MUST follow the
-  > guidelines in this section.
-
-- an exception is thrown by the instrumented method call
-- the instrumented method returns an error in another way
-
-When the operation ends with an error, instrumentation:
-
-- SHOULD set the span status code to `Error`
-- SHOULD set the `error.type` attribute
-- SHOULD set the span status description when it has additional information
-  about the error which is not expected to contain sensitive details and aligns
-  with [Span Status Description][SpanStatus] definition.
-
-  It's NOT RECOMMENDED to duplicate `db.response.status_code` or `error.type`
-  in span status description.
-
-  When the operation fails with an exception, the span status description SHOULD be set to
-  the exception message.
-
-### Recording exception events
-
-**Status**: [Experimental][DocumentStatus]
-
-When the operation fails with an exception, instrumentation SHOULD record
-an [exception event](../exceptions/exceptions-spans.md) by default if, and only if,
-the span being recorded is a local root span (does not have a local parent).
-
-> [!NOTE]
->
-> Exception stack traces could be very long and are expensive to capture and store.
-> Exceptions which are not handled by instrumented libraries are likely to be handled
-> and logged by the caller.
-> Exceptions that are not handled will be recorded by the outermost (local root)
-> instrumentation such as HTTP or gRPC server.
-
-Instrumentation MAY provide a configuration option to record exceptions that
-escape the surface of the instrumented API.
+Semantic conventions for individual systems SHOULD specify which values of `db.response.status_code`
+classify as errors.
 
 ## Common attributes
 
@@ -466,4 +417,3 @@ More specific Semantic Conventions are defined for the following database techno
 * [SQL](sql.md): Semantic Conventions for *SQL* databases.
 
 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
-[SpanStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status

docs/database/elasticsearch.md

@@ -82,8 +82,7 @@ When a query string value is redacted, the query string key SHOULD still be pres
 
 **[4] `db.elasticsearch.path_parts`:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.<key>`, where `<key>` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names.
 
-**[5] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes.
-Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system.
+**[5] `db.response.status_code`:** HTTP response codes in the 4xx and 5xx range SHOULD be considered errors.
 
 **[6] `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.