From 5b71287c6e4da75db0e52880d431dbf686e6e179 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 | 33 ++++------ specification/trace/sdk_exporters/non-otlp.md | 61 +++++++++++++++++++ specification/trace/sdk_exporters/zipkin.md | 28 ++++----- 4 files changed, 85 insertions(+), 38 deletions(-) create mode 100644 specification/trace/sdk_exporters/non-otlp.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 62ad051feef..f465e836eba 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..8a81ff672b4 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,12 +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.DroppedAttributesCount| Add to Span.tags | same | See [Dropped Attributes Count](non-otlp.md#dropped-attributes-count) for tag name to use. | | Span.Events | Span.logs | same | See [Events](#events) for the mapping format. | +| Span.DroppedEventsCount | Add to Span.tags | same | See [Dropped Events Count](non-otlp.md#dropped-events-count) for tag name to use. | | Span.Links | Span.references | same | See [Links](#links) | | Span.Status | Add to Span.tags | same | See [Status](#status) for tag names to use. | @@ -48,15 +55,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 @@ -120,17 +118,10 @@ with nanosecond precision using `google.protobuf.Timestamp` and ### 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. | +The Status is recorded as Span tags. See [Status](non-otlp.md#span-status) for +tag names to use. -### Error flag +#### Error flag When Span `Status` is set to `ERROR`, an `error` span tag MUST be added with the Boolean value of `true`. The added `error` tag MAY override any previous value. @@ -160,12 +151,10 @@ generated from [Parent ID](#parent-id), if any. ### Events -Events MUST be converted to Jaeger Logs. OpenTelemetry Event's `time_unix_nano` and `attributes` fields map directly to Jaeger Log's `timestamp` and `fields` fields. Jaeger Log has no direct equivalent for OpenTelemetry Event's `name` and `dropped_attributes_count` fields but OpenTracing semantic conventions specify some special attribute names [here](https://github.com/opentracing/specification/blob/master/semantic_conventions.md#log-fields-table). OpenTelemetry Event's `name` and `dropped_attributes_count` fields should be added to Jaeger Log's `fields` map as follows: +Events MUST be converted to Jaeger Logs. OpenTelemetry Event's `time_unix_nano` and `attributes` fields map directly to Jaeger Log's `timestamp` and `fields` fields. Jaeger Log has no direct equivalent for OpenTelemetry Event's `name` field but OpenTracing semantic conventions specify some special attribute names [here](https://github.com/opentracing/specification/blob/master/semantic_conventions.md#log-fields-table). OpenTelemetry Event's `name` field should be added to Jaeger Log's `fields` map as follows: | OpenTelemetry Event Field | Jaeger Attribute | | -------------------------- | ----------------- | | `name`|`event`| -| `dropped_attributes_count`|`otel.event.dropped_attributes_count`| -* `dropped_attributes_count` should only be recorded when it contains a non-zero value. * If OpenTelemetry Event contains an attributes with the key `event`, it should take precedence over Event's `name` field. diff --git a/specification/trace/sdk_exporters/non-otlp.md b/specification/trace/sdk_exporters/non-otlp.md new file mode 100644 index 00000000000..41d83acf443 --- /dev/null +++ b/specification/trace/sdk_exporters/non-otlp.md @@ -0,0 +1,61 @@ +# 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 Attributes Count + +OpenTelemetry Span's dropped attributes count MUST be reported as a key-value +pair associated with the Span. Similarly, Span Event's dropped attributes count +MUST be reported as a key-value pair associated with the Span Event. In both +cases the key name MUST be `otel.dropped_attributes_count`. + +This key-value pair should only be recorded when it contains a non-zero value. + +### Dropped Events Count + +OpenTelemetry Span's dropped events count MUST be reported as a key-value pair +associated with the Span. The key name MUST be `otel.dropped_events_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..f70fdf3b084 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) @@ -13,19 +17,20 @@ and Zipkin. | OpenTelemetry | Zipkin | Notes | | ------------------------ | ---------------- | --------------------------------------------------------------------------------------------- | -| Span.TraceId | Span.trace_id | | -| Span.ParentId | Span.parent_id | | +| Span.TraceId | Span.trace_id | | +| Span.ParentId | Span.parent_id | | | Span.SpanId | Span.id | | | Span.TraceState | TBD | TBD | | Span.Name | Span.name | | | Span.Kind | Span.kind | See [SpanKind](#spankind) for values mapping | | Span.StartTime | Span.timestamp | See [Unit of time](#unit-of-time) | | Span.EndTime | Span.duration | Duration is calculated based on StartTime and EndTime. See also [Unit of time](#unit-of-time) | -| Span.Attributes | Span.tags | See [Attributes](../../common/common.md#attributes) for data types for the mapping. | +| Span.Attributes | Span.tags | See [Attributes](../../common/common.md#attributes) for data types for the mapping. | +| Span.DroppedAttributesCount| Span.tags | See [Dropped Attributes Count](non-otlp.md#dropped-attributes-count) for tag name to use. | | Span.Events | Span.annotations | See [Events](#events) for the mapping format. | +| Span.DroppedEventsCount | Span.tags | See [Dropped Events Count](non-otlp.md#dropped-events-count) for tag name to use. | | 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 +40,6 @@ OpenTelemetry fields: - Resource attributes - Tracestate - Links -- LocalChildSpanCount -- dropped attributes count -- dropped events count - dropped links count Zipkin fields: @@ -79,15 +81,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 +130,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.