From 131bc6bf0d7db3f8e278374ffd9e03c2e74cb5dd Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Thu, 29 Apr 2021 12:27:34 -0400 Subject: [PATCH] Refactor non-OTLP Format Mapping and Fix Dropped Attribute Count bug Fixes https://github.com/open-telemetry/opentelemetry-specification/issues/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. --- CHANGELOG.md | 1 + specification/trace/sdk_exporters/jaeger.md | 28 +++------- specification/trace/sdk_exporters/non-otlp.md | 54 +++++++++++++++++++ specification/trace/sdk_exporters/zipkin.md | 20 +++---- 4 files changed, 68 insertions(+), 35 deletions(-) create mode 100644 specification/trace/sdk_exporters/non-otlp.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 9f47c33c857..d2e8a2b05c4 100644 --- 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. ([#1662](https://github.com/open-telemetry/opentelemetry-specification/pull/1662)) ### Metrics diff --git a/specification/trace/sdk_exporters/jaeger.md b/specification/trace/sdk_exporters/jaeger.md index d80d035d237..dd92500add0 100644 --- 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,6 +27,7 @@ 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) | @@ -30,7 +35,7 @@ and Jaeger. | 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 new file mode 100644 index 00000000000..31d67f9fbe3 --- /dev/null +++ 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 index a8ef3555647..4eb78796d57 100644 --- 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.