Remove exception.escapted, update examples, remove old example

Author: Liudmila Molkova

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/exceptions/README.md

@@ -14,16 +14,23 @@ Semantic conventions for Exceptions are defined for the following signals:
 * [Exceptions on spans](exceptions-spans.md): Semantic Conventions for Exceptions associated with *spans*.
 * [Exceptions in logs](exceptions-logs.md): Semantic Conventions for Exceptions recorded in *logs*.
 
-## Reporting errors in instrumentation code
+## Reporting exceptions in instrumentation code
 
 **Status**: [Development][DocumentStatus]
 
 When instrumented operation fails with an exception, instrumentation SHOULD record
 this exception as a [span event](exceptions-spans.md) or a [log record](exceptions-logs.md).
 
+Recording exceptions on spans SHOULD be accompanied by
+- setting span status to `ERROR`
+- setting [`error.type`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/attributes-registry/error.md#error-type)
+
+Refer to the [Recording errors](/docs/general/recording-errors.md) document for additional
+details on how to record errors across different signals.
+
 It's RECOMMENDED to use `Span.recordException` API or logging library API that takes exception instance
 instead of providing individual attributes. This enables the OpenTelemetry SDK to
-control what information is recorded based on user configuration.
+control what information is recorded based on application configuration.
 
 It's NOT RECOMMENDED to record the same exception more than once.
 It's NOT RECOMMENDED to record exceptions that are handled by the instrumented library.
@@ -36,18 +43,21 @@ to the caller, should be recorded (or logged) once.
 public boolean createIfNotExists(String resourceId) throws IOException {
   Span span = startSpan();
   try {
-    create(id);
+    create(resourceId);
     return true;
-  } catch (ResourceNotFoundException e) {
+  } catch (ResourceAlreadyExistsException e) {
     // not recording exception and not setting span status to error - exception is handled
+    // but we can set attributes that capture additional details
+    span.setAttribute(AttributeKey.stringKey("acme.resource.create.status"), "already_exists");
     return false;
   } catch (IOException e) {
     // recording exception here (assuming it was not recorded inside `create` method)
     span.recordException(e);
     // or
-    // logger.atWarning().setCause(e).log();
+    // logger.warn(e);
 
-    span.setStatus(StatusCode.ERROR);
+    span.setAttribute(AttributeKey.stringKey("error.type"), e.getClass().getCanonicalName())
+    span.setStatus(StatusCode.ERROR, e.getMessage());
     throw e;
   }
 }

docs/exceptions/exceptions-spans.md

@@ -11,33 +11,6 @@ exceptions associated with spans.
 
 <!-- toc -->
 
-- [Recording an Exception](#recording-an-exception)
-- [Exception event](#exception-event)
-  - [Stacktrace Representation](#stacktrace-representation)
-
-<!-- tocstop -->
-
-## Recording an Exception
-
-An exception SHOULD be recorded as an `Event` on the span during which it occurred.
-The name of the event MUST be `"exception"`.
-
-A typical template for an auto-instrumentation implementing this semantic convention
-using an [API-provided `recordException` method](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#record-exception)
-could look like this (pseudo-Java):
-
-```java
-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));
-  throw e;
-} finally {
-  span.end();
-}
-```
-
 ## Exception event
 
 <!-- semconv event.exception -->
@@ -57,30 +30,13 @@ This event describes a single exception.
 |---|---|---|---|---|---|
 | [`exception.message`](/docs/attributes-registry/exception.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | `Conditionally Required` [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 | [`exception.type`](/docs/attributes-registry/exception.md) | 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` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
-| [`exception.escaped`](/docs/attributes-registry/exception.md) | 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. [3] |  | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`exception.escaped`](/docs/attributes-registry/exception.md) | boolean | Indicates that the exception is escaping the scope of the span. |  | `Recommended` | ![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. |
 | [`exception.stacktrace`](/docs/attributes-registry/exception.md) | 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)` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 
 **[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise.
 
 **[2] `exception.type`:** Required if `exception.message` is not set, recommended otherwise.
 
-**[3] `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.
-
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->

model/exceptions/deprecated/registry-deprecated.yaml

@@ -0,0 +1,14 @@
+groups:
+  - id: registry.exception.deprecated
+    type: attribute_group
+    display_name: Deprecated Exception Attributes
+    brief: >
+      Deprecated exception attributes.
+    attributes:
+      - id: exception.escaped
+        type: boolean
+        stability: stable
+        deprecated: "It's no longer recommended to record exceptions that are handled
+          and do not escape the scope of a span."
+        brief: >
+          Indicates that the exception is escaping the scope of the span.

model/exceptions/registry.yaml

@@ -31,26 +31,3 @@ groups:
           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)
-      - id: exception.escaped
-        type: boolean
-        stability: stable
-        brief: >
-          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.
-        note: |-
-          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.