Move non-otlp.md to common directory

Many of the rules specified in non-otlp.md apply to all signals, not just to traces. The common directory is a better place for this file. Also renamed the file to mapping-to-non-otlp.md to better reflect the content.
open-telemetry · May 31, 2022 · 75ca343 · 75ca343
1 parent 3485e3e
commit 75ca343
Show file tree

Hide file tree

Showing 4 changed files with 21 additions and 22 deletions.
diff --git a/...ification/trace/sdk_exporters/non-otlp.md → specification/common/mapping-to-non-otlp.md b/...ification/trace/sdk_exporters/non-otlp.md → 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
@@ -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
@@ -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
@@ -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.