Error Flagging with Status Codes (#966)

* StatusSource definition

* Update HTTP status code mapping

* Remove span status

* Apply feedback.

* Remove unused link.

* markdownlint

* spelling

Co-authored-by: Carlos Alberto Cortez <calberto.cortez@gmail.com>

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,

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
 
 <!-- semconv http -->