diff --git a/.chloggen/1167.yaml b/.chloggen/1167.yaml new file mode 100644 index 0000000000..cc9655329e --- /dev/null +++ b/.chloggen/1167.yaml @@ -0,0 +1,4 @@ +change_type: bug_fix +component: http +note: "Relax requirement on when to set HTTP span status to Error from `MUST` to `SHOULD`." +issues: [1167, 1003] diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 180d595d41..a22e33506b 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -93,19 +93,31 @@ Instrumentation MUST NOT default to using URI path as a `{target}`. the response body; or 3xx codes with max redirects exceeded), in which case status MUST be set to `Error`. +> **Note:** +> +> The classification of an HTTP status code as an error depends on the context. +> For example, a 404 "Not Found" status code indicates an error if the application +> expected the resource to be available. However, it is not an error when the +> application is simply checking whether the resource exists. +> +> Instrumentations that have additional context about a specific request 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. + For HTTP status codes in the 4xx range span status MUST be left unset in case of `SpanKind.SERVER` -and MUST be set to `Error` in case of `SpanKind.CLIENT`. +and SHOULD be set to `Error` in case of `SpanKind.CLIENT`. For HTTP status codes in the 5xx range, as well as any other code the client -failed to interpret, span status MUST be set to `Error`. +failed to interpret, span status SHOULD be set to `Error`. Don't set the span status description if the reason can be inferred from `http.response.status_code`. HTTP request may fail if it was cancelled or an error occurred preventing the client or server from sending/receiving the request/response fully. -When instrumentation detects such errors it MUST set span status to `Error` -and MUST set the `error.type` attribute. +When instrumentation detects such errors it SHOULD set span status to `Error` +and SHOULD set the `error.type` attribute. ## HTTP client