Stabilize complex attributes #7973

trask · 2026-01-09T20:46:09Z

No description provided.

codecov · 2026-01-09T22:44:02Z

Codecov Report

❌ Patch coverage is 85.09804% with 38 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.19%. Comparing base (62049e7) to head (83dd600).
⚠️ Report is 24 commits behind head on main.

Files with missing lines	Patch %	Lines
...in/java/io/opentelemetry/api/common/ProtoJson.java	75.00%	15 Missing and 3 partials ⚠️
...metry/api/common/ArrayBackedAttributesBuilder.java	90.16%	2 Missing and 4 partials ⚠️
...c/main/java/io/opentelemetry/api/common/Empty.java	0.00%	5 Missing ⚠️
...pentelemetry/api/common/ArrayBackedAttributes.java	92.85%	2 Missing and 2 partials ⚠️
...n/java/io/opentelemetry/api/common/ValueEmpty.java	62.50%	3 Missing ⚠️
...lemetry/exporter/zipkin/EventDataToAnnotation.java	75.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #7973      +/-   ##
============================================
+ Coverage     90.15%   90.19%   +0.03%     
- Complexity     7476     7590     +114     
============================================
  Files           836      837       +1     
  Lines         22550    22769     +219     
  Branches       2224     2268      +44     
============================================
+ Hits          20331    20536     +205     
- Misses         1515     1519       +4     
- Partials        704      714      +10

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

trask · 2026-01-09T20:47:27Z

api/all/src/main/java/io/opentelemetry/api/common/ArrayBackedAttributes.java

changes copy-pasted from ExtendedArrayBackedAttributes.java

trask · 2026-01-09T20:47:43Z

api/all/src/main/java/io/opentelemetry/api/common/ArrayBackedAttributesBuilder.java

changes copy-pasted from ExtendedArrayBackedAttributesBuilder.java

trask · 2026-01-09T20:48:27Z

api/all/src/main/java/io/opentelemetry/api/common/AttributeKey.java

changes copy-pasted from ExtendedAttributeKey.java

trask · 2026-01-09T20:49:16Z

api/all/src/main/java/io/opentelemetry/api/common/Attributes.java

changes copy-pasted from ExtendedAttributes.java

trask · 2026-01-09T20:49:40Z

api/all/src/main/java/io/opentelemetry/api/common/AttributesBuilder.java

changes copy-pasted from ExtendedAttributesBuilder.java

Is your plan to keeep ExtendedAttributes around for a couple of releases to give folks a chance to migrate gracefully?

yeah, good point, deprecated them in c133eea

oh no, that spun out of control due to suppressing usages, reverted, I'd suggest that I do that as a follow-up PR

trask · 2026-01-10T03:57:36Z

api/all/src/main/java/io/opentelemetry/api/common/Value.java

-  // TODO(jack-berg): Should this be a JSON encoding?
+  // TODO deprecate in favor of toString() or toProtoJson()?
  String asString();


open question (also could consider keeping asString() and having it emit proto json and removing toProtoJson())

Can you talk about toProtoJson() a little bit? I see it used the prometheus and zipkin exporters. Does the spec say that these exporters should encode using protobuf JSON in for extended attribute cases?

Do we have to add this functionality in the first stable release of extended attributes or can it be added later?

Also having thoughts about how we have JSON value serialization in two places: Value#toProtoJson() and AnyValueMarshaler. They're of course used in different contexts. There's probably a way to incorporate AnyValueMarshaler into ValueToProtoJsonTest to verify they're equivalent.

open question (also could consider keeping asString() and having it emit proto json and removing toProtoJson())

Yes let's do that. See my comment to the same effect here: https://github.com/open-telemetry/opentelemetry-java/pull/7973/changes#r2696282790

just to see what it looks like, no worries if we change our mind (took me a few commits):

3a8b796

fd5fa9d

facd585

Can you talk about toProtoJson() a little bit? I see it used the prometheus and zipkin exporters. Does the spec say that these exporters should encode using protobuf JSON in for extended attribute cases?

it's unclear to me, I've added topic to discuss in spec meeting

so I'm not sure I love asString emitting proto json, because it feels a little weird for a method named asString to emit the quotes around a string for a simple string value

I think my current preference might be your other suggestion #7973 (comment) which has the other benefit of hiding proto json representation a bit more as an exporter/sdk concern

I think my current preference might be your other suggestion #7973 (comment) which has the other benefit of hiding proto json representation a bit more as an exporter/sdk concern

If we go with the other direction we only need a simplified JSON encoding, even for exporters, right? And so we could get away with adjusting asString to return the simplified JSON encoding.

api/all/src/main/java/io/opentelemetry/api/common/ValueEmpty.java

trask · 2026-01-10T04:01:58Z

...s/zipkin/src/test/java/io/opentelemetry/exporter/zipkin/OtelToZipkinSpanTransformerTest.java

+                .putTag("bytes", "\"AQID\"")
+                .putTag("map", "{\"nested\":\"value\"}")
+                .putTag("heterogeneousArray", "[\"string\",123]")
+                .putTag("empty", "null")


same questionable choices:

"\"AQID\"" vs "AQID"

"null" vs "" vs "{}"

""AQID"" vs "AQID"

Should be base64 encoded string https://protobuf.dev/programming-guides/json/

"null" vs "" vs "{}"

Should be JSON null literal

just confirming, so you agree with the choices I made in the implementation above?

