Skip to content

Commit

Permalink
Refactor non-OTLP Format Mapping and Fix Dropped Attribute Count bug
Browse files Browse the repository at this point in the history 
Fixes #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.
  • Loading branch information
@tigrannajaryan
tigrannajaryan committed Apr 30, 2021
1 parent 2a712f7 commit 5b71287
Show file tree
Hide file tree
Showing 4 changed files with 85 additions and 38 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
33 changes: 11 additions & 22 deletions specification/trace/sdk_exporters/jaeger.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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. |

Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
61 changes: 61 additions & 0 deletions specification/trace/sdk_exporters/non-otlp.md
View file
Original file line number Diff line number Diff line change
@@ -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.
28 changes: 12 additions & 16 deletions specification/trace/sdk_exporters/zipkin.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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:
Expand All @@ -35,9 +40,6 @@ OpenTelemetry fields:
- Resource attributes
- Tracestate
- Links
- LocalChildSpanCount
- dropped attributes count
- dropped events count
- dropped links count

Zipkin fields:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand Down

0 comments on commit 5b71287

Please sign in to comment.