Record failures on the span that represents the operation that failed, using the OpenTelemetry SDK and the semantic conventions for the operation.

Recording a failure

1. Preserve the exception or error in the application’s normal error-handling path.
2. Record exception details using the SDK’s supported exception-event API when appropriate.
3. Set the span status to Error when the operation has failed according to its semantic convention.
4. Add a bounded error classification attribute when it improves grouping or diagnosis.
5. End the span and rethrow, return, or handle the error according to application behavior.

Do not set every span to Ok; leave status unset when there is no error unless the application has a specific reason to mark success explicitly. Recording telemetry must not change whether an error is retried, returned, or surfaced to the caller.

Inspect a recorded failure

The following example shows Failed status and an ERROR indicator.

The following child span detail shows error attributes.

Protect sensitive data

Exception messages and stack traces can contain tokens, personal data, SQL, or request payloads. Review what the SDK records, redact or omit sensitive values, and avoid placing raw error text in attributes. Validate error traces using test data before enabling broadly.