diff --git a/.chloggen/1560.yaml b/.chloggen/1560.yaml new file mode 100644 index 0000000000..241a109b52 --- /dev/null +++ b/.chloggen/1560.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: db +note: Specify how to set span kind for database operations. +issues: [1536, 1560] diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 06c08b0597..7f885e1e2e 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -11,6 +11,8 @@ linkTitle: Client Calls - [Name](#name) +- [Status](#status) + - [Recording exception events](#recording-exception-events) - [Common attributes](#common-attributes) - [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem) - [Sanitization of `db.query.text`](#sanitization-of-dbquerytext) @@ -85,6 +87,56 @@ and SHOULD adhere to one of the following values, provided they are accessible: If a corresponding `{target}` value is not available for a specific operation, the instrumentation SHOULD omit the `{target}`. For example, for an operation describing SQL query on an anonymous table like `SELECT * FROM (SELECT * FROM table) t`, span name should be `SELECT`. +## Status + +[Span Status Code][SpanStatus] MUST be left unset if the operation has ended without any errors. + +Instrumentation SHOULD consider the operation as failed if any of the following is true: + +- the `db.response.status_code` value indicates an error + + > [!NOTE] + > The classification of status code as an error depends on the context. + > For example, a SQL STATE `02000` (`no_data`) indicates an error when the application + > expected the data to be available. However, it is not an error when the + > application is simply checking whether the data exists. + > + > Instrumentations that have additional context about a specific operation MAY use + > this context to set the span status more precisely. + > Instrumentations that don't have any additional context MUST follow the + > guidelines in this section. + +- an exception is thrown by the instrumented method call +- the instrumented method returns an error in another way + +When the operation ends with an error, instrumentation: + +- SHOULD set the span status code to `Error` +- SHOULD set the `error.type` attribute +- SHOULD set the span status description when it has additional information + about the error that aligns with [Span Status Description][SpanStatus]. + + It's NOT RECOMMENDED to duplicate `db.response.status_code` or `error.type` + in span status description. + + When the operation fails with an exception, the span status description SHOULD be set to + the exception message. + +### Recording exception events + +**Status**: [Experimental][DocumentStatus] + +When the operation fails with an exception, instrumentation SHOULD record +an [exception event](../exceptions/exceptions-spans.md) by default if and only if the +span being recorded is a local root span (does not have a local parent). + +> [!NOTE] +> Exception stack traces could be very long and are expensive to capture and store. +> Exceptions which are not handled by instrumented libraries are likely to be handled +> and logged by the caller. +> Exceptions that are not handled will be recorded by the outermost (local root) +> instrumentation such as HTTP or gRPC server. + ## Common attributes These attributes will usually be the same for all operations performed over the same database connection. @@ -422,3 +474,4 @@ More specific Semantic Conventions are defined for the following database techno * [SQL](sql.md): Semantic Conventions for *SQL* databases. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status +[SpanStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/trace/api.md#set-status