opentelemetry-sdk: add support for advisory attributes on metric instruments by herin049 · Pull Request #5444 · open-telemetry/opentelemetry-python

herin049 · 2026-07-20T01:27:25Z

Description

Adds support for Advisory Attributes metric instrument parameter.

Type of change

Please delete options that are not relevant.

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
This change requires a documentation update

How Has This Been Tested?

uv run tox -e py314-test-opentelemetry-sdk

Does This PR Require a Contrib Repo Change?

Yes. - Link to PR:
No.

Checklist:

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

…ruments

Copilot

Pull request overview

Adds support for metric instrument advisory attributes (per OTel Metrics API spec) by plumbing an _attributes_advisory parameter through the API and SDK instrument creation paths, and applying it during stream attribute selection when a View does not explicitly configure attribute_keys.

Changes:

Introduces _MetricsAdvisory(attributes=…, explicit_bucket_boundaries=…) as the unified advisory container and threads it through instrument construction/registration.
Applies advisory attribute filtering in _ViewInstrumentMatch when View.attribute_keys is not set.
Adds unit + integration test coverage for advisory attribute behavior and invalid advisory handling; updates changelog entry.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
opentelemetry-sdk/tests/metrics/test_view_instrument_match.py	Adds unit tests validating attribute selection precedence between View `attribute_keys` and instrument advisory attributes.
opentelemetry-sdk/tests/metrics/test_aggregation.py	Updates histogram advisory test to pass the new `_MetricsAdvisory` container.
opentelemetry-sdk/tests/metrics/integration_test/test_attributes_advisory.py	New integration tests covering advisory filtering across sync/async instruments, View interactions, and invalid advisory warnings.
opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/instrument.py	Adds `_advisory` storage on SDK instrument base classes and removes histogram-specific advisory init override.
opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/aggregation.py	Adjusts histogram aggregation boundary lookup to tolerate missing/non-histogram advisories.
opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/_view_instrument_match.py	Implements advisory-based attribute key filtering when View does not provide `attribute_keys`.
opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/init.py	Adds `_attributes_advisory` parameters to SDK Meter methods and validates/constructs `_MetricsAdvisory` for instruments.
opentelemetry-api/tests/metrics/test_meter.py	Updates API meter tests to include `_attributes_advisory` and verifies registration conflict behavior when advisory differs.
opentelemetry-api/tests/metrics/test_meter_provider.py	Updates proxy-meter forwarding assertions to include `_attributes_advisory=None`.
opentelemetry-api/src/opentelemetry/metrics/_internal/instrument.py	Introduces `_MetricsAdvisory` and threads `_attributes_advisory` through proxy instrument creation.
opentelemetry-api/src/opentelemetry/metrics/_internal/init.py	Extends Meter/NoOpMeter/proxy meter signatures to accept `_attributes_advisory` and includes advisory in registration/conflict tracking.
.changelog/5444.added	Adds changelog entry for advisory attributes support.

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

github-actions · 2026-08-14T03:53:23Z

This PR has been automatically marked as stale because it has not had any activity for 14 days. It will be closed if no further activity occurs within 14 days of this comment.
If you're still working on this, please add a comment or push new commits.

opentelemetry-pr-dashboard · 2026-08-14T16:52:58Z

Pull request dashboard status

Waiting on maintainers · refreshed 2026-11-03 04:17 UTC

Merge when ready.

Status above doesn't look right?

Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
Anything look wrong? Report it with what you expected; it helps us improve the dashboard.

tammy-baylis-swi · 2026-08-31T19:42:33Z

/dashboard route:author

So many PRs thank you. Please could the conflicts be resolved.

opentelemetry-pr-dashboard · 2026-08-31T20:23:47Z

@tammy-baylis-swi, /dashboard route:author is not a recognized dashboard command. The only supported command is /dashboard route:reviewers, which the pull request author can use to move a pull request from waiting on the author to waiting on reviewers.

…visory-attributes

…butes # Conflicts: # opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/_view_instrument_match.py

tammy-baylis-swi · 2026-09-21T19:19:27Z

/dashboard route:maintainers

opentelemetry-pr-dashboard · 2026-09-21T19:43:32Z

@tammy-baylis-swi, /dashboard route:maintainers is not a recognized dashboard command. The only supported command is /dashboard route:reviewers, which the pull request author can use to move a pull request from waiting on the author to waiting on reviewers.

