Update exception recording guidelines to not use span events

.chloggen/3256.yaml

@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: exceptions
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Update exception recording guidelines to not use span events.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [3256]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:

.github/copilot-instructions.md

@@ -96,7 +96,7 @@ these requirements:
 
 - **Spans**: Set status to Error, populate `error.type`, set description when helpful
 - **Metrics**: Include `error.type` attribute for filtering and analysis
-- **Exceptions**: Record as span events or log records using SDK APIs
+- **Exceptions**: Record as log records
 - **Consistency**: Same `error.type` across spans and metrics for same operation
 
 ## Common Issues to Flag

docs/exceptions/exceptions-spans.md

@@ -23,7 +23,7 @@ exceptions associated with spans.
 <!-- see templates/registry/markdown/snippet.md.j2 -->
 <!-- prettier-ignore-start -->
 
-**Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen)
+**Status:** ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Use logs to record exceptions instead.
 
 The event name MUST be `exception`.
 

docs/general/recording-errors.md

@@ -83,14 +83,16 @@ include it if the operation succeeded.
 
 ## Recording exceptions
 
-When an instrumented operation fails with an exception, instrumentation SHOULD record
-this exception as a [span event](/docs/exceptions/exceptions-spans.md) or a [log record](/docs/exceptions/exceptions-logs.md).
+When an instrumented operation throws an exception, instrumentation SHOULD
+record this exception as a [log record](/docs/exceptions/exceptions-logs.md).
 
-It's RECOMMENDED to use the `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 application configuration.
+When the instrumented operation has not succeeded due to an exception,
+refer to the [recording errors on spans](#recording-errors-on-spans)
+and to the [recording errors on metrics](#recording-errors-on-metrics)
+on capturing exception details on these signals.
 
 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.
 
 For example, in this code-snippet, `ResourceAlreadyExistsException` is handled and the corresponding
@@ -100,22 +102,25 @@ to the caller should be recorded (or logged) once.
 ```java
 public boolean createIfNotExists(String resourceId) throws IOException {
   Span span = startSpan();
+  long startTime = System.nanoTime();
   try {
     create(resourceId);
+    recordMetric("acme.resource.create.duration", System.nanoTime() - startTime);
     return true;
   } 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
+    // not setting span status to error - as the exception is not an error
+    // but we still log and set attributes that capture additional details
+    logger.debug(e);
     span.setAttribute(AttributeKey.stringKey("acme.resource.create.status"), "already_exists");
+    recordMetric("acme.resource.create.duration", System.nanoTime() - startTime);
     return false;
   } catch (IOException e) {
-    // recording exception here (assuming it was not recorded inside `create` method)
-    span.recordException(e);
-    // or
-    // logger.warn(e);
-
-    span.setAttribute(AttributeKey.stringKey("error.type"), e.getClass().getCanonicalName())
+    logger.error(e);
+    String errorType = e.getClass().getCanonicalName();
+    span.setAttribute(AttributeKey.stringKey("error.type"), errorType);
     span.setStatus(StatusCode.ERROR, e.getMessage());
+    recordMetric("acme.resource.create.duration", System.nanoTime() - startTime,
+                 AttributeKey.stringKey("error.type"), errorType);
     throw e;
   }
 }

model/exceptions/events.yaml → model/exceptions/deprecated/events-deprecated.yaml

@@ -2,6 +2,9 @@ groups:
   - id: event.exception
     name: exception
     stability: stable
+    deprecated:
+      reason: obsoleted
+      note: Use logs to record exceptions instead.
     type: event
     brief: >
       This event describes a single exception.