diff --git a/specification/trace/api.md b/specification/trace/api.md index 35b4f3706e7..b7816e3920c 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -37,7 +37,6 @@ Table of Contents * [Status creation](#status-creation) * [GetCanonicalCode](#getcanonicalcode) * [GetDescription](#getdescription) - * [GetIsOk](#getisok) * [SpanKind](#spankind) * [Concurrency](#concurrency) * [Included Propagators](#included-propagators) @@ -581,61 +580,37 @@ calling of corresponding API. ## Status `Status` interface represents the status of a finished `Span`. It's composed of -a canonical code in conjunction with an optional descriptive message. +a canonical code, and an optional descriptive message. ### StatusCanonicalCode `StatusCanonicalCode` represents the canonical set of status codes of a finished -`Span`, following the [Standard GRPC -codes](https://github.com/grpc/grpc/blob/master/doc/statuscodes.md): +`Span`. +- `Unset` + - The default status. +- `Error` + - The operation contains an error. - `Ok` - - The operation completed successfully. -- `Cancelled` - - The operation was cancelled (typically by the caller). -- `Unknown` - - An unknown error. -- `InvalidArgument` - - Client specified an invalid argument. Note that this differs from - `FailedPrecondition`. `InvalidArgument` indicates arguments that are problematic - regardless of the state of the system. -- `DeadlineExceeded` - - Deadline expired before operation could complete. For operations that change the - state of the system, this error may be returned even if the operation has - completed successfully. -- `NotFound` - - Some requested entity (e.g., file or directory) was not found. -- `AlreadyExists` - - Some entity that we attempted to create (e.g., file or directory) already exists. -- `PermissionDenied` - - The caller does not have permission to execute the specified operation. - `PermissionDenied` must not be used if the caller cannot be identified (use - `Unauthenticated1` instead for those errors). -- `ResourceExhausted` - - Some resource has been exhausted, perhaps a per-user quota, or perhaps the - entire file system is out of space. -- `FailedPrecondition` - - Operation was rejected because the system is not in a state required for the - operation's execution. -- `Aborted` - - The operation was aborted, typically due to a concurrency issue like sequencer - check failures, transaction aborts, etc. -- `OutOfRange` - - Operation was attempted past the valid range. E.g., seeking or reading past end - of file. Unlike `InvalidArgument`, this error indicates a problem that may be - fixed if the system state changes. -- `Unimplemented` - - Operation is not implemented or not supported/enabled in this service. -- `Internal` - - Internal errors. Means some invariants expected by underlying system has been - broken. -- `Unavailable` - - The service is currently unavailable. This is a most likely a transient - condition and may be corrected by retrying with a backoff. -- `DataLoss` - - Unrecoverable data loss or corruption. -- `Unauthenticated` - - The request does not have valid authentication credentials for the operation. + - 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 @@ -658,10 +633,6 @@ Returns the `StatusCanonicalCode` of this `Status`. 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. -### GetIsOk - -Returns true if the canonical code of this `Status` is `Ok`, otherwise false. - ## 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 e6bf97ad660..4561826caf4 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -37,37 +37,16 @@ default span name. ## Status -Implementations MUST set the [span status](../api.md#status) if the HTTP communication failed -or an HTTP error status code is returned (e.g. above 3xx). +[Span Status](../api.md#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`. -In the case of an HTTP redirect, the request should normally be considered successful, -unless the client aborts following redirects due to hitting some limit (redirect loop). -If following a (chain of) redirect(s) successfully, the status should be set according to the result of the final HTTP request. +For HTTP status codes in the 4xx and 5xx ranges, as well as any other code the client +failed to interpret, status MUST be set to `Error`. Don't set the span status description if the reason can be inferred from `http.status_code`. -| HTTP code | Span status code | -|-------------------------|-----------------------| -| 100...299 | `Ok` | -| 3xx redirect codes | `DeadlineExceeded` in case of loop (see above) [1], otherwise `Ok` | -| 401 Unauthorized ⚠ | `Unauthenticated` ⚠ (Unauthorized actually means unauthenticated according to [RFC 7235][rfc-unauthorized]) | -| 403 Forbidden | `PermissionDenied` | -| 404 Not Found | `NotFound` | -| 429 Too Many Requests | `ResourceExhausted` | -| 499 Client Closed | `Cancelled` (Not an official HTTP status code, defined by [NGINX][nginx-http-499]) | -| Other 4xx code | `InvalidArgument` [1] | -| 501 Not Implemented | `Unimplemented` | -| 503 Service Unavailable | `Unavailable` | -| 504 Gateway Timeout | `DeadlineExceeded` | -| Other 5xx code | `Internal` [1] | -| Any status code the client fails to interpret (e.g., 093 or 573) | `Unknown` | - -Note that the items marked with [1] are different from the mapping defined in the [OpenCensus semantic conventions][oc-http-status]. - -[oc-http-status]: https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/HTTP.md#mapping-from-http-status-codes-to-trace-status-codes -[rfc-unauthorized]: https://tools.ietf.org/html/rfc7235#section-3.1 -[nginx-http-499]: https://httpstatuses.com/499 - ## Common Attributes