Map Error Status to error tag in Zipkin & Jaeger (open-telemetry#1257)

* Added mapping of Error Status to error flag in Zipkin & Jaeger exporters.

* Zipkin error flag is now an empty string.

* Restored uppercase for status enum values.

* Removed the error text under attributes.

* Casing fix.

* Review feedback.

* Added back information about removing error flag when false.

* Updated CHANGELOG.

* Update specification/trace/sdk_exporters/jaeger.md

Co-authored-by: Yuri Shkuro <[email protected]>

* Review feedback.

Co-authored-by: Cijo Thomas <[email protected]>
Co-authored-by: Yuri Shkuro <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -17,6 +17,10 @@ Updates:
   ([#1219](https://github.com/open-telemetry/opentelemetry-specification/pull/1219))
 - Add RPC semantic conventions for metrics
   ([#1162](https://github.com/open-telemetry/opentelemetry-specification/pull/1162))
+- Clarify `Description` usage on `Status` API
+  ([#1257](https://github.com/open-telemetry/opentelemetry-specification/pull/1257))
+- Add/Update `Status` + `error` mapping for Jaeger & Zipkin Exporters
+  ([#1257](https://github.com/open-telemetry/opentelemetry-specification/pull/1257))
 
 ## v0.7.0 (11-18-2020)
 

spec-compliance-matrix.md

@@ -158,6 +158,7 @@ status of the feature is not known.
 |Boolean attributes                            | + | +  | + | +    |    | +    | + | +  |   | +  |
 |Array attributes                              | + | +  | + | [-](https://github.com/open-telemetry/opentelemetry-python/issues/1110)    |    | +    | + | +  |   | +  |
 |Status mapping                                | + | +  | + | +    |    | +    | + | +  |   | +  |
+|Error Status mapping                          |   |    |   |      |    |      |   |    |   | +  |
 |Event attributes mapping to Annotations       | + | +  | + | +    |    | +    | + | +  |   | +  |
 |Integer microseconds in timestamps            |   | +  |   | +    |    |      |   |    |   | +  |
 |[Jaeger](specification/trace/sdk_exporters/jaeger.md)|
@@ -167,6 +168,8 @@ status of the feature is not known.
 |Service name mapping                          |   |    |   | +    |    |      |   |    |   | +  |
 |Resource to Process mapping                   |   |    |   | [-](https://github.com/open-telemetry/opentelemetry-python/issues/1436)    |    |      |   |    |   | +  |
 |InstrumentationLibrary mapping                |   |    |   | +    |    |      |   |    |   | +  |
+|Status mapping                                |   |    |   |      |    |      |   |    |   | +  |
+|Error Status mapping                          |   |    |   |      |    |      |   |    |   | +  |
 |Events converted to Logs                      |   |    |   | +    |    |      |   |    |   | +  |
 |OpenCensus|
 |TBD|

specification/trace/api.md

@@ -516,6 +516,7 @@ status, which is `Unset`.
 
 - `StatusCode`, one of the values listed below.
 - Optional `Description` that provides a descriptive message of the `Status`.
+  `Description` MUST only be used with the `Error` `StatusCode` value.
 
 `StatusCode` is one of the following values:
 
@@ -529,10 +530,11 @@ status, which is `Unset`.
 
 The Span interface MUST provide:
 
-- An API to set the `Status`. This SHOULD be called `SetStatus`.
-  This API takes the `StatusCode`, and an optional `Description`, either as
-  individual parameters or as an immutable object encapsulating them, whichever
-  is most appropriate for the language.
+- An API to set the `Status`. This SHOULD be called `SetStatus`. This API takes
+  the `StatusCode`, and an optional `Description`, either as individual
+  parameters or as an immutable object encapsulating them, whichever is most
+  appropriate for the language. `Description` MUST be IGNORED for `StatusCode`
+  `Ok` & `Unset` values.
 
 The status code SHOULD remain unset, except for the following circumstances:
 

specification/trace/sdk_exporters/jaeger.md

@@ -40,7 +40,20 @@ TBD
 
 ### Status
 
-TBD
+Span `Status` MUST be reported as a key-value pair in `tags` to Jaeger, unless it is `UNSET`.
+In the latter case it MUST NOT be reported.
+
+The following table defines the OpenTelemetry `Status` to Jaeger `tags` mapping.
+
+| Status|Tag Key| Tag Value |
+|--|--|--|
+|Code | `otel.status_code` | Name of the code, either `OK` or `ERROR`. MUST NOT be set if the code is `UNSET`. |
+|Description | `otel.status_description` | Description of the `Status` if it has a value otherwise not set. |
+
+### Error flag
+
+When Span `Status` is set to `ERROR` an `error` tag MUST be added with the
+Boolean value of `true`. The added `error` tag MAY override any previous value.
 
 ### Events
 

specification/trace/sdk_exporters/zipkin.md

@@ -127,9 +127,7 @@ convention](../semantic_conventions/README.md)
 document maps to the strongly-typed fields of Zipkin spans.
 
 Primitive types MUST be converted to string using en-US culture settings.
-Boolean values must use lower case strings `"true"` and `"false"`, except an
-attribute named `error`. In case if value of the attribute is `false`, Zipkin
-tag needs to be omitted.
+Boolean values MUST use lower case strings `"true"` and `"false"`.
 
 Array values MUST be serialized to string like a JSON list as mentioned in
 [semantic conventions](../../overview.md#semantic-conventions).
@@ -146,7 +144,11 @@ The following table defines the OpenTelemetry `Status` to Zipkin `tags` mapping.
 | Status|Tag Key| Tag Value |
 |--|--|--|
 |Code | `otel.status_code` | Name of the code, either `OK` or `ERROR`. MUST NOT be set if the code is `UNSET`. |
-|Message *(optional)* | `otel.status_description` | `{message}` |
+|Description| `error` | Description of the `Status`. MUST be set if the code is `ERROR`, use an empty string if Description has no value. MUST NOT be set for `OK` and `UNSET` codes. |
+
+Note: The `error` tag should only be set if `Status` is `Error`. If a boolean
+version (`{"error":false}` or `{"error":"false"}`) is present, it SHOULD be
+removed. Zipkin will treat any span with `error` sent as failed.
 
 ### Events