From 026fad16d73816efc9b2eb064140959459531b55 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Thu, 17 Jul 2025 23:34:06 +0200 Subject: [PATCH 1/8] Add empty value to attribute --- specification/common/README.md | 12 +++++------- specification/common/attribute-type-mapping.md | 6 ++++++ 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/specification/common/README.md b/specification/common/README.md index 4b95d8b8508..1724db3cfcd 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -8,7 +8,7 @@ path_base_for_github_subdir: # Common specification concepts -**Status**: [Stable](../document-status.md) +**Status**: [Stable](../document-status.md), except where otherwise specified
Table of Contents @@ -38,15 +38,13 @@ An `Attribute` is a key-value pair, which MUST have the following properties: - A primitive type: string, boolean, double precision floating point (IEEE 754-1985) or signed 64 bit integer. - An array of primitive type values. The array MUST be homogeneous, i.e., it MUST NOT contain values of different types. + - **Status**: [Stable](../document-status.md) - An empty value (e.g. `null`). For protocols that do not natively support non-string values, non-string values SHOULD be represented as JSON-encoded strings. For example, the expression `int64(100)` will be encoded as `100`, `float64(1.5)` will be encoded as `1.5`, and an empty array of any type will be encoded as `[]`. -Attribute values expressing a numerical value of zero, an empty string, or an -empty array are considered meaningful and MUST be stored and passed on to -processors / exporters. - -Attribute values of `null` are not valid and attempting to set a `null` value is -undefined behavior. +Attribute values expressing an empty value, a numerical value of zero, +an empty string, or an empty array are considered meaningful and MUST be stored +and passed on to processors / exporters. `null` values SHOULD NOT be allowed in arrays. However, if it is impossible to make sure that no `null` values are accepted diff --git a/specification/common/attribute-type-mapping.md b/specification/common/attribute-type-mapping.md index e936eb1695c..56251663268 100644 --- a/specification/common/attribute-type-mapping.md +++ b/specification/common/attribute-type-mapping.md @@ -54,6 +54,12 @@ follow the rules described below. ### Primitive Values +#### Empty Value + +Empty values SHOULD be converted to AnyValue with no +[value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L28-L30) +field being set. + #### Integer Values Integer values which are within the range of 64 bit signed numbers From 18311641df520e578137ef9ca11fc6766825595a Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Thu, 17 Jul 2025 23:35:32 +0200 Subject: [PATCH 2/8] Update changelog --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 23a27cd2a00..139c4fadc81 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -57,6 +57,9 @@ release. ### Common +- Add empty value to attribute. + ([#4595](https://github.com/open-telemetry/opentelemetry-specification/pull/4595)) + ### Supplementary Guidelines ### OTEPs From 82e8913989e8d3250fb546ea7398efe6b0f8f5d0 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Thu, 17 Jul 2025 23:44:16 +0200 Subject: [PATCH 3/8] toc --- specification/common/attribute-type-mapping.md | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/common/attribute-type-mapping.md b/specification/common/attribute-type-mapping.md index 56251663268..015847c8aeb 100644 --- a/specification/common/attribute-type-mapping.md +++ b/specification/common/attribute-type-mapping.md @@ -13,6 +13,7 @@ linkTitle: Mapping to AnyValue - [Converting to AnyValue](#converting-to-anyvalue) * [Primitive Values](#primitive-values) + + [Empty Value](#empty-value) + [Integer Values](#integer-values) + [Enumerations](#enumerations) + [Floating Point Values](#floating-point-values) From 9cab0c47c347298743bb795ac327d80187052b70 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Thu, 17 Jul 2025 23:47:49 +0200 Subject: [PATCH 4/8] fix status --- specification/common/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/README.md b/specification/common/README.md index 1724db3cfcd..06806a5bc2b 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -38,7 +38,7 @@ An `Attribute` is a key-value pair, which MUST have the following properties: - A primitive type: string, boolean, double precision floating point (IEEE 754-1985) or signed 64 bit integer. - An array of primitive type values. The array MUST be homogeneous, i.e., it MUST NOT contain values of different types. - - **Status**: [Stable](../document-status.md) - An empty value (e.g. `null`). + - **Status**: [Development](../document-status.md) - An empty value (e.g. `null`). For protocols that do not natively support non-string values, non-string values SHOULD be represented as JSON-encoded strings. For example, the expression `int64(100)` will be encoded as `100`, `float64(1.5)` will be encoded as `1.5`, and an empty array of any type will be encoded as `[]`. From 85db60a47e8dfc50e793059dd229fcc60fccb22b Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Thu, 17 Jul 2025 23:58:27 +0200 Subject: [PATCH 5/8] Remove the note that extending attributes is a breaking change --- specification/common/README.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/specification/common/README.md b/specification/common/README.md index 06806a5bc2b..95ad05fbd08 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -81,21 +81,6 @@ reflects that LogRecord attributes are expected to model data produced from external log APIs, which do not necessarily have the same value type restrictions as the standard attribute definition. -Note: Extending the set of standard attribute value types is a breaking change. -This was decided after extensive debate, with arguments as follows: - -* Limiting the types of attribute values to a set which has proved sufficient - during several years of OpenTelemetry's development is a useful guardrail for - design. In taking additional value types off the table, we narrow the solution - space and have more productive design conversations. -* Upon proposing to extend support for complex value types, we received significant - pushback. Limiting attribute value types to primitives and arrays of primitives - simplifies data consumers' efforts to create search indexes and perform statistical - analysis. -* To address concerns over restricting standard attributes to primitive types, it was - called out that complex types can be encoded as existing primitive types, such as - representing datetime as a string or 64 bit integer. - ### Attribute Limits Execution of erroneous code can result in unintended attributes. If there are no From eaea1ea7dbe664bad1f6ae2b9cace004bb19d951 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 18 Jul 2025 00:24:52 +0200 Subject: [PATCH 6/8] Update CHANGELOG.md --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 139c4fadc81..f36b92b717b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -57,7 +57,7 @@ release. ### Common -- Add empty value to attribute. +- Add empty value attribute. ([#4595](https://github.com/open-telemetry/opentelemetry-specification/pull/4595)) ### Supplementary Guidelines From 25c2c257e4975284bf76b3fe3b70d12b4c71f0e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 18 Jul 2025 04:03:32 +0200 Subject: [PATCH 7/8] Update specification/common/attribute-type-mapping.md Co-authored-by: Tyler Yahn --- specification/common/attribute-type-mapping.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/attribute-type-mapping.md b/specification/common/attribute-type-mapping.md index 015847c8aeb..d41ebc82979 100644 --- a/specification/common/attribute-type-mapping.md +++ b/specification/common/attribute-type-mapping.md @@ -57,7 +57,7 @@ follow the rules described below. #### Empty Value -Empty values SHOULD be converted to AnyValue with no +Empty values MUST be converted to AnyValue with no [value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L28-L30) field being set. From c5400989f60bb90e4e47407ec1c3b3c45322d61d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 22 Jul 2025 17:46:08 +0200 Subject: [PATCH 8/8] revert breaking change note --- specification/common/README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/specification/common/README.md b/specification/common/README.md index 95ad05fbd08..06806a5bc2b 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -81,6 +81,21 @@ reflects that LogRecord attributes are expected to model data produced from external log APIs, which do not necessarily have the same value type restrictions as the standard attribute definition. +Note: Extending the set of standard attribute value types is a breaking change. +This was decided after extensive debate, with arguments as follows: + +* Limiting the types of attribute values to a set which has proved sufficient + during several years of OpenTelemetry's development is a useful guardrail for + design. In taking additional value types off the table, we narrow the solution + space and have more productive design conversations. +* Upon proposing to extend support for complex value types, we received significant + pushback. Limiting attribute value types to primitives and arrays of primitives + simplifies data consumers' efforts to create search indexes and perform statistical + analysis. +* To address concerns over restricting standard attributes to primitive types, it was + called out that complex types can be encoded as existing primitive types, such as + representing datetime as a string or 64 bit integer. + ### Attribute Limits Execution of erroneous code can result in unintended attributes. If there are no