diff --git a/specification/trace/api.md b/specification/trace/api.md index ee44740154e..d5658197c34 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -549,6 +549,10 @@ status, which is `Unset`. - `Error` - The operation contains an error. +These values form a total order: `Ok > Error > Unset`. +This means that setting `Status` with `StatusCode=Ok` will override any prior or future attempts to set +span `Status` with `StatusCode=Error` or `StatusCode=Unset`. See below for more specific rules. + The Span interface MUST provide: - An API to set the `Status`. This SHOULD be called `SetStatus`. This API takes @@ -559,6 +563,8 @@ The Span interface MUST provide: The status code SHOULD remain unset, except for the following circumstances: +An attempt to set value `Unset` SHOULD be ignored. + 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 @@ -571,6 +577,9 @@ status code as `Unset` unless there is an error, as described above. Application developers and Operators may set the status code to `Ok`. +When span status is set to `Ok` it SHOULD be considered final and any further +attempts to change it SHOULD be ignored. + 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.