Add common guidance on recording errors on spans and metrics, clarify DB conventions #1716

lmolkova · 2024-12-28T18:26:59Z

Document HTTP + DB approach for span status + description as generic for spans
Document error.type as generic error attribute on spans and metrics
Specify how to classify db.response.status_codes as failures
Update recommendation to record exceptions as a span events or log records

Important

We can and should implement strategy of reporting exceptions on local root spans in OTel SDK - it should not be an instrumentation concern.

Here's an OTEP on how to record exceptions on logs - it discusses the details of configurable exception recording strategy.
Since public facing log API is in development, we'll keep using span events for the time being.

Merge requirement checklist

CONTRIBUTING.md guidelines followed.
Change log entry added, according to the guidelines in When to add a changelog entry.
- If your PR does not need a change log, start the PR title with [chore]
schema-next.yaml updated with changes to existing conventions.

Copilot reviewed 5 out of 20 changed files in this pull request and generated no comments.

Files not reviewed (15)

docs/database/redis.md: Evaluated as low risk
docs/database/cassandra.md: Evaluated as low risk
docs/database/cosmosdb.md: Evaluated as low risk
docs/rpc/rpc-spans.md: Evaluated as low risk
docs/messaging/messaging-spans.md: Evaluated as low risk
docs/cli/cli-spans.md: Evaluated as low risk
docs/http/http-spans.md: Evaluated as low risk
docs/general/recording-errors.md: Evaluated as low risk
docs/gen-ai/gen-ai-spans.md: Evaluated as low risk
docs/faas/faas-spans.md: Evaluated as low risk
docs/exceptions/README.md: Evaluated as low risk
docs/database/elasticsearch.md: Evaluated as low risk
docs/database/database-spans.md: Evaluated as low risk
docs/database/mongodb.md: Evaluated as low risk
docs/database/couchdb.md: Evaluated as low risk

docs/exceptions/README.md

trask · 2025-01-09T02:20:45Z

docs/exceptions/README.md

+
+**Status**: [Development][DocumentStatus]
+
+When instrumented operation fails with an exception, instrumentation SHOULD record


Suggested change

When instrumented operation fails with an exception, instrumentation SHOULD record

When an instrumented operation fails with an exception, instrumentation SHOULD record

trask · 2025-01-09T02:21:17Z

docs/exceptions/README.md

+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 `Span.recordException` API or logging library API that takes exception instance


Suggested change

It's RECOMMENDED to use `Span.recordException` API or logging library API that takes exception instance

It's RECOMMENDED to use the `Span.recordException` API or logging library API that takes exception instance

trask · 2025-01-09T02:21:55Z

docs/exceptions/README.md

+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, `ResourceNotFoundException` is handled and corresponding


Suggested change

For example, in this code-snippet, `ResourceNotFoundException` is handled and corresponding

For example, in this code-snippet, `ResourceAlreadyExistsException` is handled and the corresponding

trask · 2025-01-09T02:22:33Z

docs/exceptions/README.md

+native instrumentation should not record it. Other exceptions, that are propagated
+to the caller, should be recorded (or logged) once.


Suggested change

native instrumentation should not record it. Other exceptions, that are propagated

to the caller, should be recorded (or logged) once.

native instrumentation should not record it. Exceptions which are propagated

to the caller should be recorded (or logged) once.

trask · 2025-01-09T02:24:37Z

docs/general/recording-errors.md

+
+**Status**: [Development][DocumentStatus].
+
+This document provides recommendations to semantic conventions and instrumentation authors


Suggested change

This document provides recommendations to semantic conventions and instrumentation authors

This document provides recommendations to semantic convention and instrumentation authors

trask · 2025-01-09T02:25:05Z

docs/general/recording-errors.md

+
+## What constitutes an error
+
+Operation SHOULD be considered as failed if any of the following is true:


Suggested change

Operation SHOULD be considered as failed if any of the following is true:

An operation SHOULD be considered as failed if any of the following is true:

trask · 2025-01-09T02:26:49Z

docs/general/recording-errors.md

+  > Instrumentations that have additional context about a specific request MAY use
+  > this context to set the span status more precisely.
+
+Errors that were retried or handled allowing operation to complete gracefully SHOULD NOT


Suggested change

Errors that were retried or handled allowing operation to complete gracefully SHOULD NOT

Errors that were retried or handled (allowing an operation to complete gracefully) SHOULD NOT

trask · 2025-01-09T02:34:37Z

.chloggen/1716.yaml