herin049 · 2026-10-14T00:41:39Z

/dashboard route:reviewers

opentelemetry-pr-dashboard · 2026-10-14T00:42:38Z

@herin049, this pull request was routed to reviewers. The handoff remains active across pushes until newer actionable human feedback arrives. Top-level feedback through this request will not return; unresolved review threads remain open.

hectorhdzg · 2026-10-27T21:43:15Z

Sign in to view

+                    name,
+                    unit,
+                    description,
+                    _attributes_advisory=_attributes_advisory,


Small thing: the proxy meter now always passes _attributes_advisory to the real meter. A third-party Meter that doesn't accept it would raise a TypeError. Is that fine since it's a private param, or should we only pass it when it's set?

This is something I should have called out in the PR description. Technically adding these private params make this a breaking changes for custom SDK implementations. Even a basic create_counter with the new private attributes will result in a runtime error if the underlying SDK implementation doesn't support it. E.g.

# TypeError if API implementation doesn't accept `_attributes_advisory` counter = meter.create_counter("foo", _attributes_advisory=("fizz, buzz"))

That being said, this might be acceptable as long as we call it out. We've done similar changes before (e.g. in #4361).

Interestingly, the fact that this is a breaking change was never called out in #4361. @xrmx @aabmass @emdneto any thoughts here?

I think this falls into the same category of breakage we encountered in #3710. Indeed, #4361 introduced a similar change, though i don’t recall any issues being reported. Since this PR affects all instrument types, the potential impact is broader than 4361. maybe Could we omit _attributes_advisory when it’s None to preserve compatibility with existing Meter implementations and adopt this strategy moving forward? A proper notice in the changelog would be nice either way

Here is a possible solution: herin049#1

However, the latter case is much more acceptable.

Could you say more? Is it just that it's not breaking until the caller actually starts passing the new param?

(BTW, I think we might want to consider making the signatures in the Logging API forward compatible to avoid this kind of problem)

Is it just that it's not breaking until the caller actually starts passing the new param?

Yes exactly, say I install opentelemetry-api==1.46.0 I see that I can use the new _attributes_advisory (the signature says I can). The ProxyMeter will initially accept it, but once the true Meter is resolved, it will crash.

counter = meter.create_counter("foo", _attributes_advisory=("fizz, buzz"))

This is more acceptable in my eyes, and should be very rare in practice. This can't happen between the API and SDK for example because we pin the API version we use (i.e. API and SDK are in lockstep). This only would occur with third-party SDKs. And if you're using a third-party SDK, you will probably know not to use functionality which you haven't implemented in that third-party SDK anyway.

I've updated the PR to also only forward non-None additional keyword arguments in the ProxyMeter, this makes the more dangerous case impossible now.

(BTW, I think we might want to consider making the signatures in the Logging API forward compatible to avoid this kind of problem)

I was thinking along similar lines 😆

FYI @aabmass: #5851

lzchen · 2026-10-28T16:55:57Z

+class HistogramOptions(InstrumentOptions):
+    """Optional keyword arguments accepted by ``Meter.create_histogram``."""
+
+    explicit_bucket_boundaries_advisory: NotRequired[Sequence[float]]


Nit: Should the typing be NotRequired[Sequence[float]] | None to accept None values as well, just to be consistent with the previous typing?

Unless we want to allow type checking to pass when users manually use explicit_bucket_boundaries_advisory=None, this should be correct. NotRequired[T] allows omitting the key from the kwargs dict, but if it is provided it must be of type T. If we want to allow the prior case, we should make it NotRequired[Sequence[float] | None].

dashpole

LGTM! I audited the exemplar behavior and it correctly preserves dropped attributes in filtered_attributes, which aligns with open-telemetry/opentelemetry-specification#5392.

opentelemetry-sdk: add support for advisory attributes on metric inst…

c1fae2b

…ruments

herin049 requested a review from a team as a code owner July 20, 2026 01:27

otelbot-python Bot added this to Python PR digest Jul 20, 2026

add changelog fragment

e6b4ad2

herin049 requested a review from Copilot July 20, 2026 01:28

herin049 added Approve Public API check This label shows that the public symbols added or changed in a PR are strictly necessary metrics labels Jul 20, 2026

Copilot started reviewing on behalf of herin049 July 20, 2026 01:28

View session

Copilot AI reviewed Jul 20, 2026

View reviewed changes

