diff --git a/specification/trace/sdk_exporters/non-otlp.md b/specification/common/mapping-to-non-otlp.md similarity index 75% rename from specification/trace/sdk_exporters/non-otlp.md rename to specification/common/mapping-to-non-otlp.md index bdfc9810171..cb80f685ca7 100644 --- a/specification/trace/sdk_exporters/non-otlp.md +++ b/specification/common/mapping-to-non-otlp.md @@ -1,8 +1,8 @@ # OpenTelemetry Transformation to non-OTLP Formats -**Status**: [Stable](../../document-status.md) +**Status**: [Stable](../document-status.md) -All OpenTelemetry concepts and span data recorded using OpenTelemetry API can be +All OpenTelemetry concepts and 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 @@ -15,16 +15,17 @@ 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. +See also additional specific transformation rules for +[Jaeger](../trace/sdk_exporters/jaeger.md) and [Zipkin](../trace/sdk_exporters/zipkin.md). +The specific rules for Jaeger and Zipkin take precedence over the generic rules defined +in this document. ## Mappings ### InstrumentationScope OpenTelemetry `InstrumentationScope`'s fields MUST be reported as key-value -pairs associated with the Span using the following mapping: +pairs associated with the Span, Metric Data Point or LogRecord using the following mapping: | OpenTelemetry InstrumentationScope Field | non-OTLP Key | Notes | | ------------------- | --- | --- | @@ -54,11 +55,9 @@ key-value pairs: ### 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 and Span Link's -dropped attributes count MUST be reported as a key-value pair associated with the -Span Link. In all cases the key name MUST be `otel.dropped_attributes_count`. +OpenTelemetry dropped attributes count MUST be reported as a key-value +pair associated with the corresponding data entity (e.g. Span, Span Link, Span Event, +Metric data point, LogRecord, etc). The key name MUST be `otel.dropped_attributes_count`. This key-value pair should only be recorded when it contains a non-zero value. diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 9e9efa771cc..a1970c90743 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -131,7 +131,7 @@ Thus, the SDK specification defines sets of possible requirements for others might have an explicit `hasEnded` boolean). Counts for attributes, events and links dropped due to collection limits MUST be - available for exporters to report as described in the [exporters](./sdk_exporters/non-otlp.md#dropped-attributes-count) + available for exporters to report as described in the [exporters](../common/mapping-to-non-otlp.md#dropped-attributes-count) specification. A function receiving this as argument might not be able to modify the Span. diff --git a/specification/trace/sdk_exporters/jaeger.md b/specification/trace/sdk_exporters/jaeger.md index acfb95752c5..629adbb011e 100644 --- a/specification/trace/sdk_exporters/jaeger.md +++ b/specification/trace/sdk_exporters/jaeger.md @@ -3,7 +3,7 @@ **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 +The generic transformation [rules specified here](../../common/mapping-to-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. @@ -33,11 +33,11 @@ and Jaeger. | 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.DroppedAttributesCount| Add to Span.tags | same | See [Dropped Attributes Count](../../common/mapping-to-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.DroppedEventsCount | Add to Span.tags | same | See [Dropped Events Count](../../common/mapping-to-non-otlp.md#dropped-events-count) for tag name to use. | | Span.Links | Span.references | same | See [Links](#links) | -| Span.DroppedLinksCount | Add to Span.tags | same | See [Dropped Links Count](non-otlp.md#dropped-links-count) for tag name to use. | +| Span.DroppedLinksCount | Add to Span.tags | same | See [Dropped Links Count](../../common/mapping-to-non-otlp.md#dropped-links-count) for tag name to use. | | Span.Status | Add to Span.tags | same | See [Status](#status) for tag names to use. | ## Mappings @@ -119,7 +119,7 @@ with nanosecond precision using `google.protobuf.Timestamp` and ### Status -The Status is recorded as Span tags. See [Status](non-otlp.md#span-status) for +The Status is recorded as Span tags. See [Status](../../common/mapping-to-non-otlp.md#span-status) for tag names to use. #### Error flag diff --git a/specification/trace/sdk_exporters/zipkin.md b/specification/trace/sdk_exporters/zipkin.md index 34cc36aa2b5..b398c1efa31 100644 --- a/specification/trace/sdk_exporters/zipkin.md +++ b/specification/trace/sdk_exporters/zipkin.md @@ -3,7 +3,7 @@ **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 +The generic transformation [rules specified here](../../common/mapping-to-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. @@ -26,11 +26,11 @@ and Zipkin. | 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 | Add to Span.tags | See [Attributes](../../common/README.md#attribute) for data types for the mapping. | -| Span.DroppedAttributesCount| Add to Span.tags | See [Dropped Attributes Count](non-otlp.md#dropped-attributes-count) for tag name to use. | +| Span.DroppedAttributesCount| Add to Span.tags | See [Dropped Attributes Count](../../common/mapping-to-non-otlp.md#dropped-attributes-count) for tag name to use. | | Span.Events | Span.annotations | See [Events](#events) for the mapping format. | -| Span.DroppedEventsCount | Add to Span.tags | See [Dropped Events Count](non-otlp.md#dropped-events-count) for tag name to use. | +| Span.DroppedEventsCount | Add to Span.tags | See [Dropped Events Count](../../common/mapping-to-non-otlp.md#dropped-events-count) for tag name to use. | | Span.Links | TBD | TBD | -| Span.DroppedLinksCount | Add to Span.tags | See [Dropped Links Count](non-otlp.md#dropped-links-count) for tag name to use. | +| Span.DroppedLinksCount | Add to Span.tags | See [Dropped Links Count](../../common/mapping-to-non-otlp.md#dropped-links-count) for tag name to use. | | Span.Status | Add to Span.tags | See [Status](#status) for tag names to use. | TBD : This is work in progress document and it is currently doesn't specify @@ -131,7 +131,7 @@ TBD: add examples ### Status This section overrides the -[generic Status mapping rule](non-otlp.md#span-status). +[generic Status mapping rule](../../common/mapping-to-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.