Refactor non-OTLP Format Mapping and Fix Dropped Attribute Count bug

Fixes open-telemetry#1656 The documents that describe transformations to Jaeger and Zipkin contained duplicate information about how to record InstrumentationLibrary. They also contained incomplete and incorrect information about how to record dropped attribute count. This change extracts common transformation rules into a separate document (non-otlp.md) and references this document where appropriate. We also define otel.event.dropped_attributes_count as the only way to record dropped attribute count, regardless of the entity for which it is recorded. Previously in Jaeger format we specified that for Events we must use otel.event.dropped_attributes_count and did not specify at all what to use for Spans. I believe using the same uniform key for Spans and Events is correct. I consider this a specification bug and do not believe it should be treated as a breaking change. Also delete the Zipkin mapping for LocalChildSpanCount since there is no such OpenTelemetry field anymore.
tigrannajaryan · Apr 29, 2021 · 6b42a87 · 6b42a87
1 parent a4b08e2
commit 6b42a87
Show file tree

Hide file tree

Showing 4 changed files with 68 additions and 35 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,7 @@ release.
 ### Traces
 
 - `Get Tracer` should use an empty string if the specified `name` is null. ([#1654](https://github.com/open-telemetry/opentelemetry-specification/pull/1654))
+- Clarify how to record dropped attribute count in non-OTLP formats. ([#]())
 
 ### Metrics
 

diff --git a/specification/trace/sdk_exporters/jaeger.md b/specification/trace/sdk_exporters/jaeger.md
@@ -3,6 +3,10 @@
 **Status**: [Stable](../../document-status.md)
 
 This document defines the transformation between OpenTelemetry and Jaeger Spans.
+The generic transformation [rules specified here](non-otlp.md) also apply. If a
+particular generic transformation rule and the rule in this document contradict
+then the rule in this document MUST be used.
+
 Jaeger accepts spans in two formats:
 
 * Thrift `Batch`, defined in [jaeger-idl/.../jaeger.thrift](https://github.com/jaegertracing/jaeger-idl/blob/master/thrift/jaeger.thrift), accepted via UDP or HTTP
@@ -23,14 +27,15 @@ and Jaeger.
 | Span.TraceId             | Span.traceIdLow/High | Span.trace_id | See [IDs](#ids)     |
 | Span.ParentId            | Span.parentSpanId | as SpanReference | See [Parent ID](#parent-id)     |
 | Span.SpanId              | Span.spanId       | Span.span_id     |      |
+| Span.TraceState          | TBD              |TBD               |       |
 | Span.Name                | Span.operationName | Span.operation_name |  |
 | Span.Kind                | Span.tags["span.kind"] | same | See [SpanKind](#spankind) for values mapping |
 | Span.StartTime           | Span.startTime | Span.start_time | See [Unit of time](#unit-of-time) |
 | Span.EndTime             | Span.duration | same | Calculated as EndTime - StartTime. See also [Unit of time](#unit-of-time) |
 | Span.Attributes          | Span.tags | same | See [Attributes](#attributes) for data types for the mapping.            |
 | Span.Events              | Span.logs | same | See [Events](#events) for the mapping format. |
 | Span.Links               | Span.references | same | See [Links](#links) |
-| Span.Status              | Add to Span.tags | same | See [Status](#status) for tag names to use. |
+| Span.Status              | Add to Span.tags | same | See [Status](non-otlp.md#span-status) for tag names to use. |
 
 ## Mappings
 
@@ -48,15 +53,6 @@ of the [`service` resource](../../resource/semantic_conventions/README.md#servic
 If no `service.name` is contained in a Span's Resource, that field MUST be populated from the
 [default](../../resource/sdk.md#sdk-provided-resource-attributes) `Resource`.
 
-### InstrumentationLibrary
-
-OpenTelemetry Span's `InstrumentationLibrary` MUST be reported as span `tags` to Jaeger using the following mapping.
-
-| OpenTelemetry | Jaeger |
-| ------------- | ------ |
-| `InstrumentationLibrary.name`|`otel.library.name`|
-| `InstrumentationLibrary.version`|`otel.library.version`|
-
 ### IDs
 
 Trace and span IDs in Jaeger are random sequences of bytes. However, Thrift model
@@ -118,18 +114,6 @@ In Jaeger Proto format the timestamps and durations MUST be represented
 with nanosecond precision using `google.protobuf.Timestamp` and
 `google.protobuf.Duration` types.
 
-### Status
-
-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` span tag MUST be added with the

diff --git a/specification/trace/sdk_exporters/non-otlp.md b/specification/trace/sdk_exporters/non-otlp.md
@@ -0,0 +1,54 @@
+# OpenTelemetry Transformation to non-OTLP Formats
+
+**Status**: [Stable](../../document-status.md)
+
+All OpenTelemetry concepts and span data recorded using OpenTelemetry API can be
+directly and precisely represented using corresponding messages and fields of
+OTLP format. However, for other formats this is not always the case. Sometimes a
+format will not have a native way to represent a particular OpenTelemetry
+concept or a field of a concept.
+
+This document defines the transformation between OpenTelemetry and formats other
+than OTLP, for OpenTelemetry fields and concepts that have no direct semantic
+equivalent in those other formats.
+
+Note: when a format has a direct semantic equivalent for a particular field or
+concept then the recommendation in this document MUST be ignored.
+
+See also additional specific transformation rules for [Jaeger](jaeger.md) and
+[Zipkin](zipkin.md). The specific rules for Jaeger and Zipkin take precedence
+over the generic rules defined in this document.
+
+## Mappings
+
+### InstrumentationLibrary
+
+OpenTelemetry `InstrumentationLibrary`'s fields MUST be reported as key-value
+pairs associated with the Span using the following mapping:
+
+| OpenTelemetry InstrumentationLibrary Field | non-OTLP Key |
+| ------------------- | --- |
+| `InstrumentationLibrary.name`|`otel.library.name`|
+| `InstrumentationLibrary.version`|`otel.library.version`|
+
+### Span Status
+
+Span `Status` MUST be reported as key-value pairs associated with the Span,
+unless the `Status` is `UNSET`. In the latter case it MUST NOT be reported.
+
+The following table defines the OpenTelemetry `Status`'s mapping to Span's
+key-value pairs:
+
+|OpenTelemetry Status Field|non-OTLP Key|non-OTLP 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. |
+
+### Dropped Attribute Count
+
+OpenTelemetry Span's dropped attribute count MUST be reported as a key-value
+pair associated with the Span. Similarly, Span Event's dropped attribute count
+MUST be reported as a key-value pair associated with the Span Event. In both
+cases the key name MUST be `otel.dropped_attribute_count`.
+
+This key-value pair should only be recorded when it contains a non-zero value.
diff --git a/specification/trace/sdk_exporters/zipkin.md b/specification/trace/sdk_exporters/zipkin.md
@@ -3,6 +3,10 @@
 **Status**: [Stable](../../document-status.md)
 
 This document defines the transformation between OpenTelemetry and Zipkin Spans.
+The generic transformation [rules specified here](non-otlp.md) also apply. If a
+particular generic transformation rule and the rule in this document contradict
+then the rule in this document MUST be used.
+
 Zipkin's v2 API is defined in the
 [zipkin.proto](https://github.com/openzipkin/zipkin-api/blob/master/zipkin.proto)
 
@@ -25,7 +29,6 @@ and Zipkin.
 | Span.Events              | Span.annotations | See [Events](#events) for the mapping format.                                                 |
 | Span.Links               | TBD              | TBD                                                                                           |
 | Span.Status              | Add to Span.tags | See [Status](#status) for tag names to use.                                                   |
-| Span.LocalChildSpanCount | TBD              | TBD                                                                                           |
 
 TBD : This is work in progress document and it is currently doesn't specify
 mapping for these fields:
@@ -35,9 +38,6 @@ OpenTelemetry fields:
 - Resource attributes
 - Tracestate
 - Links
-- LocalChildSpanCount
-- dropped attributes count
-- dropped events count
 - dropped links count
 
 Zipkin fields:
@@ -79,15 +79,6 @@ Zipkin.
 | `SpanKind.PRODUCER`|`SpanKind.PRODUCER` ||
 | `SpanKind.INTERNAL`|`null` |must be omitted (set to `null`)|
 
-### InstrumentationLibrary
-
-OpenTelemetry Span's `InstrumentationLibrary` MUST be reported as `tags` to Zipkin using the following mapping.
-
-| OpenTelemetry | Zipkin
-| ------------- | ------ |
-| `InstrumentationLibrary.name`|`otel.library.name`|
-| `InstrumentationLibrary.version`|`otel.library.version`|
-
 ### Remote endpoint
 
 #### OTLP -> Zipkin
@@ -137,6 +128,9 @@ TBD: add examples
 
 ### Status
 
+This section overrides the
+[generic Status mapping rule](non-otlp.md#span-status).
+
 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.