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: deprecation
+
+# 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

AREAS.md

@@ -39,7 +39,7 @@ their owners, related project (and project board) as well as its current status.
 | Semantic Conventions: Database | [semconv-db-approvers](https://github.com/orgs/open-telemetry/teams/semconv-db-approvers) | https://github.com/open-telemetry/community/blob/main/projects/completed-projects/database-client-semconv.md | https://github.com/orgs/open-telemetry/projects/73 | `area:db` | `inactive` | The SIG is inactive. Bugs and bugfixes are welcome. For substantial changes, follow the [new project process](https://github.com/open-telemetry/community/blob/main/project-management.md) |
 | Semantic Conventions: FaaS | [specs-semconv-maintainers](https://github.com/orgs/open-telemetry/teams/specs-semconv-maintainers) | https://github.com/open-telemetry/community/blob/main/projects/completed-projects/faas.md | N/A | `area:faas` | `inactive` | The SIG is inactive. Bugs and bugfixes are welcome. For substantial changes, follow the [new project process](https://github.com/open-telemetry/community/blob/main/project-management.md) |
 | Semantic Conventions: JVM | [semconv-jvm-approvers](https://github.com/orgs/open-telemetry/teams/semconv-jvm-approvers) | N/A | https://github.com/orgs/open-telemetry/projects/49 | `area:jvm` | `inactive` | The SIG is inactive. Bugs and bugfixes are welcome. For substantial changes, follow the [new project process](https://github.com/open-telemetry/community/blob/main/project-management.md) |
-| Semantic Conventions: Logs | [semconv-log-approvers](https://github.com/orgs/open-telemetry/teams/semconv-log-approvers) | N/A | N/A | `area:log`, `area:event`, `area:exception` | `accepting_contributions`, `active` | The SIG is looking for contributions! |
+| Semantic Conventions: Logs | [semconv-log-approvers](https://github.com/orgs/open-telemetry/teams/semconv-log-approvers) | N/A | https://github.com/orgs/open-telemetry/projects/65 | `area:log`, `area:event`, `area:exception` | `accepting_contributions`, `active` | The SIG is looking for contributions! |
 | Semantic Conventions: Mainframe | [sig-mainframe-approvers](https://github.com/orgs/open-telemetry/teams/sig-mainframe-approvers) | https://github.com/open-telemetry/community/blob/main/projects/mainframe.md | N/A | `area:mainframe`, `area:zos` | `accepting_contributions`, `active` | The SIG is looking for contributions! |
 | Semantic Conventions: Profiling | [profiling-approvers](https://github.com/orgs/open-telemetry/teams/profiling-approvers) | N/A | N/A | `area:profile`, `area:pprof` | `accepting_contributions`, `active` | The SIG is looking for contributions! |
 | Semantic Conventions: .NET | [semconv-dotnet-approver](https://github.com/orgs/open-telemetry/teams/semconv-dotnet-approver) | N/A | N/A | `area:dotnet`, `area:aspnetcore`, `area:signalr`, `area:kestrel` | `accepting_contributions`, `active` | SIG is driven by members of the .NET runtime team. Contributions are welcomed but must be aligned with the .NET runtime features/roadmap |

areas.yaml

@@ -190,7 +190,7 @@ areas:
       - name: "semconv-log-approvers"
         github: semconv-log-approvers
     project: "N/A"
-    board: "N/A"
+    board: "https://github.com/orgs/open-telemetry/projects/65"
     labels:
       - area:log
       - area:event

docs/exceptions/exceptions-spans.md

@@ -4,7 +4,8 @@ linkTitle: Spans
 
 # Semantic conventions for exceptions on spans
 
-**Status**: [Stable][DocumentStatus]
+**Status**: [Deprecated](https://img.shields.io/badge/-deprecated-red)<br>
+Use [Semantic conventions for exceptions in logs](exceptions-logs.md) instead.
 
 This document defines semantic conventions for recording application
 exceptions associated with spans.
@@ -23,7 +24,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`.
 
@@ -79,4 +80,3 @@ grained information from a stacktrace, if necessary.
 [telemetry-sdk-resource]: ../resource/README.md#telemetry-sdk
 [erlang-stacktrace]: https://www.erlang.org/doc/apps/stdlib/erl_error.html#format_exception/3
 [elixir-stacktrace]: https://hexdocs.pm/elixir/1.14.3/Exception.html#format/3
-[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

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 instrumented code 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,38 @@ 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.withEventName("acme.resource.create.error")
+      .withAttribute("acme.resource.create.status", "already_exists")
+      .withException(e)
+      .debug()
+
     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);
+    logger.withEventName("acme.resource.create.error")
+      .withException(e)
+      .warn()  // this exception is expected to be handled by the caller and could be a transient error
 
-    span.setAttribute(AttributeKey.stringKey("error.type"), e.getClass().getCanonicalName())
+    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.