Stabilize complex attributes #7973

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

No description provided.

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

Codecov Report

❌ Patch coverage is 91.20000% with 22 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.28%. Comparing base (62049e7) to head (3b6a906).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...in/java/io/opentelemetry/api/common/ProtoJson.java	88.88%	6 Missing and 2 partials ⚠️
...metry/api/common/ArrayBackedAttributesBuilder.java	90.16%	2 Missing and 4 partials ⚠️
...pentelemetry/api/common/ArrayBackedAttributes.java	92.85%	2 Missing and 2 partials ⚠️
...n/java/io/opentelemetry/api/common/ValueEmpty.java	55.55%	4 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #7973      +/-   ##
============================================
+ Coverage     90.15%   90.28%   +0.12%     
- Complexity     7476     7606     +130     
============================================
  Files           836      839       +3     
  Lines         22550    22798     +248     
  Branches       2224     2256      +32     
============================================
+ Hits          20331    20584     +253     
+ Misses         1515     1505      -10     
- Partials        704      709       +5

☔ 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?

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

trask · 2026-01-10T03:59:31Z

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

+  @Override
+  public Void getValue() {
+    return null;


need to mark this @Nullable or return some marker value (instead of using Void)

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

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.

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?

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

Stabilize complex attributes #7973

Are you sure you want to change the base?

Stabilize complex attributes #7973

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!

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!

2 participants

codecov bot commented Jan 9, 2026 •

edited

Loading