Comment thread opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/__init__.py Resolved

Comment thread opentelemetry-api/src/opentelemetry/metrics/_internal/instrument.py Resolved

herin049 and others added 4 commits July 19, 2026 21:32

fix formatting

4b62a31

update '_validate_explicit_bucket_boundaries_advisory' to return a tuple

5be3e39

Merge branch 'main' into feat/advisory-attributes

17341cc

Merge branch 'main' into feat/advisory-attributes

dc69790

github-actions Bot added the Stale label Aug 14, 2026

opentelemetry-pr-dashboard Bot mentioned this pull request Aug 14, 2026

Pull Request Dashboard #5550

Open

tammy-baylis-swi moved this to Reviewed PRs that need fixes in Python PR digest Aug 31, 2026

github-actions Bot removed the Stale label Sep 1, 2026

herin049 and others added 4 commits September 1, 2026 20:08

Merge commit '0110bb1d273dbe848312d429326b844da9e86d93^' into feat/ad…

e812378

…visory-attributes

chore: merge Ruff 120 reformat and format branch

17c0bea

Merge remote-tracking branch 'upstream/main' into feat/advisory-attri…

cc909f5

…butes # Conflicts: # opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/_view_instrument_match.py

Merge branch 'main' into feat/advisory-attributes

d539dec

tammy-baylis-swi approved these changes Sep 21, 2026

View reviewed changes

github-project-automation Bot moved this from Reviewed PRs that need fixes to Approved PRs in Python PR digest Sep 21, 2026

Merge branch 'main' into feat/advisory-attributes

5c34019

Merge branch 'main' into feat/advisory-attributes

2a71dc0

Merge branch 'main' into feat/advisory-attributes

0e93798

This was referenced Oct 27, 2026

Stabilize "attributes" instrument advisory parameter open-telemetry/opentelemetry-specification#3785

Open

Stabilize Attributes instrument advisory parameter open-telemetry/opentelemetry-specification#5393

Draft

hectorhdzg reviewed Oct 27, 2026

View reviewed changes

ocelotl mentioned this pull request Oct 28, 2026

opentelemetry-api: forward the attributes advisory only when it is set herin049/opentelemetry-python#1

Open

herin049 and others added 5 commits October 27, 2026 22:25

update instrument creation signatures

afc0e41

update changelog entry

f2ea24d

Merge branch 'main' into feat/advisory-attributes

2103a8f

make options types public

feb1941

remove type checking guard for Unpack/NotRequired

97f3544

lzchen reviewed Oct 28, 2026

View reviewed changes

hectorhdzg approved these changes Oct 28, 2026

View reviewed changes

dashpole self-requested a review November 1, 2026 19:12

herin049 mentioned this pull request Nov 1, 2026

Enhancement: Add forward compatible instrument creation APIs #5877

Open

herin049 and others added 2 commits November 1, 2026 21:52

switch to using per-instrument create_*_with_options(...) methods

4c1d8b1

Merge branch 'main' into feat/advisory-attributes

b71703c

herin049 mentioned this pull request Nov 2, 2026

feat(metrics): add experimental _opt_in_advisory and View enabled parameter #5847

Draft

switch from _MetricsAdvisory to _InstrumentAdvisory

92b1792

dashpole approved these changes Nov 2, 2026

View reviewed changes

Conversation

herin049 commented Jul 20, 2026

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!

github-actions Bot commented Aug 14, 2026

Uh oh!

opentelemetry-pr-dashboard Bot commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request dashboard status

Uh oh!

tammy-baylis-swi commented Aug 31, 2026

Uh oh!

opentelemetry-pr-dashboard Bot commented Aug 31, 2026

Uh oh!

tammy-baylis-swi commented Sep 21, 2026

Uh oh!

opentelemetry-pr-dashboard Bot commented Sep 21, 2026

Uh oh!

herin049 commented Oct 14, 2026

Uh oh!

opentelemetry-pr-dashboard Bot commented Oct 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

herin049 Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

emdneto Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

This comment was marked as spam.

Uh oh!

herin049 Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

dashpole left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

opentelemetry-pr-dashboard Bot commented Aug 14, 2026 •

edited

Loading

herin049 Oct 27, 2026 •

edited

Loading

emdneto Oct 28, 2026 •

edited

Loading

herin049 Oct 28, 2026 •

edited

Loading

dashpole left a comment •

edited

Loading