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..

aabmass · 2026-07-24T19:56:35Z

+                # Calling str(x) will use an object's `__str__` method if it exists, otherwise it will use it's `__repr__` method.
+                # If neither is defined it uses the base class's `object.__repr__` method, which returns a string that is hard to understand.
+                # So in that case we drop the key/value pair.
+                if (
+                    type(key).__str__ is not object.__str__
+                    or type(key).__repr__ is not object.__repr__
+                ):
+                    key = str(key)
+                else:
+                    continue


IMO it would be much more readable to just try to call str() and continue in the except block like we did before. Any strong reason for this pattern?

aabmass · 2026-07-24T19:56:57Z

+    if (
+        type(value).__str__ is not object.__str__
+        or type(value).__repr__ is not object.__repr__
+    ):


same comment here

aabmass · 2026-07-24T20:00:38Z

+                val, max_string_value_length
+            )
+        return MappingProxyType(cleaned_mapping)
    _logger.warning(


Can you add an exhaustiveness check?

We used this pattern to avoid raising an AssertionError at runtime

opentelemetry-python/exporter/opentelemetry-exporter-otlp-json-common/src/opentelemetry/exporter/otlp/json/common/_internal/metrics_encoder/__init__.py

Lines 143 to 144 in 4ea521a

if TYPE_CHECKING:

assert_never(metric.data)

aabmass · 2026-07-24T20:10:11Z

        return f"{dict(self._dict)}"

-    def __getitem__(self, key: str) -> types.AnyValue:
+    def __getitem__(self, key: str) -> types.AttributeValue:


nit as they are now aliases of each other, but can you make it consistent to use AttributeValue or AnyValue and not mix?

aabmass · 2026-07-24T20:10:49Z

-    key: str, value: types.AnyValue, max_len: int | None
-) -> types.AnyValue:
-    """Checks if attribute value is valid and cleans it if required.
+class BoundedAttributes(MutableMapping):


Suggested change

class BoundedAttributes(MutableMapping):

class BoundedAttributes(MutableMapping[str, AnyValue]):

not sure why pyright isn't complaining

aabmass · 2026-07-24T21:00:52Z

    pass

-LabelValue = AttributeValue
-Attributes = Mapping[str, LabelValue]


We should leave this to avoid breaking the public API 😕

aabmass · 2026-07-24T21:01:18Z

+        # Immutable set to true so attributes cannot be added or removed after creation.
+        self._attributes = BoundedAttributes(
+            attributes=attributes, immutable=True
+        )


Immutable doesn't seem relevant to this PR, can you split this out?

aabmass · 2026-07-24T21:04:55Z

Same comment about immutable, unless im misunderstanding.

aabmass · 2026-07-24T21:07:54Z

IIRC we added this to a pyi instead of the main py file because of some bugs in mypy. I agree we should try to collapse it back into the normal py file but can we do it in a separate PR?

(You should also merge some of the information in this pyi in the py file, for example ns_to_iso_str() is still untyped in the py file)

aabmass · 2026-07-24T21:08:28Z

            schema_url = ""
        self._schema_url = schema_url
-        self._attributes = BoundedAttributes(attributes=attributes)
+        # Attributes cannot be added/removed after creation.


same comment

aabmass · 2026-07-24T21:15:31Z

    | None
 )
-
-AttributeValue = (


Please leave to avoid breaking public API. We can mark them deprecated in a comment or docstring

aabmass · 2026-07-24T21:15:36Z

-    | Sequence[float]
-)
-Attributes = Mapping[str, AttributeValue] | None
-AttributesAsKey = tuple[


Please leave to avoid breaking public API. We can mark them deprecated in a comment or docstring

aabmass · 2026-07-24T21:22:01Z

-]
-
-_ExtendedAttributes = Mapping[str, "AnyValue"]
+Attributes = Mapping[str, AnyValue] | None


One subtle detail here is when this used as a return value, it is technically breaking users since we made the type more permissive.

For example, exporters now need to handle more variants of attribute types when serializing. I don't think there is any way around this but we should add it to the changelog IMO.

I wonder what other languages are doing to absorb this change to support complex attributes @lmolkova?

Oops I see Mike left a similar resolved comment https://github.com/open-telemetry/opentelemetry-python/pull/5266/changes/BASE..036b621be41a976af8fbded16e2f8670e1585858#r3376099968

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 added 2 commits June 18, 2026 16:40

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 6 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

Merge branch 'main' into extended_attributes

01f0df8

Merge branch 'main' into extended_attributes

036b621

aabmass reviewed Jul 24, 2026

View reviewed changes

aabmass moved this from Approved PRs to Approved PRs that need fixes in Python PR digest Jul 24, 2026

aabmass reviewed Jul 24, 2026

View reviewed changes

	class BoundedAttributes(MutableMapping):
	class BoundedAttributes(MutableMapping[str, AnyValue]):

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

DylanRussell commented Jun 1, 2026 •

edited

Loading