@@ -0,0 +1,4 @@
+change_type: enhancement
+component: docs, db
+note: Add common guidance on recording errors on spans and metrics, clarify DB conventions.


Suggested change

note: Add common guidance on recording errors on spans and metrics, clarify DB conventions.

note: Add common guidance for recording errors on spans and metrics, clarify DB conventions.

trask · 2025-01-09T02:39:34Z

docs/http/http-spans.md

+Refer to the [Recording Errors](/docs/general/recording-errors.md) document for
+general considerations on how to record span status.
+


maybe?

Suggested change

Refer to the [Recording Errors](/docs/general/recording-errors.md) document for

general considerations on how to record span status.

**Status**: [Development][DocumentStatus] - Refer to the [Recording Errors](/docs/general/recording-errors.md) document for

general considerations on how to record span status.

lmolkova · 2025-01-09T04:50:19Z

docs/exceptions/exceptions-spans.md

@@ -11,33 +11,6 @@ exceptions associated with spans.

 <!-- toc -->

- [Recording an Exception](#recording-an-exception)


It's a duplicate of the spec doc https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/exceptions.md

lmolkova requested review from a team as code owners December 28, 2024 18:27

lmolkova requested a review from Copilot December 28, 2024 18:28

Copilot AI reviewed Dec 28, 2024

View reviewed changes

joaopgrassi reviewed Dec 30, 2024

View reviewed changes

docs/exceptions/README.md Outdated Show resolved Hide resolved

lmolkova force-pushed the generic-recording-errors branch from 4aa1c75 to 4c1fdc3 Compare January 3, 2025 01:11

lmolkova added 5 commits January 8, 2025 16:47

Add generic guidance on recording errors on spans and metrics

116ef58

provide system-specific db status code notes

59a5313

changelog and lint

45ebafd

feedback and some clarifications

176716a

Remove exception.escapted, update examples, remove old example

456f377

lmolkova force-pushed the generic-recording-errors branch from 4c1fdc3 to 456f377 Compare January 9, 2025 01:40

trask reviewed Jan 9, 2025

View reviewed changes

lmolkova commented Jan 9, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add common guidance on recording errors on spans and metrics, clarify DB conventions #1716

Add common guidance on recording errors on spans and metrics, clarify DB conventions #1716

lmolkova commented Dec 28, 2024 •

edited

Loading

trask Jan 9, 2025

trask Jan 9, 2025

trask Jan 9, 2025

trask Jan 9, 2025

trask Jan 9, 2025

trask Jan 9, 2025

trask Jan 9, 2025

trask Jan 9, 2025

trask Jan 9, 2025

lmolkova Jan 9, 2025


		Status: [Development][DocumentStatus]

		When instrumented operation fails with an exception, instrumentation SHOULD record

	When instrumented operation fails with an exception, instrumentation SHOULD record
	When an instrumented operation fails with an exception, instrumentation SHOULD record

	It's RECOMMENDED to use `Span.recordException` API or logging library API that takes exception instance
	It's RECOMMENDED to use the `Span.recordException` API or logging library API that takes exception instance

	For example, in this code-snippet, `ResourceNotFoundException` is handled and corresponding
	For example, in this code-snippet, `ResourceAlreadyExistsException` is handled and the corresponding

		native instrumentation should not record it. Other exceptions, that are propagated
		to the caller, should be recorded (or logged) once.


		Status: [Development][DocumentStatus].

		This document provides recommendations to semantic conventions and instrumentation authors


		## What constitutes an error

		Operation SHOULD be considered as failed if any of the following is true:

	Operation SHOULD be considered as failed if any of the following is true:
	An operation SHOULD be considered as failed if any of the following is true:

	Errors that were retried or handled allowing operation to complete gracefully SHOULD NOT
	Errors that were retried or handled (allowing an operation to complete gracefully) SHOULD NOT

	note: Add common guidance on recording errors on spans and metrics, clarify DB conventions.
	note: Add common guidance for recording errors on spans and metrics, clarify DB conventions.

		Refer to the [Recording Errors](/docs/general/recording-errors.md) document for
		general considerations on how to record span status.

		@@ -11,33 +11,6 @@ exceptions associated with spans.

		<!-- toc -->

		- [Recording an Exception](#recording-an-exception)

Add common guidance on recording errors on spans and metrics, clarify DB conventions #1716

Are you sure you want to change the base?

Add common guidance on recording errors on spans and metrics, clarify DB conventions #1716

Conversation

lmolkova commented Dec 28, 2024 • edited Loading

Merge requirement checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lmolkova commented Dec 28, 2024 •

edited

Loading