Skip to content

OTEP: Extending attributes to support complex values#4485

Merged
lmolkova merged 63 commits intoopen-telemetry:mainfrom
trask:complex-attributes
Jul 15, 2025
Merged

OTEP: Extending attributes to support complex values#4485
lmolkova merged 63 commits intoopen-telemetry:mainfrom
trask:complex-attributes

Conversation

@lmolkova
Copy link
Copy Markdown
Member

@lmolkova lmolkova commented Apr 22, 2025

Related to #4468, #4414

This OTEP suggests a path forward on how to support complex attributes. It proposes to:

  • allow complex attributes on all signals by default on the API and SDK level
  • discourage them on metrics, resources, instrumentation scope, and identifying attributes on entities. If complex attribute is provided, it's probably by mistake, but we let backend decide.
  • provide guidance in semconv to default to flat attributes whenever possible and develop conventions with an assumption that complex attributes are not indexed, not queryable and not efficient.
  • documents how limits can apply to complex attributes (leaf nodes are counted towards the attribute count limit and are truncated based on the value limit) and suggests other ways to protect from users misusing complex attributes.

Having experimental phase for complex attributes limits the impact of this change and gives backends a graceful period to update.

Liudmila Molkova and others added 4 commits April 20, 2025 12:33
Comment thread oteps/XXXX-extending-attributes-to-support-complex-values.md Outdated
Comment thread oteps/XXXX-extending-attributes-to-support-complex-values.md Outdated
Comment thread oteps/XXXX-extending-attributes-to-support-complex-values.md Outdated
Comment thread oteps/XXXX-extending-attributes-to-support-complex-values.md Outdated
Comment thread oteps/XXXX-extending-attributes-to-support-complex-values.md Outdated
Comment thread oteps/XXXX-extending-attributes-to-support-complex-values.md Outdated
Liudmila Molkova and others added 2 commits April 22, 2025 07:58
Comment thread oteps/XXXX-extending-attributes-to-support-complex-values.md Outdated
Comment thread oteps/XXXX-extending-attributes-to-support-complex-values.md Outdated
Comment thread oteps/XXXX-extending-attributes-to-support-complex-values.md Outdated
Comment thread oteps/XXXX-extending-attributes-to-support-complex-values.md Outdated
@lmolkova lmolkova marked this pull request as ready for review April 22, 2025 22:45
@lmolkova lmolkova requested review from a team April 22, 2025 22:45
Copy link
Copy Markdown
Member

@pellared pellared left a comment

Choose a reason for hiding this comment

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

In general, LGTM. There are still some things that would be good to have clarified.

Comment thread oteps/4485-extending-attributes-to-support-complex-values.md Outdated
Comment thread oteps/4485-extending-attributes-to-support-complex-values.md Outdated
Comment thread oteps/4485-extending-attributes-to-support-complex-values.md
Comment thread oteps/4485-extending-attributes-to-support-complex-values.md Outdated
Comment thread oteps/4485-extending-attributes-to-support-complex-values.md Outdated
Comment thread oteps/4485-extending-attributes-to-support-complex-values.md
Comment thread oteps/4485-extending-attributes-to-support-complex-values.md Outdated
Liudmila Molkova added 2 commits July 8, 2025 12:39
…ents to implementations that allow using complex attrs on metrics, resources, entities, instr scope
@reyang reyang enabled auto-merge July 15, 2025 00:38
@trask trask disabled auto-merge July 15, 2025 00:46
@lmolkova lmolkova added this pull request to the merge queue Jul 15, 2025
Merged via the queue into open-telemetry:main with commit 8aa1d27 Jul 15, 2025
6 checks passed
@lmolkova lmolkova deleted the complex-attributes branch July 15, 2025 17:14
@github-project-automation github-project-automation Bot moved this from In Progress to Done in Go: Logs (GA) Jul 15, 2025
github-merge-queue Bot pushed a commit that referenced this pull request Aug 19, 2025
…hange (#4614)

Towards
#4602

Per OTEP:
https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/4485-extending-attributes-to-support-complex-values.md#why-doesnt-this-require-a-major-version-bump

This basically reverts:
-
#3858

Before we did not have a consensus to extend the attribute value types.
However, this has changed with:
-
#4485

Related proto PR:
- open-telemetry/opentelemetry-proto#683

**As a follow-up I plan to create issues in all language repositories so
that they can prepare their APIs and SDKs to extend the attribute value
types.**

---------

Co-authored-by: Trask Stalnaker <[email protected]>
@trask trask mentioned this pull request Nov 25, 2025
github-merge-queue Bot pushed a commit that referenced this pull request Jan 7, 2026
Fixes #4710

OTEP #4485 (Extending attributes to support complex values)

## What

Stabilize the complex `AnyValue` attribute value types and the
corresponding attribute limits.
Simplifiy the Logs Data Model to rely on `AnyValue` and Attribute
Collections instead of custom `any` / `map<string, any>` types.

## Why

Per the OTEP-implementing PR
[#4485](#4485)
tht was merged on **2025‑07‑15**, so the 6‑month window ends around
**2026‑01‑15**. This PR is intended to be merged around **2026‑01‑15**,
in line with that requirement.

> Stable exporters will be prohibited from emitting complex attributes
by default on signals other than Logs until at least 6 months after this
OTEP is merged.

OpenTelemetry **Go** and **Java** treat the common package as a **stable
cross‑cutting surface**. They need these `AnyValue` types and limits to
be Stable in the spec before they can add corresponding features to
their APIs, SDKs, and exporters.

## Prototypes

We have **three independent prototypes** that exercised the complex
`AnyValue` attribute types and limits:

- Java: open-telemetry/opentelemetry-java#7814 (
- Python:
open-telemetry/opentelemetry-python#4587
- Go: open-telemetry/opentelemetry-go#6809


In summary, they:

1. Validated that complex attributes can be represented and processed
end‑to‑end using `AnyValue`.
2. Confirmed that the specified attribute limits (length and count) are
acceptable.
3. Demonstrated that existing implementations can adopt complex
attributes without breaking current stable behavior.

## Other

I was thinking about adding something to `spec-compliance-matrix.md`,
but I do not see any obvious place where it could be located. I think we
can tackle it in a separate PR if there would be a demand for it.

EDIT: Tracked under
#4808
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.