Change Status to be consistent with Link and Event (open-telemetry#1067)

* Change Status to be consistent with Link and Event

Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>

* Add changelog entry

Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>

* Fix link to status

Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>

* Update specification/trace/api.md

Co-authored-by: Yuri Shkuro <yurishkuro@users.noreply.github.com>

* Update specification/trace/api.md

Co-authored-by: Yuri Shkuro <yurishkuro@users.noreply.github.com>

* Fix markdown errors

Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>

* Update specification/trace/api.md

Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>

Co-authored-by: Yuri Shkuro <yurishkuro@users.noreply.github.com>
Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>

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

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,

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`.