From b6e8980fe1b37f0de4724b3536bd440d5728243a Mon Sep 17 00:00:00 2001 From: Georg Pirklbauer Date: Mon, 8 Aug 2022 18:00:34 +0200 Subject: [PATCH 01/11] initial --- specification/common/attribute-precedence.md | 162 +++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 specification/common/attribute-precedence.md diff --git a/specification/common/attribute-precedence.md b/specification/common/attribute-precedence.md new file mode 100644 index 00000000000..a0be8932ae0 --- /dev/null +++ b/specification/common/attribute-precedence.md @@ -0,0 +1,162 @@ +# Attribute Precedence on transformation to non-OTLP formats + +This document defines the attribute precedence that exporters should follow when +translating from the hierarchical OTLP format to non-hierarchical formats. + +This mapping is required when flattening out attributes from the structured OTLP +format that allows adding attributes at different levels (e.g., Resource +attributes, InstrumentationLibraryScope attributes, Attributes on +Spans/Metrics/Logs) to a non-hierarchical representation (e.g., OpenMetrics +labels). +In the case of OpenMetrics, the set of labels is completely flat and must have +unique labels only (https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#labelset). +Since OpenTelemetry allows for different levels of attributes, it is feasible +that the same attribute appears multiple times on different levels. + +This document aims to provide guidance around consistently transforming +OpenTelemetry attributes to flat sets. + +## Attribute hierarchy in the OTLP message + +Since the OTLP format is a hierarchical format, there is an inherent order in +the attributes. +This document assumes that Resource attributes are at the top of the hierarchy, +since they are the most general attributes. +Attributes on individual Spans/Metric data points/Logs are at the bottom of the +hierarchy, as they are most specialized and only apply to a subset of all data. + +**A more specialized attribute that shares an attribute key with more general +attribute will take precedence.** + +Therefore, more specialized attributes will overwrite more general ones. +In some cases it might be desirable to overwrite an attribute like this. + + +When de-normalizing the structured OTLP message to a flat set of key-value pairs, +attributes that are present at Resource and InstrumentationLibraryScope level +will be duplicated for each Span/Metric data point/Log. + +## Precedence per Signal + +Below, the precedence for each of the signals is spelled out explicitly. +Some attributes (e.g., Span Link attributes) should only be used when flattening +out attributes to transform the respective concept (Span Link attributes should +not be added when transforming attributes to export spans, for example). +`A > B` means that `A` will overwrite `B` if the keys clash. + +### Traces + +``` +Span.attributes > ScopeSpans.scope.attributes > ResourceSpans.resource.attributes +``` + +#### Span Events + +``` +Span.events.attributes > Span.attributes > ScopeSpans.scope.attributes > ResourceSpans.resource.attributes +``` + +#### Span links + +``` +Span.links.attributes > Span.attributes > ScopeSpans.scope.attributes > ResourceSpans.resource.attributes +``` + +### Metrics + +Metrics are different from Spans and LogRecords, as each Metric has a data field +which can contain one or more data points. +Each data point has a set of attributes, which need to be considered +independently. + +``` +Metric.data.data_points.attributes > ScopeMetrics.scope.attributes > ResourceMetrics.resource.attributes +``` + +#### Metric exemplars + +``` +Metric.data.data_points.exemplars.filtered_attributes > Metric.data.data_points.attributes > ScopeMetrics.scope.attributes > ResourceMetrics.resource.attributes +``` + +### Logs + +``` +LogRecord.log_records.attributes > ScopeLogs.scope.attributes > ResourceLogs.resource.attributes +``` + +## Considerations + +Note that this precedence is a strong suggestion, not a requirement. +Exporters should follow this mode of flattening, but might diverge if they have +a reason to do so. +Furthermore, exporters can apply clash prevention, e.g., by prefixing all +Resource attributes with `resource.`. +Note that even then, a Span attribute can overwrite the resource attribute +`attribute_name`, if it is called `resource.attribute_name`. +Therefore, extra care needs to be taken when prefixing attributes. + +## Example + +De-duplication can be thought of as a map with unique keys to which the +attributes are added, from most general to most specialized. +First, the resource attributes are added, then the InstrumentationLibraryScope +attributes, which overwrite the resource attributes if they share a key. +Then the attributes on the Span/Metric data point/LogRecord are added, which +again overwrite keys that are already present. +The final set of key-value pairs are all the pairs in the map. + +This YAML-like representation of a theoretical OTLP message has attributes +with attribute names that clash on multiple levels. + +```yaml +ResourceMetrics: + resource: + attributes: + # key-value pairs (attributes) on the resource + attribute1: resource-attribute-1 + attribute2: resource-attribute-2 + attribute3: resource-attribute-3 + service.name: my-service + + scope_metrics: + scope: + attributes: + attribute1: scope-attribute-1 + attribute2: scope-attribute-2 + + metrics: + # there can be multiple data entries here. + data/0: + data_points: + # each data can have multiple data points: + data_point/0: + attributes: + attribute1: data-point-0-attribute-1 + + data_point/1: + attributes: + attribute1: data-point-1-attribute-1 +``` + +The structure above contains two data points, thus there will be two data points +in the output. +Their attributes will be: + +```yaml +# data point 0 +service.name: my-service +attribute1: data-point-0-attribute-1 # only this attribute is different +attribute2: scope-attribute-2 +attribute3: resource-attribute-3 + +# data point 1 +service.name: my-service +attribute1: data-point-1-attribute-1 # only this attribute is different +attribute2: scope-attribute-2 +attribute3: resource-attribute-3 +``` + + + + From a7b43978ad4d3d68011e03086b9b1d7728741886 Mon Sep 17 00:00:00 2001 From: Georg Pirklbauer Date: Tue, 9 Aug 2022 11:37:56 +0200 Subject: [PATCH 02/11] update a few sections --- specification/common/attribute-precedence.md | 79 ++++++++++++++------ 1 file changed, 57 insertions(+), 22 deletions(-) diff --git a/specification/common/attribute-precedence.md b/specification/common/attribute-precedence.md index a0be8932ae0..b8f814a619f 100644 --- a/specification/common/attribute-precedence.md +++ b/specification/common/attribute-precedence.md @@ -1,15 +1,41 @@ # Attribute Precedence on transformation to non-OTLP formats -This document defines the attribute precedence that exporters should follow when -translating from the hierarchical OTLP format to non-hierarchical formats. - -This mapping is required when flattening out attributes from the structured OTLP -format that allows adding attributes at different levels (e.g., Resource -attributes, InstrumentationLibraryScope attributes, Attributes on -Spans/Metrics/Logs) to a non-hierarchical representation (e.g., OpenMetrics -labels). +
+Table of Contents + + + +- [Attribute Precedence on transformation to non-OTLP formats](#attribute-precedence-on-transformation-to-non-otlp-formats) + - [Overview](#overview) + - [Attribute hierarchy in the OTLP message](#attribute-hierarchy-in-the-otlp-message) + - [Precedence per Signal](#precedence-per-signal) + - [Traces](#traces) + - [Span Events](#span-events) + - [Span links](#span-links) + - [Metrics](#metrics) + - [Metric exemplars](#metric-exemplars) + - [Logs](#logs) + - [Considerations](#considerations) + - [Example](#example) + - [Useful links](#useful-links) + + + +
+ +## Overview + +This document provides supplementary guidelines for the attribute precedence +that exporters should follow when translating from the hierarchical OTLP format +to non-hierarchical formats. + +A mapping is required when flattening out attributes from the structured OTLP +format has attributes at different levels (e.g., Resource attributes, +InstrumentationLibraryScope attributes, Attributes on Spans/Metrics/Logs) to a +non-hierarchical representation (e.g., OpenMetrics labels). In the case of OpenMetrics, the set of labels is completely flat and must have -unique labels only (https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#labelset). +unique labels only +(https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#labelset). Since OpenTelemetry allows for different levels of attributes, it is feasible that the same attribute appears multiple times on different levels. @@ -20,9 +46,11 @@ OpenTelemetry attributes to flat sets. Since the OTLP format is a hierarchical format, there is an inherent order in the attributes. -This document assumes that Resource attributes are at the top of the hierarchy, -since they are the most general attributes. -Attributes on individual Spans/Metric data points/Logs are at the bottom of the +In this document, +[Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) +attributes are considered to be at the top of the hierarchy, since they are the +most general attributes. +Attributes on individual Spans/ Metric data points/Logs are at the bottom of the hierarchy, as they are most specialized and only apply to a subset of all data. **A more specialized attribute that shares an attribute key with more general @@ -32,17 +60,19 @@ Therefore, more specialized attributes will overwrite more general ones. In some cases it might be desirable to overwrite an attribute like this. -When de-normalizing the structured OTLP message to a flat set of key-value pairs, -attributes that are present at Resource and InstrumentationLibraryScope level -will be duplicated for each Span/Metric data point/Log. +When de-normalizing the structured OTLP message to a flat set of key-value +pairs, attributes that are present at Resource and InstrumentationLibraryScope +level will be duplicated for each Span/Metric data point/Log. ## Precedence per Signal Below, the precedence for each of the signals is spelled out explicitly. Some attributes (e.g., Span Link attributes) should only be used when flattening out attributes to transform the respective concept (Span Link attributes should -not be added when transforming attributes to export spans, for example). -`A > B` means that `A` will overwrite `B` if the keys clash. +not be added when transforming attributes on spans, for example). + +`A > B` denotes that the attribute on `A` will overwrite the attribute on `B` +if the keys clash. ### Traces @@ -88,12 +118,13 @@ LogRecord.log_records.attributes > ScopeLogs.scope.attributes > ResourceLogs.res ## Considerations Note that this precedence is a strong suggestion, not a requirement. -Exporters should follow this mode of flattening, but might diverge if they have -a reason to do so. +Code that transforms attributes should follow this mode of flattening, but might +diverge if they have a reason to do so. Furthermore, exporters can apply clash prevention, e.g., by prefixing all Resource attributes with `resource.`. -Note that even then, a Span attribute can overwrite the resource attribute -`attribute_name`, if it is called `resource.attribute_name`. +Note that even then, a Span/Metric data point/LogRecord attribute can overwrite +the resource attribute `attribute_name`, if it is called +`resource.attribute_name`. Therefore, extra care needs to be taken when prefixing attributes. ## Example @@ -157,6 +188,10 @@ attribute2: scope-attribute-2 attribute3: resource-attribute-3 ``` +## Useful links - +* [Trace Proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/trace/v1/trace.proto) +* [Metrics Proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/metrics/v1/metrics.proto) +* [Logs Proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/logs/v1/logs.proto) +* [Resource Proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/resource/v1/resource.proto) From 2e2834c8e99809f2f6729fb652d4a3783c2b4229 Mon Sep 17 00:00:00 2001 From: Georg Pirklbauer Date: Tue, 9 Aug 2022 12:34:27 +0200 Subject: [PATCH 03/11] add link to readme --- specification/common/README.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/specification/common/README.md b/specification/common/README.md index 2b377a731cd..af5b3464c31 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -10,11 +10,12 @@ aliases: [/docs/reference/specification/common/common] -- [Attribute](#attribute) - * [Attribute Limits](#attribute-limits) - + [Configurable Parameters](#configurable-parameters) - + [Exempt Entities](#exempt-entities) -- [Attribute Collections](#attribute-collections) +- [Common specification concepts](#common-specification-concepts) + - [Attribute](#attribute) + - [Attribute Limits](#attribute-limits) + - [Configurable Parameters](#configurable-parameters) + - [Exempt Entities](#exempt-entities) + - [Attribute Collections](#attribute-collections) @@ -59,6 +60,10 @@ See [Requirement Level](attribute-requirement-level.md) for requirement levels g See [this document](attribute-type-mapping.md) to find out how to map values obtained outside OpenTelemetry into OpenTelemetry attribute values. +See [the document on attribute precedence](attribute-precedence.md) to find out +how to transform a structured representation like OTLP to a flat set of unique +attributes. + ### Attribute Limits Execution of erroneous code can result in unintended attributes. If there are no From 5ca79ddbf38141142fa2d0ea93ef07f622da8b9f Mon Sep 17 00:00:00 2001 From: Georg Pirklbauer Date: Tue, 9 Aug 2022 12:34:49 +0200 Subject: [PATCH 04/11] status header --- specification/common/attribute-precedence.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/common/attribute-precedence.md b/specification/common/attribute-precedence.md index b8f814a619f..3658cb3a9e2 100644 --- a/specification/common/attribute-precedence.md +++ b/specification/common/attribute-precedence.md @@ -1,5 +1,7 @@ # Attribute Precedence on transformation to non-OTLP formats +**Status**: [Experimental](../document-status.md) +
Table of Contents From 1a87bfc2bfdbfefe03cdb451a10a8aaed12f9769 Mon Sep 17 00:00:00 2001 From: Georg Pirklbauer Date: Thu, 11 Aug 2022 11:31:31 +0200 Subject: [PATCH 05/11] Review comments Co-authored-by: Joao Grassi --- specification/common/README.md | 17 ++-- specification/common/attribute-precedence.md | 92 +++++++++----------- 2 files changed, 47 insertions(+), 62 deletions(-) diff --git a/specification/common/README.md b/specification/common/README.md index af5b3464c31..e0a94607f20 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -10,12 +10,11 @@ aliases: [/docs/reference/specification/common/common] -- [Common specification concepts](#common-specification-concepts) - - [Attribute](#attribute) - - [Attribute Limits](#attribute-limits) - - [Configurable Parameters](#configurable-parameters) - - [Exempt Entities](#exempt-entities) - - [Attribute Collections](#attribute-collections) +- [Attribute](#attribute) + * [Attribute Limits](#attribute-limits) + + [Configurable Parameters](#configurable-parameters) + + [Exempt Entities](#exempt-entities) +- [Attribute Collections](#attribute-collections) @@ -60,9 +59,9 @@ See [Requirement Level](attribute-requirement-level.md) for requirement levels g See [this document](attribute-type-mapping.md) to find out how to map values obtained outside OpenTelemetry into OpenTelemetry attribute values. -See [the document on attribute precedence](attribute-precedence.md) to find out -how to transform a structured representation like OTLP to a flat set of unique -attributes. +See [Attribute precedence for non-OTLP exporters](attribute-precedence.md) to +find out how to transform a structured representation like OTLP to a flat set of +unique attributes. ### Attribute Limits diff --git a/specification/common/attribute-precedence.md b/specification/common/attribute-precedence.md index 3658cb3a9e2..13c173a3bca 100644 --- a/specification/common/attribute-precedence.md +++ b/specification/common/attribute-precedence.md @@ -7,19 +7,18 @@ -- [Attribute Precedence on transformation to non-OTLP formats](#attribute-precedence-on-transformation-to-non-otlp-formats) - - [Overview](#overview) - - [Attribute hierarchy in the OTLP message](#attribute-hierarchy-in-the-otlp-message) - - [Precedence per Signal](#precedence-per-signal) - - [Traces](#traces) - - [Span Events](#span-events) - - [Span links](#span-links) - - [Metrics](#metrics) - - [Metric exemplars](#metric-exemplars) - - [Logs](#logs) - - [Considerations](#considerations) - - [Example](#example) - - [Useful links](#useful-links) +- [Overview](#overview) +- [Attribute hierarchy in the OTLP message](#attribute-hierarchy-in-the-otlp-message) +- [Precedence per Signal](#precedence-per-signal) + - [Traces](#traces) + - [Span Events](#span-events) + - [Span links](#span-links) + - [Metrics](#metrics) + - [Metric exemplars](#metric-exemplars) + - [Logs](#logs) +- [Considerations](#considerations) +- [Example](#example) +- [Useful links](#useful-links) @@ -32,8 +31,8 @@ that exporters should follow when translating from the hierarchical OTLP format to non-hierarchical formats. A mapping is required when flattening out attributes from the structured OTLP -format has attributes at different levels (e.g., Resource attributes, -InstrumentationLibraryScope attributes, Attributes on Spans/Metrics/Logs) to a +format, which has attributes at different levels (e.g., Resource attributes, +InstrumentationScope attributes, attributes on Spans/Metrics/Logs) to a non-hierarchical representation (e.g., OpenMetrics labels). In the case of OpenMetrics, the set of labels is completely flat and must have unique labels only @@ -41,10 +40,10 @@ unique labels only Since OpenTelemetry allows for different levels of attributes, it is feasible that the same attribute appears multiple times on different levels. -This document aims to provide guidance around consistently transforming -OpenTelemetry attributes to flat sets. +This document aims to provide guidance on how OpenTelemetry attributes can be +consistently mapped to flat sets. -## Attribute hierarchy in the OTLP message +## Attribute hierarchy in OTLP messages Since the OTLP format is a hierarchical format, there is an inherent order in the attributes. @@ -52,19 +51,18 @@ In this document, [Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) attributes are considered to be at the top of the hierarchy, since they are the most general attributes. -Attributes on individual Spans/ Metric data points/Logs are at the bottom of the +Attributes on individual Spans/Metric data points/Logs are at the bottom of the hierarchy, as they are most specialized and only apply to a subset of all data. **A more specialized attribute that shares an attribute key with more general attribute will take precedence.** -Therefore, more specialized attributes will overwrite more general ones. In some cases it might be desirable to overwrite an attribute like this. -When de-normalizing the structured OTLP message to a flat set of key-value -pairs, attributes that are present at Resource and InstrumentationLibraryScope -level will be duplicated for each Span/Metric data point/Log. +When de-normalizing an OTLP message to a flat set of key-value pairs, +attributes that are present on the Resource and InstrumentationScope levels will +be duplicated for each Span/Metric data point/Log. ## Precedence per Signal @@ -122,25 +120,11 @@ LogRecord.log_records.attributes > ScopeLogs.scope.attributes > ResourceLogs.res Note that this precedence is a strong suggestion, not a requirement. Code that transforms attributes should follow this mode of flattening, but might diverge if they have a reason to do so. -Furthermore, exporters can apply clash prevention, e.g., by prefixing all -Resource attributes with `resource.`. -Note that even then, a Span/Metric data point/LogRecord attribute can overwrite -the resource attribute `attribute_name`, if it is called -`resource.attribute_name`. -Therefore, extra care needs to be taken when prefixing attributes. ## Example -De-duplication can be thought of as a map with unique keys to which the -attributes are added, from most general to most specialized. -First, the resource attributes are added, then the InstrumentationLibraryScope -attributes, which overwrite the resource attributes if they share a key. -Then the attributes on the Span/Metric data point/LogRecord are added, which -again overwrite keys that are already present. -The final set of key-value pairs are all the pairs in the map. - -This YAML-like representation of a theoretical OTLP message has attributes -with attribute names that clash on multiple levels. +The following is a theoretical YAML-like representation of an OTLP message which +has attributes with attribute names that clash on multiple levels. ```yaml ResourceMetrics: @@ -163,13 +147,15 @@ ResourceMetrics: data/0: data_points: # each data can have multiple data points: - data_point/0: - attributes: - attribute1: data-point-0-attribute-1 - data_point/1: attributes: + # will overwrite scope and resource attribute attribute1: data-point-1-attribute-1 + + data_point/2: + attributes: + # will overwrite + attribute1: data-point-2-attribute-1 ``` The structure above contains two data points, thus there will be two data points @@ -177,17 +163,17 @@ in the output. Their attributes will be: ```yaml -# data point 0 -service.name: my-service -attribute1: data-point-0-attribute-1 # only this attribute is different -attribute2: scope-attribute-2 -attribute3: resource-attribute-3 - # data point 1 -service.name: my-service -attribute1: data-point-1-attribute-1 # only this attribute is different -attribute2: scope-attribute-2 -attribute3: resource-attribute-3 +service.name: my-service # from the resource +attribute1: data-point-1-attribute-1 # overwrites attribute1 on resource & scope +attribute2: scope-attribute-2 # overwrites attribute2 on resource +attribute3: resource-attribute-3 # from the resource, not overwritten + +# data point 2 +service.name: my-service # from the resource +attribute1: data-point-2-attribute-1 # overwrites attribute1 on resource & scope +attribute2: scope-attribute-2 # overwrites attribute2 on resource +attribute3: resource-attribute-3 # from the resource, not overwritten ``` ## Useful links From 935786bd0a8d943d82e54c64737615126cc00f27 Mon Sep 17 00:00:00 2001 From: Georg Pirklbauer Date: Thu, 11 Aug 2022 11:49:13 +0200 Subject: [PATCH 06/11] span links / events / metric exemplars Co-authored-by: Joao Grassi --- specification/common/attribute-precedence.md | 32 +++++++------------- 1 file changed, 11 insertions(+), 21 deletions(-) diff --git a/specification/common/attribute-precedence.md b/specification/common/attribute-precedence.md index 13c173a3bca..4aa339d3bde 100644 --- a/specification/common/attribute-precedence.md +++ b/specification/common/attribute-precedence.md @@ -67,9 +67,17 @@ be duplicated for each Span/Metric data point/Log. ## Precedence per Signal Below, the precedence for each of the signals is spelled out explicitly. -Some attributes (e.g., Span Link attributes) should only be used when flattening -out attributes to transform the respective concept (Span Link attributes should -not be added when transforming attributes on spans, for example). +Only Spans, Metric data points and LogRecords are considered. +Span Links, Span Events and Metric Exemplars need to be considered differently, +as conflicting entries there can lead to problematic data loss. +Consider a `http.host` attribute on a Span Link, which identifies the host of a +linked Span. +Following the "more specialized overwrites more general" suggestion leads to +overwriting the `http.host` attribute of the Span, which is likely desired +information. +Consider transferring attributes on Span Links, Span Events and Metric Exemplars +separately from the parent Span/Metric data point. + `A > B` denotes that the attribute on `A` will overwrite the attribute on `B` if the keys clash. @@ -80,18 +88,6 @@ if the keys clash. Span.attributes > ScopeSpans.scope.attributes > ResourceSpans.resource.attributes ``` -#### Span Events - -``` -Span.events.attributes > Span.attributes > ScopeSpans.scope.attributes > ResourceSpans.resource.attributes -``` - -#### Span links - -``` -Span.links.attributes > Span.attributes > ScopeSpans.scope.attributes > ResourceSpans.resource.attributes -``` - ### Metrics Metrics are different from Spans and LogRecords, as each Metric has a data field @@ -103,12 +99,6 @@ independently. Metric.data.data_points.attributes > ScopeMetrics.scope.attributes > ResourceMetrics.resource.attributes ``` -#### Metric exemplars - -``` -Metric.data.data_points.exemplars.filtered_attributes > Metric.data.data_points.attributes > ScopeMetrics.scope.attributes > ResourceMetrics.resource.attributes -``` - ### Logs ``` From 6f1f3d3e3957f8ff1ff77a2c0881e6ea034f96ad Mon Sep 17 00:00:00 2001 From: Georg Pirklbauer Date: Thu, 11 Aug 2022 14:12:21 +0200 Subject: [PATCH 07/11] review comments Co-authored-by: Marc Pichler --- specification/common/attribute-precedence.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/specification/common/attribute-precedence.md b/specification/common/attribute-precedence.md index 4aa339d3bde..a60fb0aba6d 100644 --- a/specification/common/attribute-precedence.md +++ b/specification/common/attribute-precedence.md @@ -54,15 +54,12 @@ most general attributes. Attributes on individual Spans/Metric data points/Logs are at the bottom of the hierarchy, as they are most specialized and only apply to a subset of all data. -**A more specialized attribute that shares an attribute key with more general -attribute will take precedence.** +**A more specialized attribute that shares an attribute key with more general +attribute will take precedence and overwrite the more general attribute.** -In some cases it might be desirable to overwrite an attribute like this. - - -When de-normalizing an OTLP message to a flat set of key-value pairs, +When de-normalizing an OTLP message into a flat set of key-value pairs, attributes that are present on the Resource and InstrumentationScope levels will -be duplicated for each Span/Metric data point/Log. +be attached to each Span/Metric data point/Log. ## Precedence per Signal @@ -78,8 +75,7 @@ information. Consider transferring attributes on Span Links, Span Events and Metric Exemplars separately from the parent Span/Metric data point. - -`A > B` denotes that the attribute on `A` will overwrite the attribute on `B` +`A > B` denotes that the attribute on `A` will overwrite the attribute on `B` if the keys clash. ### Traces @@ -108,7 +104,7 @@ LogRecord.log_records.attributes > ScopeLogs.scope.attributes > ResourceLogs.res ## Considerations Note that this precedence is a strong suggestion, not a requirement. -Code that transforms attributes should follow this mode of flattening, but might +Code that transforms attributes should follow this mode of flattening, but may diverge if they have a reason to do so. ## Example From 848faaaa70952947db78bb22d9a2e458d58e1d7f Mon Sep 17 00:00:00 2001 From: Georg Pirklbauer Date: Tue, 16 Aug 2022 14:53:10 +0200 Subject: [PATCH 08/11] review comments --- specification/common/attribute-precedence.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/attribute-precedence.md b/specification/common/attribute-precedence.md index a60fb0aba6d..94dd323e27b 100644 --- a/specification/common/attribute-precedence.md +++ b/specification/common/attribute-precedence.md @@ -64,7 +64,7 @@ be attached to each Span/Metric data point/Log. ## Precedence per Signal Below, the precedence for each of the signals is spelled out explicitly. -Only Spans, Metric data points and LogRecords are considered. +Only spans, metric data points and log records are considered. Span Links, Span Events and Metric Exemplars need to be considered differently, as conflicting entries there can lead to problematic data loss. Consider a `http.host` attribute on a Span Link, which identifies the host of a From 45bbdb7f4e3d06140e108f49c3a6f0309358f1e1 Mon Sep 17 00:00:00 2001 From: Georg Pirklbauer Date: Wed, 17 Aug 2022 10:18:24 +0200 Subject: [PATCH 09/11] review comments Co-authored-by: Joao Grassi --- specification/common/attribute-precedence.md | 34 ++++++++++++-------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/specification/common/attribute-precedence.md b/specification/common/attribute-precedence.md index 94dd323e27b..9fba6fd4800 100644 --- a/specification/common/attribute-precedence.md +++ b/specification/common/attribute-precedence.md @@ -1,4 +1,4 @@ -# Attribute Precedence on transformation to non-OTLP formats +# Attribute precedence on transformation to non-OTLP formats **Status**: [Experimental](../document-status.md) @@ -8,14 +8,12 @@ - [Overview](#overview) -- [Attribute hierarchy in the OTLP message](#attribute-hierarchy-in-the-otlp-message) +- [Attribute hierarchy in OTLP messages](#attribute-hierarchy-in-otlp-messages) - [Precedence per Signal](#precedence-per-signal) - [Traces](#traces) - - [Span Events](#span-events) - - [Span links](#span-links) - [Metrics](#metrics) - - [Metric exemplars](#metric-exemplars) - [Logs](#logs) + - [Span Links, Span Events and Metric Exemplars](#span-links-span-events-and-metric-exemplars) - [Considerations](#considerations) - [Example](#example) - [Useful links](#useful-links) @@ -65,15 +63,6 @@ be attached to each Span/Metric data point/Log. Below, the precedence for each of the signals is spelled out explicitly. Only spans, metric data points and log records are considered. -Span Links, Span Events and Metric Exemplars need to be considered differently, -as conflicting entries there can lead to problematic data loss. -Consider a `http.host` attribute on a Span Link, which identifies the host of a -linked Span. -Following the "more specialized overwrites more general" suggestion leads to -overwriting the `http.host` attribute of the Span, which is likely desired -information. -Consider transferring attributes on Span Links, Span Events and Metric Exemplars -separately from the parent Span/Metric data point. `A > B` denotes that the attribute on `A` will overwrite the attribute on `B` if the keys clash. @@ -101,6 +90,19 @@ Metric.data.data_points.attributes > ScopeMetrics.scope.attributes > ResourceMet LogRecord.log_records.attributes > ScopeLogs.scope.attributes > ResourceLogs.resource.attributes ``` +### Span Links, Span Events and Metric Exemplars + +> Span Links, Span Events and Metric Exemplars need to be considered +> differently, as conflicting entries there can lead to problematic data loss. + +Consider a `http.host` attribute on a Span Link, which identifies the host of a +linked Span. +Following the "more specialized overwrites more general" suggestion leads to +overwriting the `http.host` attribute of the Span, which is likely desired +information. +Transferring attributes on Span Links, Span Events and Metric Exemplars should +be done separately from the parent Span/Metric data point. + ## Considerations Note that this precedence is a strong suggestion, not a requirement. @@ -127,6 +129,7 @@ ResourceMetrics: attributes: attribute1: scope-attribute-1 attribute2: scope-attribute-2 + attribute4: scope-attribute-4 metrics: # there can be multiple data entries here. @@ -142,6 +145,7 @@ ResourceMetrics: attributes: # will overwrite attribute1: data-point-2-attribute-1 + attribute4: data-point-2-attribute-4 ``` The structure above contains two data points, thus there will be two data points @@ -154,12 +158,14 @@ service.name: my-service # from the resource attribute1: data-point-1-attribute-1 # overwrites attribute1 on resource & scope attribute2: scope-attribute-2 # overwrites attribute2 on resource attribute3: resource-attribute-3 # from the resource, not overwritten +attribute4: scope-attribute-4 # from the scope, not overwritten # data point 2 service.name: my-service # from the resource attribute1: data-point-2-attribute-1 # overwrites attribute1 on resource & scope attribute2: scope-attribute-2 # overwrites attribute2 on resource attribute3: resource-attribute-3 # from the resource, not overwritten +attribute4: data-point-2-attribute-4 # overwrites attribute4 from the scope ``` ## Useful links From f130fcde96d75da862aa5dae55429e4e44b8bbfa Mon Sep 17 00:00:00 2001 From: Georg Pirklbauer Date: Wed, 17 Aug 2022 10:27:43 +0200 Subject: [PATCH 10/11] polish --- specification/common/README.md | 2 +- specification/common/attribute-precedence.md | 33 ++++++++++---------- 2 files changed, 17 insertions(+), 18 deletions(-) diff --git a/specification/common/README.md b/specification/common/README.md index e0a94607f20..0e7e37e5df2 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -59,7 +59,7 @@ See [Requirement Level](attribute-requirement-level.md) for requirement levels g See [this document](attribute-type-mapping.md) to find out how to map values obtained outside OpenTelemetry into OpenTelemetry attribute values. -See [Attribute precedence for non-OTLP exporters](attribute-precedence.md) to +See [Attribute precedence for non-OTLP exporters](attribute-precedence.md) to find out how to transform a structured representation like OTLP to a flat set of unique attributes. diff --git a/specification/common/attribute-precedence.md b/specification/common/attribute-precedence.md index 9fba6fd4800..5aa51d15c39 100644 --- a/specification/common/attribute-precedence.md +++ b/specification/common/attribute-precedence.md @@ -10,10 +10,10 @@ - [Overview](#overview) - [Attribute hierarchy in OTLP messages](#attribute-hierarchy-in-otlp-messages) - [Precedence per Signal](#precedence-per-signal) - - [Traces](#traces) - - [Metrics](#metrics) - - [Logs](#logs) - - [Span Links, Span Events and Metric Exemplars](#span-links-span-events-and-metric-exemplars) + * [Traces](#traces) + * [Metrics](#metrics) + * [Logs](#logs) + * [Span Links, Span Events and Metric Exemplars](#span-links-span-events-and-metric-exemplars) - [Considerations](#considerations) - [Example](#example) - [Useful links](#useful-links) @@ -24,31 +24,31 @@ ## Overview -This document provides supplementary guidelines for the attribute precedence +This document provides supplementary guidelines for the attribute precedence that exporters should follow when translating from the hierarchical OTLP format to non-hierarchical formats. A mapping is required when flattening out attributes from the structured OTLP -format, which has attributes at different levels (e.g., Resource attributes, +format, which has attributes at different levels (e.g., Resource attributes, InstrumentationScope attributes, attributes on Spans/Metrics/Logs) to a non-hierarchical representation (e.g., OpenMetrics labels). -In the case of OpenMetrics, the set of labels is completely flat and must have -unique labels only -(https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#labelset). +In the case of OpenMetrics, the set of labels is completely flat and must have +unique labels only +(). Since OpenTelemetry allows for different levels of attributes, it is feasible that the same attribute appears multiple times on different levels. -This document aims to provide guidance on how OpenTelemetry attributes can be +This document aims to provide guidance on how OpenTelemetry attributes can be consistently mapped to flat sets. ## Attribute hierarchy in OTLP messages -Since the OTLP format is a hierarchical format, there is an inherent order in +Since the OTLP format is a hierarchical format, there is an inherent order in the attributes. -In this document, +In this document, [Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) attributes are considered to be at the top of the hierarchy, since they are the -most general attributes. +most general attributes. Attributes on individual Spans/Metric data points/Logs are at the bottom of the hierarchy, as they are most specialized and only apply to a subset of all data. @@ -77,7 +77,7 @@ Span.attributes > ScopeSpans.scope.attributes > ResourceSpans.resource.attribute Metrics are different from Spans and LogRecords, as each Metric has a data field which can contain one or more data points. -Each data point has a set of attributes, which need to be considered +Each data point has a set of attributes, which need to be considered independently. ``` @@ -106,8 +106,8 @@ be done separately from the parent Span/Metric data point. ## Considerations Note that this precedence is a strong suggestion, not a requirement. -Code that transforms attributes should follow this mode of flattening, but may -diverge if they have a reason to do so. +Code that transforms attributes should follow this mode of flattening, but may +diverge if they have a reason to do so. ## Example @@ -174,4 +174,3 @@ attribute4: data-point-2-attribute-4 # overwrites attribute4 from the scope * [Metrics Proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/metrics/v1/metrics.proto) * [Logs Proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/logs/v1/logs.proto) * [Resource Proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/resource/v1/resource.proto) - From 0a228b3871a01bf222b0a484e06513c406e6f52c Mon Sep 17 00:00:00 2001 From: Georg Pirklbauer Date: Wed, 17 Aug 2022 13:48:25 +0200 Subject: [PATCH 11/11] review comments Co-authored-by: Armin Ruech --- specification/common/attribute-precedence.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/specification/common/attribute-precedence.md b/specification/common/attribute-precedence.md index 5aa51d15c39..2cb3f7b5cd7 100644 --- a/specification/common/attribute-precedence.md +++ b/specification/common/attribute-precedence.md @@ -31,11 +31,11 @@ to non-hierarchical formats. A mapping is required when flattening out attributes from the structured OTLP format, which has attributes at different levels (e.g., Resource attributes, InstrumentationScope attributes, attributes on Spans/Metrics/Logs) to a -non-hierarchical representation (e.g., OpenMetrics labels). -In the case of OpenMetrics, the set of labels is completely flat and must have -unique labels only +non-hierarchical representation (e.g., Prometheus/OpenMetrics labels). +In the case of OpenMetrics, the set of labels is flat and must have unique +labels only (). -Since OpenTelemetry allows for different levels of attributes, it is feasible +Since OpenTelemetry allows for different levels of attributes, it is possible that the same attribute appears multiple times on different levels. This document aims to provide guidance on how OpenTelemetry attributes can be @@ -47,8 +47,8 @@ Since the OTLP format is a hierarchical format, there is an inherent order in the attributes. In this document, [Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) -attributes are considered to be at the top of the hierarchy, since they are the -most general attributes. +attributes are considered to be at the top of the hierarchy, since they apply to +all collected telemetry. Attributes on individual Spans/Metric data points/Logs are at the bottom of the hierarchy, as they are most specialized and only apply to a subset of all data. @@ -102,6 +102,7 @@ overwriting the `http.host` attribute of the Span, which is likely desired information. Transferring attributes on Span Links, Span Events and Metric Exemplars should be done separately from the parent Span/Metric data point. +This is out of the scope of these guidelines. ## Considerations