From 847e1a06c83771484b6909ee5c992a4de6d84e84 Mon Sep 17 00:00:00 2001
From: Liudmila Molkova <limolkova@microsoft.com>
Date: Wed, 15 Jan 2025 18:58:09 -0800
Subject: [PATCH] =?UTF-8?q?Deprecate=20=1Bxception.escaped=20attribute,=20?=
 =?UTF-8?q?update=20exception=20example,=20clean=20up=20semconv=20doc?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 specification/semantic-conventions.md | 33 ++++++++++++++-------------
 specification/trace/exceptions.md     | 14 ++++++++----
 2 files changed, 26 insertions(+), 21 deletions(-)

diff --git a/specification/semantic-conventions.md b/specification/semantic-conventions.md
index 326749bf793..5fb1b37073b 100644
--- a/specification/semantic-conventions.md
+++ b/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/v1.29.0/docs/attributes-registry/error.md#error-type)
+- [`exception.message`](https://github.com/open-telemetry/semantic-conventions/blob/v1.29.0/docs/attributes-registry/exception.md#exception-message)
+- [`exception.stacktrace`](https://github.com/open-telemetry/semantic-conventions/blob/v1.29.0/docs/attributes-registry/exception.md#exception-stacktrace)
+- [`exception.type`](https://github.com/open-telemetry/semantic-conventions/blob/v1.29.0/docs/attributes-registry/exception.md#exception-type)
+- [`server.address`](https://github.com/open-telemetry/semantic-conventions/blob/v1.29.0/docs/attributes-registry/server.md#server-address)
+- [`server.port`](https://github.com/open-telemetry/semantic-conventions/blob/v1.29.0/docs/attributes-registry/server.md#server-port)
+- [`service.name`](https://github.com/open-telemetry/semantic-conventions/blob/v1.29.0/docs/attributes-registry/service.md#service-name)
+- [`telemetry.sdk.language`](https://github.com/open-telemetry/semantic-conventions/blob/v1.29.0/docs/attributes-registry/telemetry.md#telemetry-sdk-language)
+- [`telemetry.sdk.name`](https://github.com/open-telemetry/semantic-conventions/blob/v1.29.0/docs/attributes-registry/telemetry.md#telemetry-sdk-name)
+- [`telemetry.sdk.version`](https://github.com/open-telemetry/semantic-conventions/blob/v1.29.0/docs/attributes-registry/telemetry.md#telemetry-sdk-version)
+- [`url.scheme`](https://github.com/open-telemetry/semantic-conventions/blob/v1.29.0/docs/attributes-registry/url.md#url-scheme)
+
+Semantic conventions MUST provide the following events:
+
+- [`exception`](https://github.com/open-telemetry/semantic-conventions/blob/v1.29.0/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/v1.29.0/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.
diff --git a/specification/trace/exceptions.md b/specification/trace/exceptions.md
index 8ede02b5886..329b338b854 100644
--- a/specification/trace/exceptions.md
+++ b/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 -->
 
@@ -17,6 +16,9 @@ their required attributes.
 An exception SHOULD be recorded as an `Event` on the span during which it occurred.
 The name of the event MUST be `"exception"`.
 
+<!-- TODO: update to semconv tag once merged and released  -->
+**Status**: [Development](../document-status.md) - Refer to the [Recording Errors](https://github.com/open-telemetry/semantic-conventions/blob/c77c7d7866c943b357d1d26ffa2fa89b092f2b9f/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 +28,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 +45,7 @@ event name `exception`.
 Additionally, the following attributes SHOULD be
 filled out:
 
-- `exception.escaped`
+- [Deprecated](../document-status.md) `exception.escaped`
 - `exception.message`
 - `exception.stacktrace`
 - `exception.type`