diff --git a/CHANGELOG.md b/CHANGELOG.md index 18158bcbb9c..baf9452a0f6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,8 @@ release. New: +- Change Status to be consistent with Link and Event + ([#1067](/~https://github.com/open-telemetry/opentelemetry-specification/pull/1067)) - Clarify env variables in otlp exporter ([#975](/~https://github.com/open-telemetry/opentelemetry-specification/pull/975)) - Add Prometheus exporter environment variables diff --git a/specification/trace/api.md b/specification/trace/api.md index 061c5678c03..8567b0ff130 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -33,11 +33,6 @@ Table of Contents * [Record Exception](#record-exception) * [Span lifetime](#span-lifetime) * [Propagated Span creation](#propagated-span-creation) -* [Status](#status) - * [StatusCanonicalCode](#statuscanonicalcode) - * [Status creation](#status-creation) - * [GetCanonicalCode](#getcanonicalcode) - * [GetDescription](#getdescription) * [SpanKind](#spankind) * [Concurrency](#concurrency) * [Included Propagators](#included-propagators) @@ -496,16 +491,50 @@ Note that [`RecordException`](#record-exception) is a specialized variant of #### Set Status -Sets the [`Status`](#status) of the `Span`. If used, this will override the -default `Span` status, which is `OK`. +Sets the `Status` of the `Span`. If used, this will override the default `Span` +status, which is `Unset`. -Only the value of the last call will be recorded, and implementations are free -to ignore previous calls. +`Status` is semantically defined by the following properties: + +- `StatusCanonicalCode` that represents the canonical set of `Status` codes. +- Optional `Description` that provides a descriptive message of the `Status`. + +`StatusCanonicalCode` has the following values: + +- `Unset` + - The default status. +- `Ok` + - The operation has been validated by an Application developer or Operator to + have completed successfully. +- `Error` + - The operation contains an error. The Span interface MUST provide: -- An API to set the `Status` where the new status is the only argument. This - SHOULD be called `SetStatus`. +- An API to set the `Status`. This SHOULD be called `SetStatus`. + This API takes the `StatusCanonicalCode`, and optional `Description`, + either as individual parameters or as an immutable object encapsulating them, + whichever is most appropriate for the language. + +The status code SHOULD remain unset, except for the following circumstances: + +When the status is set to `ERROR` by Instrumentation Libraries, the status codes +SHOULD be documented and predictable. The status code should only be set to `ERROR` +according to the rules defined within the semantic conventions. For operations +not covered by the semantic conventions, Instrumentation Libraries SHOULD +publish their own conventions, including status codes. + +Generally, Instrumentation Libraries SHOULD NOT set the status code to `Ok`, +unless explicitly configured to do so. Instrumention libraries SHOULD leave the +status code as `Unset` unless there is an error, as described above. + +Application developers and Operators may set the status code to `Ok`. + +Analysis tools SHOULD respond to an `Ok` status by suppressing any errors they +would otherwise generate. For example, to suppress noisy errors such as 404s. + +Only the value of the last call will be recorded, and implementations are free +to ignore previous calls. #### UpdateName @@ -594,62 +623,6 @@ The remaining functionality of `Span` MUST be defined as no-op operations. This functionality MUST be fully implemented in the API, and SHOULD NOT be overridable. -## Status - -`Status` interface represents the status of a finished `Span`. It's composed of -a canonical code, and an optional descriptive message. - -### StatusCanonicalCode - -`StatusCanonicalCode` represents the canonical set of status codes of a finished -`Span`. - -- `Unset` - - The default status. -- `Error` - - The operation contains an error. -- `Ok` - - The operation has been validated by an Application developers or Operator to - have completed successfully, or contain - -The status code SHOULD remain unset, except for the following circumstances: - -When the status is set to `ERROR` by Instrumentation Libraries, the status codes -SHOULD be documented and predictable. The status code should only be set to `ERROR` -according to the rules defined within the semantic conventions. For operations -not covered by the semantic conventions, Instrumentation Libraries SHOULD -publish their own conventions, including status codes. - -Generally, Instrumentation Libraries SHOULD NOT set the status code to `Ok`, -unless explicitly configured to do so. Instrumention libraries SHOULD leave the -status code as `Unset` unless there is an error, as described above. - -Application developers and Operators may set the status code to `Ok`. - -Analysis tools SHOULD respond to an `Ok` status by suppressing any errors they -would otherwise generate. For example, to suppress noisy errors such as 404s. - -### Status creation - -API MUST provide a way to create a new `Status`. - -Required parameters - -- `StatusCanonicalCode` of this `Status`. - -Optional parameters - -- Description of this `Status`. - -### GetCanonicalCode - -Returns the `StatusCanonicalCode` of this `Status`. - -### GetDescription - -Returns the description of this `Status`. -Languages should follow their usual conventions on whether to return `null` or an empty string here if no description was given. - ## SpanKind `SpanKind` describes the relationship between the Span, its parents, diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 4561826caf4..74564559397 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -37,7 +37,7 @@ default span name. ## Status -[Span Status](../api.md#status) MUST be left unset if HTTP status code was in the +[Span Status](../api.md#set-status) MUST be left unset if HTTP status code was in the 1xx, 2xx or 3xx ranges, unless there was another error (e.g., network error receiving the response body; or 3xx codes with max redirects exceeded), in which case status MUST be set to `Error`.