In open-telemetry/opentelemetry-specification#4848, I'm proposing that top-level attributes be more naturally encoded (instead of JSON encoded), so

Suggested change

.putTag("bytes", "\"AQID\"")

.putTag("map", "{\"nested\":\"value\"}")

.putTag("heterogeneousArray", "[\"string\",123]")

.putTag("empty", "null")

.putTag("bytes", "AQID")

.putTag("map", "{\"nested\":\"value\"}")

.putTag("heterogeneousArray", "[\"string\",123]")

.putTag("empty", "")

trask · 2026-01-10T04:08:57Z

api/all/src/main/java/io/opentelemetry/api/common/ValueEmpty.java

+
+  @Override
+  public String asString() {
+    return "";


another option would be return the string "null"

I'm fine with this for asString().

Geez I don't think we can justify having asString(), toString(), and toProtoJson() 😅. I think probably we change asString() to be the proto json encoder. I warned in the javadoc that no guarantees are made so we should be able to do this:

* <p>WARNING: No guarantees are made about the encoding of this string response. It MAY change in * a future minor release. If you need a reliable string encoding, write your own serializer.

trask · 2026-01-10T04:16:30Z

api/all/src/main/java/io/opentelemetry/api/common/Value.java

+   * @return a JSON encoding of this value
+   */
+  default String toProtoJson() {
+    return "\"unimplemented\"";


alternatively could throw UnsupportedOperationException

Another alternative would be to have a static String asProtoJson(Value<?>) utility method. Is there anything in the implementations of toProtoJson that benefits from accessing the private fields?

This type of utility method could also packaged somewhere like opentelemetry-exporter-common or opentelemetry-sdk-common so opentelemetry-api doesn't need to have a class called ProtoJson in it, which is a smell.

This type of utility method could also packaged somewhere like opentelemetry-exporter-common or opentelemetry-sdk-common so opentelemetry-api doesn't need to have a class called ProtoJson in it, which is a smell.

just confirming you prefer to ignore this comment since it contradicts #7973 (comment)?

having second thoughts and may prefer this suggestion: #7973 (comment)

jack-berg · 2026-01-15T22:36:44Z

api/all/src/test/java/io/opentelemetry/api/common/ValueToProtoJsonTest.java

+
+  @Test
+  void valueString_basic() {
+    assertThat(Value.of("hello").toProtoJson()).isEqualTo("\"hello\"");


Slight preference for @ParameterizedTest here, but won't split hairs over it because there's plenty of examples in this repo similar to what you have here.

jack-berg · 2026-01-15T22:39:02Z

api/all/src/test/java/io/opentelemetry/api/common/ValueToProtoJsonTest.java

+                    Value.of(false),
+                    Value.empty())
+                .toProtoJson())
+        .isEqualTo("[\"string\",42,3.14,true,false,null]");


If longs are supposed to be stringified, then how come in an array context they aren't?

longs are stringified everywhere, but they aren't surrounded by (extra) quotes since they aren't json strings

This reverts commit c133eea.

trask added 2 commits January 9, 2026 14:31

Stabilize complex attributes

eca5ee4

apidiffs

8c951bd

trask force-pushed the stabilize-complex-attributes-try-2 branch from 3bc8e76 to 8c951bd Compare January 9, 2026 22:32

updates

0e2af07

trask force-pushed the stabilize-complex-attributes-try-2 branch from 30fb180 to 0e2af07 Compare January 9, 2026 23:37

json

103d13b

trask force-pushed the stabilize-complex-attributes-try-2 branch 4 times, most recently from 55d9121 to 23f5d22 Compare January 10, 2026 04:05

toProtoJson

0e19885

trask force-pushed the stabilize-complex-attributes-try-2 branch from 23f5d22 to 0e19885 Compare January 10, 2026 04:15

trask commented Jan 10, 2026

View reviewed changes

trask marked this pull request as ready for review January 10, 2026 04:16

trask requested a review from a team as a code owner January 10, 2026 04:16

trask added 2 commits January 10, 2026 09:35

unit tests

0ad0d89

test coverage

3b6a906

jack-berg reviewed Jan 15, 2026

View reviewed changes

trask added 9 commits January 19, 2026 19:05

improve javadoc

bc77eed

better empty value representation

543e8eb

deprecate extended attributes incubating api

c133eea

Use asString instead of toProtoJson

3a8b796

parameterized test

4fbab35

Revert "deprecate extended attributes incubating api"

7604d83

This reverts commit c133eea.

fixup! Use asString instead of toProtoJson

fd5fa9d

fixup! Use asString instead of toProtoJson

facd585

Update to latest spec PR

2a8fd46

trask force-pushed the stabilize-complex-attributes-try-2 branch from 7dabd12 to 2a8fd46 Compare January 21, 2026 23:30

jApiCmp

83dd600

Stabilize complex attributes #7973

Are you sure you want to change the base?

Stabilize complex attributes #7973

Uh oh!

Conversation

trask commented Jan 9, 2026

Uh oh!

codecov bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

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!

trask Jan 20, 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!

trask Jan 20, 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!

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!

trask Jan 20, 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!

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!

trask Jan 20, 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!

codecov bot commented Jan 9, 2026 •

edited

Loading

trask Jan 20, 2026 •

edited

Loading

trask Jan 20, 2026 •

edited

Loading

trask Jan 20, 2026 •

edited

Loading

trask Jan 20, 2026 •

edited

Loading