Deprecate exception.escaped attribute, update exception example (#4368)

Author: Liudmila Molkova

CHANGELOG.md

@@ -11,6 +11,10 @@ release.
 
 ### Traces
 
+- Deprecate `exception.escaped` attribute, add link to in-development semantic-conventions
+  on how to record errors across signals.
+  ([#4368](https://github.com/open-telemetry/opentelemetry-specification/pull/4368))
+
 ### Metrics
 
 ### Logs

specification/semantic-conventions.md

@@ -11,28 +11,29 @@ OpenTelemetry defines its semantic conventions in a separate repository:
 
 Semantic conventions MUST provide the following attributes:
 
-- Resource
-  - `service.name`
-  - `telemetry.sdk.language`
-  - `telemetry.sdk.name`
-  - `telemetry.sdk.version`
-- Event
-  - `exception.escaped`
-  - `exception.message`
-  - `exception.stacktrace`
-  - `exception.type`
+- [`error.type`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/attributes-registry/error.md#error-type)
+- [`exception.message`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/attributes-registry/exception.md#exception-message)
+- [`exception.stacktrace`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/attributes-registry/exception.md#exception-stacktrace)
+- [`exception.type`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/attributes-registry/exception.md#exception-type)
+- [`server.address`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/attributes-registry/server.md#server-address)
+- [`server.port`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/attributes-registry/server.md#server-port)
+- [`service.name`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/attributes-registry/service.md#service-name)
+- [`telemetry.sdk.language`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/attributes-registry/telemetry.md#telemetry-sdk-language)
+- [`telemetry.sdk.name`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/attributes-registry/telemetry.md#telemetry-sdk-name)
+- [`telemetry.sdk.version`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/attributes-registry/telemetry.md#telemetry-sdk-version)
+- [`url.scheme`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/attributes-registry/url.md#url-scheme)
+
+Semantic conventions MUST provide the following events:
+
+- [`exception`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-spans.md)
 
 ## In-development Reserved Attributes
 
 Semantic conventions MUST provide the following attributes:
 
-- Resource
-  - `server.address`
-  - `server.port`
-  - `service.instance.id`
-  - `url.scheme`
+- [`service.instance.id`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/attributes-registry/service.md#service-instance-id)
 
 ## Reserved Namespace
 
 The `otel.*` namespace is reserved for defining compatibility with
-non-opentelemetry technologies.
+non-OpenTelemetry technologies.

specification/trace/exceptions.md

@@ -1,9 +1,8 @@
 # Exceptions
 
-**Status**: [Stable](../document-status.md)
+**Status**: [Stable](../document-status.md), Unless otherwise specified.
 
-This document defines how to record exceptions and
-their required attributes.
+This document defines how to record exceptions and their attributes.
 
 <!-- toc -->
 
@@ -14,9 +13,14 @@ their required attributes.
 
 ## Recording an Exception
 
-An exception SHOULD be recorded as an `Event` on the span during which it occurred.
+An exception SHOULD be recorded as an `Event` on the span during which it occurred
+if and only if it remains unhandled when the span ends and causes the span status
+to be set to ERROR.
+
 The name of the event MUST be `"exception"`.
 
+**Status**: [Development](../document-status.md) - Refer to the [Recording Errors](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/recording-errors.md) document for the details on how to report errors across signals.
+
 A typical template for an auto-instrumentation implementing this semantic convention
 using an [API-provided `recordException` method](api.md#record-exception)
 could look like this (pseudo-Java):
@@ -26,7 +30,9 @@ Span span = myTracer.startSpan(/*...*/);
 try {
   // Code that does the actual work which the Span represents
 } catch (Throwable e) {
-  span.recordException(e, Attributes.of("exception.escaped", true));
+  span.recordException(e);
+  span.setAttribute(AttributeKey.stringKey("error.type"), e.getClass().getCanonicalName())
+  span.setStatus(StatusCode.ERROR, e.getMessage());
   throw e;
 } finally {
   span.end();
@@ -41,7 +47,6 @@ event name `exception`.
 Additionally, the following attributes SHOULD be
 filled out:
 
-- `exception.escaped`
 - `exception.message`
 - `exception.stacktrace`
 - `exception.type`