From 478bb16966878cfdfa87bae4fd5cfdcc636bda16 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Wed, 31 Jan 2024 13:19:23 -0600 Subject: [PATCH 1/5] Prohibit attribute values from containing complex types --- specification/common/README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/specification/common/README.md b/specification/common/README.md index 4b9adc77b2d..7832d62c3cd 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -54,6 +54,13 @@ indices that are kept in sync (e.g., two attributes `header_keys` and `header_va both containing an array of strings to represent a mapping `header_keys[i] -> header_values[i]`). +Attribute values MUST NOT be evolved to support complex types (e.g. maps and +heterogeneous arrays). Note: the log data model +defines [attributes](../logs/data-model.md#field-attributes) with values of +type `Any`. This is an intentional divergence from the standard definition of +attributes defined here. Log record attributes are a super set of standard +attributes. + See [Attribute Naming](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-naming.md) for naming guidelines. See [Requirement Level](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-requirement-level.md) for requirement levels guidelines. From 848ef60084248d08599671c1be540616cac1a37b Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Wed, 14 Feb 2024 09:59:59 -0600 Subject: [PATCH 2/5] Changing attribute value types is a breaking change, define standard attribute --- specification/common/README.md | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/specification/common/README.md b/specification/common/README.md index 7832d62c3cd..aa270cc0bfa 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -29,7 +29,7 @@ An `Attribute` is a key-value pair, which MUST have the following properties: - The attribute key MUST be a non-`null` and non-empty string. - Case sensitivity of keys is preserved. Keys that differ in casing are treated as distinct keys. -- The attribute value is either: +- The attribute value is either[1]: - 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. @@ -54,13 +54,6 @@ indices that are kept in sync (e.g., two attributes `header_keys` and `header_va both containing an array of strings to represent a mapping `header_keys[i] -> header_values[i]`). -Attribute values MUST NOT be evolved to support complex types (e.g. maps and -heterogeneous arrays). Note: the log data model -defines [attributes](../logs/data-model.md#field-attributes) with values of -type `Any`. This is an intentional divergence from the standard definition of -attributes defined here. Log record attributes are a super set of standard -attributes. - See [Attribute Naming](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-naming.md) for naming guidelines. See [Requirement Level](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-requirement-level.md) for requirement levels guidelines. @@ -68,6 +61,24 @@ See [Requirement Level](https://github.com/open-telemetry/semantic-conventions/b See [this document](attribute-type-mapping.md) to find out how to map values obtained outside OpenTelemetry into OpenTelemetry attribute values. +**[1]**: Note: extending the set of allowable attribute value types is a +breaking change. + +### Standard Attribute + +Attributes are used in various places throughout the OpenTelemetry data model. +We designate the [previous attribute section](#attribute) as the standard +attribute definition, in order to facilitate more intuitive and consistent API / +SDK design. + +The standard attribute definition SHOULD be used to represent attributes in data +modeling unless there is a strong justification to diverge. For example, the log +data model has an extended [attributes](../logs/data-model.md#field-attributes) +definition allowing values of type `Any`. This reflects that log record +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. + ### Attribute Limits Execution of erroneous code can result in unintended attributes. If there are no From 53c5ad182631ad72a8d50d088f112d0b43775c87 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Wed, 14 Feb 2024 10:07:33 -0600 Subject: [PATCH 3/5] markdown-toc --- specification/common/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/common/README.md b/specification/common/README.md index aa270cc0bfa..29dc2ad8634 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -12,6 +12,7 @@ aliases: [/docs/reference/specification/common/common] - [Attribute](#attribute) + * [Standard Attribute](#standard-attribute) * [Attribute Limits](#attribute-limits) + [Configurable Parameters](#configurable-parameters) + [Exempt Entities](#exempt-entities) From 5b55675dfdb4c39c3b2c30420aef9c16e8971fcc Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Thu, 15 Feb 2024 09:47:09 -0600 Subject: [PATCH 4/5] Formatting --- specification/common/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/common/README.md b/specification/common/README.md index 29dc2ad8634..fcc0885f8be 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -73,12 +73,12 @@ attribute definition, in order to facilitate more intuitive and consistent API / SDK design. The standard attribute definition SHOULD be used to represent attributes in data -modeling unless there is a strong justification to diverge. For example, the log -data model has an extended [attributes](../logs/data-model.md#field-attributes) -definition allowing values of type `Any`. This reflects that log record -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. +modeling unless there is a strong justification to diverge. For example, the Log +Data Model has an extended [attributes](../logs/data-model.md#field-attributes) +definition allowing values of [type `Any`](../logs/data-model.md#type-any). This +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. ### Attribute Limits From b1d354056619ff545d8893e080f50d06dd532855 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Thu, 29 Feb 2024 10:31:36 -0600 Subject: [PATCH 5/5] Add explanation --- specification/common/README.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/specification/common/README.md b/specification/common/README.md index fcc0885f8be..ec7570c9c2c 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -62,8 +62,22 @@ See [Requirement Level](https://github.com/open-telemetry/semantic-conventions/b See [this document](attribute-type-mapping.md) to find out how to map values obtained outside OpenTelemetry into OpenTelemetry attribute values. -**[1]**: Note: extending the set of allowable attribute value types is a -breaking change. +**[1]**: NOTE: extending the set of 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. +* We proposed extending support for complex value types and received significant + pushback. Removing the bounds significantly increases the burden on data + consumers. Adding additional simple value types doesn't cause the same level + of burden, but these can be encoded using existing primitive types. For + example, datetime can be encoded as a string or 64 bit integer. +* Limiting attribute value types to primitives and arrays of primitives supports + OpenTelemetry's intent that attributes are metadata, and facilitates the + ability for data consumers to create search indexes and perform other + statistical analysis. ### Standard Attribute