Expand `attribute` value type to support complex values everywhere and cleanup surrounding code by DylanRussell · Pull Request #5266 · open-telemetry/opentelemetry-python

DylanRussell · 2026-06-01T20:00:27Z

Description

This PR updates the code to support complex values everywhere as described in this OTEP -- basically it adds support for None type, Bytes type, heterogeneous arrays, and maps as attribute values.

I cleaned up the surrounding code, including refactoring BoundedAttributes.. this was in part possible because we no longer have to support 2 sets of attribute values.

BoundedAttributes is a dictionary sublcass used in the SDK for setting/storing/getting attributes. It's used for span attributes (and span event attributes and span link attributes), log attributes, instrumentation scope attributes, and resource attributes, but i think it's completely optional for metric points -- all the various metric point classes just accept a generic attributes value, and I think it's up to instrumentations to decide on whether to use it or not.. I don't see any guidance requiring people do it, and I don't see any usages of BoundedAttributes in contrib.

For the bytes type I just pass that through as is.. Currently we do that for Extended attributes but not regular attributes (which I'm removing), for regular attributes it was decided to a utf-8 string.. But bytes is a valid AnyValue that can be encoded as bytes in the OTLP proto, and we don't know how it was encoded, so I think passing it through makes the most sense..

Some minor follow up work is tracked in #5304

I believe the failing Public Symbols check is acceptable, it is due to:

expanding the Attributes type (additive change, should be acceptable.)
Removing AttributesAsKey type (unused in this repo and contrib, doesn't make sense as a type..)
Removing a very stale .pyi file in the SDK (opentelemetry-sdk/src/opentelemetry/sdk/util/__init__.pyi).

Type of change

Please delete options that are not relevant.

[ x] New feature (non-breaking change which adds functionality)

How Has This Been Tested?

Unit tests

Does This PR Require a Contrib Repo Change?

Yes I had to submit open-telemetry/opentelemetry-python-contrib#4646 -- if someone attempts to use an old (anything less than the next release of) opentelemetry-instrumentation-logging with the next release of opentelemetry-api it will not work.. I'm confused about what to do to resolve that issue though..

Checklist:

[ x] Followed the style guidelines of this project
[ x] Changelogs have been updated
[ x] Unit tests have been added
[ x] Documentation has been updated

Copilot

Pull request overview

This PR expands OpenTelemetry Python’s attribute value model across the API, SDK, and OTLP exporters to support “complex” values everywhere (e.g., None, heterogeneous arrays, and maps), aligning behavior with the referenced OTEP and updating surrounding utilities/tests accordingly.

Changes:

Broadens AnyValue/AttributeValue/Attributes typing and updates public API surfaces (tracing/logs/events/metrics) to accept complex attribute values.
Refactors attribute cleaning/storage (BoundedAttributes) and metric attribute-keying (_hash_attributes) to handle complex values consistently.
Updates OTLP proto/json encoding to represent None as an empty AnyValue and adjusts unit tests/benchmarks for the new semantics.

Reviewed changes

Copilot reviewed 31 out of 31 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
opentelemetry-sdk/tests/trace/test_trace.py	Updates span attribute/event tests for complex values and bytes behavior.
opentelemetry-sdk/tests/resources/test_resources.py	Updates resource attribute validation tests for new cleaning/stringify behavior.
opentelemetry-sdk/tests/metrics/test_view_instrument_match.py	Updates metrics tests to use `_hash_attributes` aggregation keys.
opentelemetry-sdk/tests/metrics/test_measurement_consumer.py	Adjusts a concurrency test to pass attributes explicitly.
opentelemetry-sdk/src/opentelemetry/sdk/util/instrumentation.py	Switches instrumentation scope attributes typing to `Attributes`.
opentelemetry-sdk/src/opentelemetry/sdk/resources/init.py	Aligns resource attribute typing/imports with new `Attributes` definition.
opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/_view_instrument_match.py	Introduces `_hash_attributes` and deep-copies measurement attributes prior to aggregation.
opentelemetry-sdk/src/opentelemetry/sdk/environment_variables/init.py	Clarifies docs for attribute value length limits with string/bytes focus.
opentelemetry-sdk/src/opentelemetry/sdk/_logs/_internal/_exceptions.py	Updates exception-attribute merging to the unified `Attributes` type.
opentelemetry-sdk/src/opentelemetry/sdk/_logs/_internal/init.py	Updates logging translation checks/warnings for AnyValue casting.
opentelemetry-sdk/src/opentelemetry/sdk/_events/init.py	Updates event logger provider attribute typing to `Attributes`.
opentelemetry-sdk/benchmarks/metrics/test_benchmark_metrics_histogram.py	Expands benchmarks to cover complex/mapping/array attribute shapes.
opentelemetry-api/tests/logs/test_proxy.py	Updates logs proxy tests to `Attributes`.
opentelemetry-api/tests/events/test_proxy_event.py	Updates events proxy tests to `Attributes`.
opentelemetry-api/tests/attributes/test_attributes.py	Reworks attribute tests around new `_clean_attribute_value`/`BoundedAttributes`.
opentelemetry-api/src/opentelemetry/util/types.py	Redefines `AnyValue`/`AttributeValue` and widens `Attributes` accordingly; removes `_ExtendedAttributes`.
opentelemetry-api/src/opentelemetry/trace/span.py	Updates span API type hints to use `collections.abc.Mapping` and `types.Attributes` in NoOp implementation.
opentelemetry-api/src/opentelemetry/attributes/init.py	Major refactor: new recursive cleaner and `BoundedAttributes` as a `dict` subclass.
opentelemetry-api/src/opentelemetry/_logs/_internal/init.py	Updates log API typing from `_ExtendedAttributes` to `Attributes`.
opentelemetry-api/src/opentelemetry/_events/init.py	Updates event API typing from `_ExtendedAttributes` to `Attributes`.
exporter/opentelemetry-exporter-otlp-proto-grpc/benchmarks/test_benchmark_trace_exporter.py	Updates patch target to `TraceServiceStub`.
exporter/opentelemetry-exporter-otlp-proto-common/tests/test_log_encoder.py	Refactors OTLP proto log encoder tests around new null/AnyValue behavior.
exporter/opentelemetry-exporter-otlp-proto-common/tests/test_attribute_encoder.py	Adjusts encoder failure tests to use an unencodable object.
exporter/opentelemetry-exporter-otlp-proto-common/src/opentelemetry/exporter/otlp/proto/common/_internal/_log_encoder/init.py	Stops using `allow_null`; encodes null as empty `AnyValue`.
exporter/opentelemetry-exporter-otlp-proto-common/src/opentelemetry/exporter/otlp/proto/common/_internal/init.py	Simplifies `_encode_value` and `_encode_attributes` around null-as-empty-AnyValue.
exporter/opentelemetry-exporter-otlp-json-common/tests/test_log_encoder.py	Updates JSON log encoder tests for null-as-empty-AnyValue body.
exporter/opentelemetry-exporter-otlp-json-common/tests/test_common_encoder.py	Updates JSON common encoder tests for null and unencodable values.
exporter/opentelemetry-exporter-otlp-json-common/src/opentelemetry/exporter/otlp/json/common/_internal/_log_encoder/init.py	Removes `allow_null` usage in JSON log encoding.
exporter/opentelemetry-exporter-otlp-json-common/src/opentelemetry/exporter/otlp/json/common/_internal/init.py	Simplifies `_encode_value` and `_encode_attributes` around null-as-empty-AnyValue.
docs/conf.py	Updates Sphinx type-hint resolution aliasing; now also touches metrics internals.
.changelog/5266.added	Adds changelog entry for extended/complex attribute support across packages.

Comments suppressed due to low confidence (1)

opentelemetry-api/src/opentelemetry/trace/span.py:96

The note in Span.set_attributes says the behavior of None value attributes is undefined, but this PR explicitly adds support for None/null attribute values across the API/SDK. Please update the docstring to reflect the new supported semantics (even if None remains discouraged).

    def set_attributes(
        self, attributes: Mapping[str, types.AttributeValue]
    ) -> None:
        """Sets Attributes.

        Sets Attributes with the key and value passed as arguments dict.

        Note: The behavior of `None` value attributes is undefined, and hence
        strongly discouraged. It is also preferred to set attributes at span
        creation, instead of calling this method later since samplers can only
        consider information already present during span creation.
        """

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

DylanRussell · 2026-06-18T16:57:55Z

This is ready for another review now.. That other PR has been merged into main, and I've merged that main into this PR..

DylanRussell added 11 commits May 21, 2026 20:29

Initial changes..

28901b2

Make lots of changes

55af143

Merge branch 'main' into extended_attributes

f9a9600

Fix tests, run precommit

aee7365

Fix more tests

66d3d12

Run precommit

30df0bd

Fix more tests

ca0a0e4

Refactor clean attributes code and tests..

d73d251

Add more test coverage.. Still need to get the type checker passing.

98fb897

Refactor BoundedAttributes again.. Fix lots of tests

99ae2f7

Fix lint issues

a26a6ef

DylanRussell requested a review from a team as a code owner June 1, 2026 20:00

otelbot-python Bot added this to Python PR digest Jun 1, 2026

DylanRussell added 8 commits June 1, 2026 20:21

Fix lint issues, spellcheck issues, add changelog

52fe1df

Fix typo

e6b09c9

Fix __iter__

796121d

Remove log warning.. add msg to TypeError

1f9c0a7

Clean up BoundedAttributes

bde6f6b

Remove encoding of Bytes. Fix tests..

faeeefe

Revert lock file

f35002d

Fix busted tests

bfebcac

DylanRussell mentioned this pull request Jun 2, 2026

Fix broken botocore tests, minor change to HTTPX instrumentation test, remove _ExtendedAttributes import from logging instrumentation open-telemetry/opentelemetry-python-contrib#4646

Merged

DylanRussell added 2 commits June 2, 2026 18:45

Add commnet retrigger CI

588ffef

Minor fixes..

eb12236

DylanRussell mentioned this pull request Jun 2, 2026

Issues with OTLP exporter with None values #5211

Open

DylanRussell requested a review from Copilot June 3, 2026 15:21

Copilot started reviewing on behalf of DylanRussell June 3, 2026 15:21 View session

Merge branch 'main' into extended_attributes

ff58266

Copilot AI reviewed Jun 3, 2026

View reviewed changes

Clarify immutability

22bb59e

DylanRussell and others added 3 commits June 17, 2026 14:34

FIx precommit. bunch of minor cleanup

ba41e8d

Clarify params

d90d193

Merge branch 'main' into extended_attributes

c298055

DylanRussell mentioned this pull request Jun 18, 2026

[genai-utils] Remove all usages of typing.Any open-telemetry/opentelemetry-python-genai#41

Closed

DylanRussell added 3 commits June 18, 2026 16:37

Merge branch 'main' into extended_attributes

61f27c0

Missing import

36b9980

Minor changes..

1a05554

DylanRussell added 3 commits June 22, 2026 10:15

Merge branch 'main' into extended_attributes

5557b3a

Merge branch 'main' into extended_attributes

8da4810

Merge branch 'main' into extended_attributes

a09c06f

herin049 reviewed Jun 27, 2026

View reviewed changes

Comment thread opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/_view_instrument_match.py Outdated

herin049 reviewed Jun 27, 2026

View reviewed changes

Comment thread opentelemetry-sdk/src/opentelemetry/sdk/util/__init__.pyi

herin049 approved these changes Jun 27, 2026

View reviewed changes

DylanRussell added 5 commits July 7, 2026 18:17

Merge branch 'main' into extended_attributes

1043698

Add immutable back..

ac0fc88

Fix broken test

bb8064d

Add comment to Measurement class

80b79eb

Fix broken test

16def67

DylanRussell moved this from Reviewed PRs that need fixes to Approved PRs in Python PR digest Jul 7, 2026

DylanRussell and others added 4 commits July 8, 2026 11:39

Merge branch 'main' into extended_attributes

d7e5dd5

Merge branch 'main' into extended_attributes

de893a3

Merge branch 'main' into extended_attributes

daa8213

Merge branch 'main' into extended_attributes

5da6780

tammy-baylis-swi mentioned this pull request Jul 16, 2026

fix: support sequence metric attributes in view aggregation keys #5341

Open

herin049 mentioned this pull request Jul 19, 2026

BoundedAttributes: _clean_extended_attribute returns None for both invalid input and valid AnyValue(None), causing invalid attributes to be written instead of dropped #5432

Open

DylanRussell and others added 4 commits July 20, 2026 09:35

Merge branch 'main' into extended_attributes

5c234d6

Add helper method raise_if_immutable

8220ee5

update _set_items to check if key is a string

7b7706b

Fix pre commit

588d310

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Expand `attribute` value type to support complex values everywhere and cleanup surrounding code#5266

Expand `attribute` value type to support complex values everywhere and cleanup surrounding code#5266
DylanRussell wants to merge 67 commits into
open-telemetry:mainfrom
DylanRussell:extended_attributes

DylanRussell commented Jun 1, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DylanRussell commented Jun 18, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Uh oh!

Conversation

DylanRussell commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

How Has This Been Tested?

Does This PR Require a Contrib Repo Change?

Checklist:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DylanRussell commented Jun 18, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

DylanRussell commented Jun 1, 2026 •

edited

Loading