From d2839998cc20863e561db1aac51a1f350590ba35 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Mon, 23 Nov 2020 10:18:34 -0800 Subject: [PATCH 01/10] Added mapping of Error Status to error flag in Zipkin & Jaeger exporters. --- spec-compliance-matrix.md | 3 +++ specification/trace/sdk_exporters/jaeger.md | 16 +++++++++++++++- specification/trace/sdk_exporters/zipkin.md | 10 ++++++++-- 3 files changed, 26 insertions(+), 3 deletions(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index ca07fcb1b21..8c10f770103 100644 --- a/spec-compliance-matrix.md +++ b/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 | | | | | | | | | | + | |InstrumentationLibrary mapping | | | | | | | | | | + | +|Status mapping | | | | | | | | | | + | +|Error Status mapping | | | | | | | | | | + | |Events converted to Logs | | | | | | | | | | + | |OpenCensus| |TBD| diff --git a/specification/trace/sdk_exporters/jaeger.md b/specification/trace/sdk_exporters/jaeger.md index c3e7208a12b..8c071a7b674 100644 --- a/specification/trace/sdk_exporters/jaeger.md +++ b/specification/trace/sdk_exporters/jaeger.md @@ -40,7 +40,21 @@ 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`. | +|Message *(optional)* | `otel.status_description` | `{message}` | + +### Error flag + +When Span `Status` is set to `Error` an `error` tag SHOULD be added with the +`BOOL` value (`vBool`) set to `true`. The added `error` tag MAY override any +previous value. ### Events diff --git a/specification/trace/sdk_exporters/zipkin.md b/specification/trace/sdk_exporters/zipkin.md index 968809cff02..a8052d7ffc6 100644 --- a/specification/trace/sdk_exporters/zipkin.md +++ b/specification/trace/sdk_exporters/zipkin.md @@ -138,16 +138,22 @@ TBD: add examples ### Status -Span `Status` MUST be reported as a key-value pair in `tags` to Zipkin, unless it is `UNSET`. +Span `Status` MUST be reported as a key-value pair in `tags` to Zipkin, unless it is `Unset`. In the latter case it MUST NOT be reported. 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`. | +|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}` | +### Error flag + +When Span `Status` is set to `Error` an `error` tag SHOULD be added with the +string value `true` (eg. `{"error":"true"}`). The added `error` tag MAY override +any previous value. + ### Events OpenTelemetry `Event` has an optional `Attribute`(s) which is not supported by From 4d618e223c01e70b8f0c944194de89c4f1675db1 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Tue, 24 Nov 2020 09:53:50 -0800 Subject: [PATCH 02/10] Zipkin error flag is now an empty string. --- specification/trace/sdk_exporters/zipkin.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/trace/sdk_exporters/zipkin.md b/specification/trace/sdk_exporters/zipkin.md index a8052d7ffc6..d6ac3c6a30b 100644 --- a/specification/trace/sdk_exporters/zipkin.md +++ b/specification/trace/sdk_exporters/zipkin.md @@ -150,9 +150,9 @@ The following table defines the OpenTelemetry `Status` to Zipkin `tags` mapping. ### Error flag -When Span `Status` is set to `Error` an `error` tag SHOULD be added with the -string value `true` (eg. `{"error":"true"}`). The added `error` tag MAY override -any previous value. +When Span `Status` is set to `Error` an `error` tag SHOULD be added with an +empty string value (eg. `{"error":""}`). The added `error` tag MAY override any +previous value. ### Events From cd5c3c7702708fc4d79ccc6f22a2c74d4c6a6e9d Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Tue, 24 Nov 2020 10:13:00 -0800 Subject: [PATCH 03/10] Restored uppercase for status enum values. --- specification/trace/sdk_exporters/jaeger.md | 6 +++--- specification/trace/sdk_exporters/zipkin.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/trace/sdk_exporters/jaeger.md b/specification/trace/sdk_exporters/jaeger.md index 8c071a7b674..97b7966a067 100644 --- a/specification/trace/sdk_exporters/jaeger.md +++ b/specification/trace/sdk_exporters/jaeger.md @@ -40,19 +40,19 @@ TBD ### Status -Span `Status` MUST be reported as a key-value pair in `tags` to Jaeger, unless it is `Unset`. +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`. | +|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}` | ### Error flag -When Span `Status` is set to `Error` an `error` tag SHOULD be added with the +When Span `Status` is set to `ERROR` an `error` tag SHOULD be added with the `BOOL` value (`vBool`) set to `true`. The added `error` tag MAY override any previous value. diff --git a/specification/trace/sdk_exporters/zipkin.md b/specification/trace/sdk_exporters/zipkin.md index d6ac3c6a30b..bd243f842e6 100644 --- a/specification/trace/sdk_exporters/zipkin.md +++ b/specification/trace/sdk_exporters/zipkin.md @@ -138,19 +138,19 @@ TBD: add examples ### Status -Span `Status` MUST be reported as a key-value pair in `tags` to Zipkin, unless it is `Unset`. +Span `Status` MUST be reported as a key-value pair in `tags` to Zipkin, unless it is `UNSET`. In the latter case it MUST NOT be reported. 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`. | +|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}` | ### Error flag -When Span `Status` is set to `Error` an `error` tag SHOULD be added with an +When Span `Status` is set to `ERROR` an `error` tag SHOULD be added with an empty string value (eg. `{"error":""}`). The added `error` tag MAY override any previous value. From 1fba8f2748555003a509763bed10909d9c922465 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Tue, 24 Nov 2020 19:41:11 -0800 Subject: [PATCH 04/10] Removed the error text under attributes. --- specification/trace/sdk_exporters/zipkin.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/specification/trace/sdk_exporters/zipkin.md b/specification/trace/sdk_exporters/zipkin.md index bd243f842e6..bc42c7f3040 100644 --- a/specification/trace/sdk_exporters/zipkin.md +++ b/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). From f3d41767b57bdcf4469cb1b6c3941e343554f34a Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Tue, 24 Nov 2020 19:44:02 -0800 Subject: [PATCH 05/10] Casing fix. --- specification/trace/sdk_exporters/zipkin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/sdk_exporters/zipkin.md b/specification/trace/sdk_exporters/zipkin.md index bc42c7f3040..17c99be639c 100644 --- a/specification/trace/sdk_exporters/zipkin.md +++ b/specification/trace/sdk_exporters/zipkin.md @@ -127,7 +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"`. +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). From b62b65182d8eb64dbec89ccd5283e4477ef5ecf5 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Thu, 3 Dec 2020 12:56:45 -0800 Subject: [PATCH 06/10] Review feedback. --- specification/trace/api.md | 10 ++++++---- specification/trace/sdk_exporters/jaeger.md | 2 +- specification/trace/sdk_exporters/zipkin.md | 8 +------- 3 files changed, 8 insertions(+), 12 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 14fc9b7ad2e..80e3ee64a29 100644 --- a/specification/trace/api.md +++ b/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: diff --git a/specification/trace/sdk_exporters/jaeger.md b/specification/trace/sdk_exporters/jaeger.md index 97b7966a067..3b32664d089 100644 --- a/specification/trace/sdk_exporters/jaeger.md +++ b/specification/trace/sdk_exporters/jaeger.md @@ -48,7 +48,7 @@ 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`. | -|Message *(optional)* | `otel.status_description` | `{message}` | +|Description | `otel.status_description` | Description of the `Status` if it has a value otherwise not set. | ### Error flag diff --git a/specification/trace/sdk_exporters/zipkin.md b/specification/trace/sdk_exporters/zipkin.md index 17c99be639c..9cb23d7d936 100644 --- a/specification/trace/sdk_exporters/zipkin.md +++ b/specification/trace/sdk_exporters/zipkin.md @@ -144,13 +144,7 @@ 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}` | - -### Error flag - -When Span `Status` is set to `ERROR` an `error` tag SHOULD be added with an -empty string value (eg. `{"error":""}`). The added `error` tag MAY override any -previous value. +|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. | ### Events From 8534795044538c3822f7146c43b3b51206900327 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Thu, 3 Dec 2020 16:22:46 -0800 Subject: [PATCH 07/10] Added back information about removing error flag when false. --- specification/trace/sdk_exporters/zipkin.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/specification/trace/sdk_exporters/zipkin.md b/specification/trace/sdk_exporters/zipkin.md index 9cb23d7d936..01fca7f1c7a 100644 --- a/specification/trace/sdk_exporters/zipkin.md +++ b/specification/trace/sdk_exporters/zipkin.md @@ -146,6 +146,10 @@ The following table defines the OpenTelemetry `Status` to Zipkin `tags` mapping. |Code | `otel.status_code` | Name of the code, either `OK` or `ERROR`. MUST NOT be set if the code is `UNSET`. | |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 OpenTelemetry `Event` has an optional `Attribute`(s) which is not supported by From 91f9c1fb288040f5bc9064491486262c3003b1cc Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Mon, 7 Dec 2020 10:04:34 -0800 Subject: [PATCH 08/10] Updated CHANGELOG. --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 593cf4e49bf..b55bc7e292a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,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) From 70fd80842bd9aea652fb8ad8430b500997778bbc Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Tue, 8 Dec 2020 22:36:28 -0800 Subject: [PATCH 09/10] Update specification/trace/sdk_exporters/jaeger.md Co-authored-by: Yuri Shkuro --- specification/trace/sdk_exporters/jaeger.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/sdk_exporters/jaeger.md b/specification/trace/sdk_exporters/jaeger.md index 3b32664d089..38b071b09bc 100644 --- a/specification/trace/sdk_exporters/jaeger.md +++ b/specification/trace/sdk_exporters/jaeger.md @@ -53,7 +53,7 @@ The following table defines the OpenTelemetry `Status` to Jaeger `tags` mapping. ### Error flag When Span `Status` is set to `ERROR` an `error` tag SHOULD be added with the -`BOOL` value (`vBool`) set to `true`. The added `error` tag MAY override any +Boolean value of `true`. The added `error` tag MAY override any previous value. ### Events From 2891d74e250152176111c97c2580e8706332833d Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Thu, 10 Dec 2020 11:24:30 -0800 Subject: [PATCH 10/10] Review feedback. --- specification/trace/sdk_exporters/jaeger.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/specification/trace/sdk_exporters/jaeger.md b/specification/trace/sdk_exporters/jaeger.md index 38b071b09bc..2ad1eb329c7 100644 --- a/specification/trace/sdk_exporters/jaeger.md +++ b/specification/trace/sdk_exporters/jaeger.md @@ -52,9 +52,8 @@ The following table defines the OpenTelemetry `Status` to Jaeger `tags` mapping. ### Error flag -When Span `Status` is set to `ERROR` an `error` tag SHOULD be added with the -Boolean value of `true`. The added `error` tag MAY override any -previous value. +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