diff --git a/CHANGELOG.md b/CHANGELOG.md index 64b4bbd65f2..1cac5296d42 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,6 +31,9 @@ release. ### Common +- Add in-development guidance recommending a JSON object as the string + representation for an attribute in non-OTLP protocols. + ([#5028](https://github.com/open-telemetry/opentelemetry-specification/pull/5028)) - Define the Core packages term. ([#5046](https://github.com/open-telemetry/opentelemetry-specification/pull/5046)) diff --git a/specification/common/README.md b/specification/common/README.md index 282ec85faf5..599e2190afa 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -27,6 +27,7 @@ path_base_for_github_subdir: + [Arrays](#arrays) + [Maps](#maps) - [Attribute](#attribute) + * [Attribute representation for non-OTLP](#attribute-representation-for-non-otlp) * [Attribute Collections](#attribute-collections) - [Attribute Limits](#attribute-limits) * [Configurable Parameters](#configurable-parameters) @@ -195,6 +196,34 @@ 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. +### Attribute representation for non-OTLP + +**Status**: [Development](../document-status.md) + +For non-OTLP protocols that need to +represent a single `Attribute` as a string, the RECOMMENDED form is a +[JSON object](https://datatracker.ietf.org/doc/html/rfc8259#section-4) +containing a single name/value pair (member). + +The attribute key SHOULD be represented as a JSON object member +name. + +The attribute value SHOULD be represented as a JSON object member value and +follow the encoding rules defined in +[AnyValue representation for non-OTLP protocols](#anyvalue-representation-for-non-otlp-protocols), +as it would be represented as an element in an [array](#arrays) and a value in +a [map](#maps). + +Examples: `{"http.request.method": "GET"}`, `{"retries": 3}`, +`{"payload": "aGVsbG8gd29ybGQ="}`, `{"session.id": null}`, +`{"colors": ["red", "blue"]}`, `{"context": {"nested": true}}` + +> [!NOTE] +> This string representation is lossy. Type information is lost as all +> values are converted to strings, and precision loss may occur for numeric values +> (particularly for floating point numbers and large integers that exceed the +> precision capabilities of the receiving system's string-to-number conversion). + ### Attribute Collections [Resources](../resource/sdk.md),