Skip to content

Recommend JSON object encoding of an attribute for non-OTLP #5028

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jack-berg merged 23 commits into from
May 20, 2026
Merged

Recommend JSON object encoding of an attribute for non-OTLP #5028

Show file tree
Hide file tree
Changes from 12 commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
f7d265d
recommend JSON object encoding for attribute debugging
pellared Apr 15, 2026
cafff95
add PR number
pellared Apr 15, 2026
b7156b2
enhance examples
pellared Apr 20, 2026
864d0d7
Merge branch 'main' into key-anyvalue-tuple-representation
pellared Apr 20, 2026
33a3220
Merge branch 'main' into key-anyvalue-tuple-representation
pellared Apr 22, 2026
dc96379
Merge branch 'main' into key-anyvalue-tuple-representation
pellared Apr 24, 2026
6406205
Merge branch 'main' into key-anyvalue-tuple-representation
pellared Apr 24, 2026
dea3de4
Merge branch 'main' into key-anyvalue-tuple-representation
pellared Apr 27, 2026
dccd5bb
Avoid duplicating AnyValue non-OTLP encoding rules
pellared Apr 27, 2026
c04789f
refine section
pellared Apr 27, 2026
bc48da2
Update CHANGELOG.md
pellared Apr 27, 2026
6eb91fa
Merge branch 'main' into key-anyvalue-tuple-representation
pellared Apr 28, 2026
c3305ba
Update specification/common/README.md
pellared Apr 28, 2026
1f3c2e1
Update CHANGELOG.md
pellared Apr 28, 2026
e42169b
Merge branch 'main' into key-anyvalue-tuple-representation
pellared Apr 28, 2026
a29f6e1
Merge branch 'main' into key-anyvalue-tuple-representation
pellared Apr 29, 2026
43982ab
Merge branch 'main' into key-anyvalue-tuple-representation
pellared May 4, 2026
3d1ad40
Merge branch 'main' into key-anyvalue-tuple-representation
pellared May 7, 2026
f1c82d5
Merge branch 'main' into key-anyvalue-tuple-representation
pellared May 7, 2026
c319aac
Merge branch 'main' into key-anyvalue-tuple-representation
pellared May 18, 2026
48db8d3
Merge branch 'main' into key-anyvalue-tuple-representation
pellared May 18, 2026
dd5f562
Merge branch 'main' into key-anyvalue-tuple-representation
pellared May 19, 2026
31f06f9
Merge branch 'main' into key-anyvalue-tuple-representation
pellared May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,10 @@ release.

### Common

- Add in-development guidance recommending a JSON object as the string
representation for an attribute in non-OTLP or debugging contexts.
([#5028](https://github.com/open-telemetry/opentelemetry-specification/pull/5028))

### OpenTelemetry Protocol

### Compatibility
Expand Down
29 changes: 29 additions & 0 deletions specification/common/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Comment thread
bogdandrutu marked this conversation as resolved.

**Status**: [Development](../document-status.md)

For non-OTLP protocols or other debugging-oriented contexts that need to
Comment thread
pellared marked this conversation as resolved.
Outdated
represent a single `Attribute` as a string, the RECOMMENDED form is a

@jack-berg jack-berg May 13, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To me this seems duplicative of the "#### Maps" section on line 168. It already describes how to encode using what I believe is the same output.

An attribute set is analogous to a map. A single attribute is analogous to a single entry map.

Rather than repeating that section, could we make the (obvious) analogy between attributes and maps, and link over to the existing maps section for how it should be represented?

@pellared pellared May 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A single attribute is analogous to a single entry map.

Indeed. And this is what this section is specifying.

Rather than repeating that section, could we make the (obvious) analogy between attributes and maps, and link over to the existing maps section for how it should be represented?

I am not repeating the whole section. Note that this PR is already linking to the maps section.

Also note that e.g. https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/README.md#maps does not tell anything about the attribute name/value. I did my best to refer to the existing specification while also adding the missing parts. This is why this PR has e.g.

The attribute key SHOULD be represented as a JSON object member
name.

Other reviewers also asked to have more examples and have this section to be more clear (even it if is more verbose).

An attribute set is analogous to a map.

It is not specified anywhere. It a subject for a separate PR as we would need it for open-telemetry/opentelemetry-go#8209. I do not want to open large PRs and I plan to create it once this PR lands.

@jack-berg jack-berg May 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair enough - I approve.

[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
Comment thread
pellared marked this conversation as resolved.
> 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).
Comment thread
pellared marked this conversation as resolved.

### Attribute Collections

[Resources](../resource/sdk.md),
Expand Down
Loading