From 1f37350ab20c0af4670c93fc50563f8678144f15 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 15 Jan 2025 17:15:33 -0800 Subject: [PATCH] move 'recording exceptions' to recording_errors.md doc --- docs/exceptions/README.md | 52 +------------------------------- docs/general/recording-errors.md | 42 +++++++++++++++++++++++++- 2 files changed, 42 insertions(+), 52 deletions(-) diff --git a/docs/exceptions/README.md b/docs/exceptions/README.md index a1dcf2e495..6c1c976e10 100644 --- a/docs/exceptions/README.md +++ b/docs/exceptions/README.md @@ -7,61 +7,11 @@ path_base_for_github_subdir: # Semantic Conventions for Exceptions -**Status**: [Stable][DocumentStatus], Unless otherwise specified. +**Status**: [Stable][DocumentStatus] 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 exceptions in instrumentation code - -**Status**: [Development][DocumentStatus] - -When an 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) attribute - -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 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. - -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 -native instrumentation should not record it. Exceptions which are propagated -to the caller should be recorded (or logged) once. - -```java -public boolean createIfNotExists(String resourceId) throws IOException { - Span span = startSpan(); - try { - create(resourceId); - 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 - 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.warn(e); - - span.setAttribute(AttributeKey.stringKey("error.type"), e.getClass().getCanonicalName()) - span.setStatus(StatusCode.ERROR, e.getMessage()); - throw e; - } -} -``` - [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/general/recording-errors.md b/docs/general/recording-errors.md index 01c91541ae..af118a155d 100644 --- a/docs/general/recording-errors.md +++ b/docs/general/recording-errors.md @@ -52,7 +52,7 @@ When the operation ends with an error, instrumentation: When the operation fails with an exception, the span status description SHOULD be set to the exception message. -Refer to the [general exception guidance](/docs/exceptions/README.md) on capturing exception +Refer to the [recording exceptions](#recording-errors) on capturing exception details. ## How to record errors on metrics @@ -76,5 +76,45 @@ and metrics when both are reported. A span and its corresponding metric for a si operation SHOULD have the same `error.type` value if the operation failed and SHOULD NOT 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](exceptions-spans.md) or a [log record](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. + +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 +native instrumentation should not record it. Exceptions which are propagated +to the caller should be recorded (or logged) once. + +```java +public boolean createIfNotExists(String resourceId) throws IOException { + Span span = startSpan(); + try { + create(resourceId); + 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 + 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.warn(e); + + span.setAttribute(AttributeKey.stringKey("error.type"), e.getClass().getCanonicalName()) + span.setStatus(StatusCode.ERROR, e.getMessage()); + throw e; + } +} +``` + [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status [SpanStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status