PoC: widen 'Attributes' to support the extended AnyValue by trentm · Pull Request #6579 · open-telemetry/opentelemetry-js

trentm · 2026-04-10T01:10:57Z

Current status

This is a hacked-up proof of concept, to explore whether support for complex/extended attributes could be accomplished without a separate attributes type in the API.

Can we widen interface Attributes, and update the SDK package's usage of attributes?
Code-wise, I think this change so far shows: yes.

The big Q is whether this would be considered a breaking change in the API for users/instrumentations.
Possibly it could surprise code in SDK implementors, but they should be limiting on max API minor ver already. (FWIW, the sanitizeAttributes() already in the SDK packages now safely handle incoming attributes. The SDK was already necessarily defensive in checking the given attribute keys and values for validity.)

Refs: open-telemetry#6349

trentm · 2026-04-10T17:33:25Z

For reference OTel Spec 1.49.0 includes:

"IMPORTANT: Extending the set of standard attribute value types is no longer a breaking change."

https://github.com/open-telemetry/opentelemetry-specification/blob/main/CHANGELOG.md#v1490-2025-09-16
open-telemetry/opentelemetry-specification#4614
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

… all of this needs to be part of *this* PR work

…ibuteValue (now deprecated) because AnyValue is in the spec for more than just attributes (e.g. LogRecord#body)

…d attributes in sdk-metrics (keyObjFromAnyValue util in core package)

trentm

Add some notes to self, and for reviews.

trentm · 2026-04-10T22:19:09Z

   * @param [options] the metric options.
   */
-  createGauge<AttributesTypes extends MetricAttributes = MetricAttributes>(
+  createGauge<AttributesTypes extends Attributes = Attributes>(


Q: What is the <AttributesTypes extends ...> generic on Instruments for?

trentm · 2026-04-10T22:19:59Z

   * @param [options] the metric options.
   */
-  createHistogram<AttributesTypes extends MetricAttributes = MetricAttributes>(
+  createHistogram<AttributesTypes extends Attributes = Attributes>(


There are a lot of s/{Metric,Span}Attributes/Attributes/ changes in the PR that could be done in a separate PR to make it smaller. I may end up separating them to help reviews.

trentm · 2026-04-10T22:20:41Z

+  attributes?: Attributes;
+  // XXX A bit silly/incorrect to have this dropped count on the `Link` type
+  //     used by Span#addLink. The user is not meant to specify this count.
+  //     We could deprecate this, and then cope in the SDK.


This is totally for a separate PR. This is a note to self.

trentm · 2026-04-10T22:21:37Z

+// TODO: Remove ProxyTracerProvider export in the next major version.
+export { ProxyTracerProvider } from './trace/ProxyTracerProvider';
+export type { Sampler } from './trace/Sampler';
+export { SamplingDecision, type SamplingResult } from './trace/SamplingResult';


This belongs in a separate PR, if at all. I did this as I was working through the full API to grok usage of Attributes/AnyValue.

trentm · 2026-04-10T22:22:33Z

+  return isAttributeValueInternal(val, new WeakSet());
+}
+
+function isAttributeValueInternal(


This impl is mostly from the current sdk-logs, e.g.: isLogAttributeValueInternal().

trentm · 2026-04-10T22:23:21Z

+// XXX Want a version without limits: resources and metrics are exempt: https://opentelemetry.io/docs/specs/otel/common/#exempt-entities
+// XXX Having to pass around attribute count (currentAttributesCount, etc.) is a pain. Not suggesting it now, because more work, but using a Map would be nice for the API.
+// XXX Consider moving diag.warn()s out to caller.
+export function addAttribute(


This impl is from Marc's https://github.com/open-telemetry/opentelemetry-js/pull/6573/changes#diff-b9c349741ba9d65deb917bfda167c88913970a8f9d1784a133013cd8d1972cc9R79

trentm · 2026-04-10T22:24:26Z

+    // XXX use normalizeAttributes, keep droppedAttributeCount values,
+    //     separate from the `links` sent to shouldSample. Then pass links
+    //     *with* droppedAttributeCount to SpanImpl, which accepts those.
+    //     I.e. SpanImpl type shoudl be `Array<Link & {droppedAttributeCount?: number}>`


This belongs in a separate PR.

trentm · 2026-04-10T22:25:11Z

+  // XXX Should this be defensively dropping attributes with invalid type?
+
+  const keyObj = keyObjFromAnyValue(attributes);
+  return JSON.stringify(keyObj);


I think this hashAttributes is the only "handling" of Attributes that is need to update sdk-metrics to support complex attributes.

codecov · 2026-04-10T23:12:51Z

Codecov Report

❌ Patch coverage is 90.00000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.51%. Comparing base (87d0112) to head (34f8ee8).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
api/src/metrics/NoopMeter.ts	75.00%	1 Missing ⚠️
packages/opentelemetry-sdk-trace-base/src/Span.ts	92.85%	1 Missing ⚠️

❗ There is a different number of reports uploaded between BASE (87d0112) and HEAD (34f8ee8). Click for more details.

HEAD has 17 uploads less than BASE

Flag BASE (87d0112) HEAD (34f8ee8)

18 1

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6579      +/-   ##
==========================================
- Coverage   95.74%   89.51%   -6.24%     
==========================================
  Files         375       84     -291     
  Lines       12704     1994   -10710     
  Branches     2998      417    -2581     
==========================================
- Hits        12164     1785   -10379     
+ Misses        540      209     -331

Files with missing lines	Coverage Δ
api/src/metrics/Metric.ts	`100.00% <ø> (ø)`
api/src/trace/NonRecordingSpan.ts	`95.83% <100.00%> (ø)`
api/src/trace/SamplingResult.ts	`100.00% <ø> (ø)`
...ackages/opentelemetry-sdk-trace-base/src/Tracer.ts	`98.71% <ø> (ø)`
api/src/metrics/NoopMeter.ts	`95.34% <75.00%> (ø)`
packages/opentelemetry-sdk-trace-base/src/Span.ts	`98.32% <92.85%> (+0.01%)`	⬆️

... and 297 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

trentm · 2026-04-10T23:26:35Z

instr-http tests are failing on a deepStrictEqual of span.attributes where a span's attributes include:

    'user_agent.original': undefined

We will need to discuss whether we actually want to allow the undefined "empty" value in JavaScript's AnyValue.
I suspect it is fairly common usage currently to set attributes objects with possibly-undefined values (for convenience), on the assumption that those values will get removed during serialization. E.g.:

opentelemetry-js/experimental/packages/opentelemetry-instrumentation-http/src/utils.ts

Lines 467 to 489 in d185ad4

    
           const userAgent = headers['user-agent']; 
        
           const urlFull = getAbsoluteUrl( 
        
             requestOptions, 
        
             headers, 
        
             `${options.component}:`, 
        
             options.redactedQueryParams 
        
           ); 
        
           const oldAttributes: Attributes = { 
        
             [ATTR_HTTP_URL]: urlFull, 
        
             [ATTR_HTTP_METHOD]: method, 
        
             [ATTR_HTTP_TARGET]: requestOptions.path || '/', 
        
             [ATTR_NET_PEER_NAME]: hostname, 
        
             [ATTR_HTTP_HOST]: headers.host ?? `${hostname}:${port}`, 
        
           }; 
        
           const newAttributes: Attributes = { 
        
             // Required attributes 
        
             [ATTR_HTTP_REQUEST_METHOD]: normalizedMethod, 
        
             [ATTR_SERVER_ADDRESS]: hostname, 
        
             [ATTR_SERVER_PORT]: Number(port), 
        
             [ATTR_URL_FULL]: urlFull, 
        
             [ATTR_USER_AGENT_ORIGINAL]: userAgent,

The spec https://opentelemetry.io/docs/specs/otel/common/#anyvalue says:

an empty value if supported by the language, (e.g. null, undefined in JavaScript/TypeScript, None in Python, nil in Go/Ruby, not supported in Erlang, etc.)

But my guess is this wasn't fully vetted.
I haven't checked if the sdk-logs tests actually test for an undefined value on an attribute (or on LogRecord#body).

pichlermarc · 2026-04-29T15:49:27Z

I mentioned that there's some ways to demonstrate why this is a breaking change.
I found that there's really only one way to demonstrate it and everything else is a variation of that one issue:

This is the type of code that compiles with the previous attribute type but breaks with the new one:

/**
 * A function that may validate or sanitize attributes before they are used in telemetry.
 */
function doStuffWithAttributes(attributes: Attributes) {
  for (const attrName in attributes) {
    const value = attributes[attrName];

    if (
      value == null ||
      typeof value === 'string' ||
      typeof value === 'number' ||
      typeof value === 'boolean'
    ) {
      // do whatever
      continue;
    }

    // tsc now knows that this can now only be an Array,
    // so it'll allow things that are available on Arrays.
    // In the future, this may be an object so it will
    //  - break during compile time. (TS2723: Cannot invoke an object which is possibly null or undefined)
    //  - break during runtime for already compiled code that caret-depends on the API (like instrumentations that receive attributes from a user-exposed hook)
    //
    // I think all other possible examples where are essentially variations of this one.
    //
    // SDK components should be safe since they should specify an upper limit for supported API versions.
    // Unfortunately, instrumentations are not bound by that.
    return value.filter(item => typeof item == 'string');
  }
}

PoC: widen 'Attributes' to support the extended AnyValue

0b70688

Refs: open-telemetry#6349

trentm self-assigned this Apr 10, 2026

lint:fix

d438f46

trentm added 3 commits April 10, 2026 11:08

more work cleaning up attributes handling in tracing APIs so far. Not…

2b2f308

… all of this needs to be part of *this* PR work

s/MetricAttributes/Attributes/ in usage; use AnyValue instead of Attr…

5469036

…ibuteValue (now deprecated) because AnyValue is in the spec for more than just attributes (e.g. LogRecord#body)

use Marc's normalizeAnyValue (from a separate PR) for hashing extende…

74282bd

…d attributes in sdk-metrics (keyObjFromAnyValue util in core package)

trentm commented Apr 10, 2026

View reviewed changes

trentm added 3 commits April 10, 2026 15:27

lint:fix

2ca3075

fix core tests

31b15cd

fix sdk-trace-base tests

29b0978

trentm added 2 commits April 10, 2026 16:27

lint:fix

6303b2c

fix shim-opencensus tests

34f8ee8

Conversation

trentm commented Apr 10, 2026

Current status

Uh oh!

trentm commented Apr 10, 2026

Uh oh!

trentm left a comment

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!

codecov Bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

trentm commented Apr 10, 2026

Uh oh!

pichlermarc commented Apr 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov Bot commented Apr 10, 2026 •

edited

Loading