Skip to content

Add missing set value attribute shortcuts #8255

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
trask wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add missing set value attribute shortcuts #8255

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
19f8996
Add missing set value attribute shortcuts
trask Apr 5, 2026
f071768
opencensus-shim
trask Apr 8, 2026
ca0c2dd
apidiff
trask Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions api/all/src/main/java/io/opentelemetry/api/logs/LogRecordBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,21 @@ default LogRecordBuilder setAttribute(String key, int value) {
return setAttribute(key, (long) value);
}

/**
* Sets a {@link Value} attribute on the {@code LogRecord}. If the {@code LogRecord} previously
* contained a mapping for the key, the old value is replaced by the specified value.
*
Copy link
Copy Markdown
Member Author

@trask trask Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add comment here and elsewhere

Instrumentations should assume that backends do not index individual properties of complex attributes, that querying or aggregating on such properties is inefficient and complicated, and that reporting complex attributes carries higher performance overhead.

Copy link
Copy Markdown
Member

@jack-berg jack-berg Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ping @trask 🙂

* <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
* pre-allocate your keys, if possible.
*
* @param key the key for this attribute.
* @param value the value for this attribute.
* @return this.
*/
default LogRecordBuilder setAttribute(String key, Value<?> value) {
return setAttribute(AttributeKey.valueKey(key), value);
}

/**
* Sets the event name, which identifies the class / type of the Event.
*
Expand Down
16 changes: 16 additions & 0 deletions api/all/src/main/java/io/opentelemetry/api/trace/Span.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@

import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.common.Value;
import io.opentelemetry.api.internal.ApiUsageLogger;
import io.opentelemetry.context.Context;
import io.opentelemetry.context.ImplicitContextKeyed;
Expand Down Expand Up @@ -148,6 +149,21 @@ default Span setAttribute(String key, boolean value) {
return setAttribute(AttributeKey.booleanKey(key), value);
}

/**
* Sets a {@link Value} attribute on the {@code Span}. If the {@code Span} previously contained a
* mapping for the key, the old value is replaced by the specified value.
*
* <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
* pre-allocate your keys, if possible.
*
* @param key the key for this attribute.
* @param value the value for this attribute.
* @return this.
*/
default Span setAttribute(String key, Value<?> value) {
return setAttribute(AttributeKey.valueKey(key), value);
}

/**
* Sets an attribute to the {@code Span}. If the {@code Span} previously contained a mapping for
* the key, the old value is replaced by the specified value.
Expand Down
6 changes: 4 additions & 2 deletions api/all/src/test/java/io/opentelemetry/api/trace/PropagatedSpanTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
import static org.assertj.core.api.Assertions.assertThat;

import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.common.Value;
import java.time.Instant;
import java.util.concurrent.TimeUnit;
import org.junit.jupiter.api.Test;
Expand All @@ -40,16 +41,17 @@ void doNotCrash() {
span.setAttribute(booleanKey("MyBooleanAttributeKey"), true);
span.setAttribute(longKey("MyLongAttributeKey"), 123L);
span.setAttribute(longKey("MyLongAttributeKey"), 123);
span.setAttribute("NullString", null);
span.setAttribute("NullString", (String) null);
span.setAttribute("EmptyString", "");
span.setAttribute("long", 1);
span.setAttribute("double", 1.0);
span.setAttribute("boolean", true);
span.setAttribute("value", Value.of("val"));
span.setAttribute(stringArrayKey("NullArrayString"), null);
span.setAttribute(booleanArrayKey("NullArrayBoolean"), null);
span.setAttribute(longArrayKey("NullArrayLong"), null);
span.setAttribute(doubleArrayKey("NullArrayDouble"), null);
span.setAttribute((String) null, null);
span.setAttribute((String) null, (String) null);
span.setAllAttributes(null);
span.setAllAttributes(Attributes.empty());
span.setAllAttributes(
Expand Down
5 changes: 4 additions & 1 deletion sdk/logs/src/test/java/io/opentelemetry/sdk/logs/SdkLogRecordBuilderTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
import static io.opentelemetry.api.common.AttributeKey.doubleKey;
import static io.opentelemetry.api.common.AttributeKey.longKey;
import static io.opentelemetry.api.common.AttributeKey.stringKey;
import static io.opentelemetry.api.common.AttributeKey.valueKey;
import static io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions.assertThat;
import static io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions.equalTo;
import static org.mockito.ArgumentMatchers.eq;
Expand Down Expand Up @@ -160,14 +161,16 @@ void testConvenienceAttributeMethods() {
.setAttribute("dk", 12.123)
.setAttribute("bk", true)
.setAttribute("ik", 13)
.setAttribute("vk", Value.of(new byte[] {1, 2, 3}))
.emit();
assertThat(emittedLog.get().toLogRecordData())
.hasAttributesSatisfyingExactly(
equalTo(stringKey("foo"), "bar"),
equalTo(longKey("lk"), 12L),
equalTo(doubleKey("dk"), 12.123),
equalTo(booleanKey("bk"), true),
equalTo(longKey("ik"), 13L));
equalTo(longKey("ik"), 13L),
equalTo(valueKey("vk"), Value.of(new byte[] {1, 2, 3})));
}

@Test
Expand Down
2 changes: 1 addition & 1 deletion sdk/trace/src/test/java/io/opentelemetry/sdk/trace/SdkSpanBuilderTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -391,7 +391,7 @@ void setAttribute_nullAttributeValue_afterEnd() {
SdkSpan span = (SdkSpan) spanBuilder.startSpan();
assertThat(span.toSpanData().getAttributes().size()).isEqualTo(10);
span.end();
span.setAttribute("emptyString", null);
span.setAttribute("emptyString", (String) null);
span.setAttribute(stringKey("emptyStringAttributeValue"), null);
span.setAttribute(longKey("longAttribute"), null);
span.setAttribute(booleanKey("boolAttribute"), null);
Expand Down
11 changes: 7 additions & 4 deletions sdk/trace/src/test/java/io/opentelemetry/sdk/trace/SdkSpanTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -548,7 +548,7 @@ void setAttribute() {
SdkSpan span = createTestRootSpan();
try {
span.setAttribute("StringKey", "StringVal");
span.setAttribute("NullStringKey", null);
span.setAttribute("NullStringKey", (String) null);
span.setAttribute("EmptyStringKey", "");
span.setAttribute(stringKey("NullStringAttributeValue"), null);
span.setAttribute(stringKey("EmptyStringAttributeValue"), "");
Expand All @@ -557,6 +557,7 @@ void setAttribute() {
span.setAttribute(longKey("LongKey3"), 6L);
span.setAttribute("DoubleKey", 10.0);
span.setAttribute("BooleanKey", false);
span.setAttribute("BytesValueKey", Value.of(new byte[] {1, 2, 3}));
span.setAttribute(
stringArrayKey("ArrayStringKey"), Arrays.asList("StringVal", null, "", "StringVal2"));
span.setAttribute(longArrayKey("ArrayLongKey"), Arrays.asList(1L, 2L, 3L, 4L, 5L));
Expand All @@ -579,7 +580,7 @@ void setAttribute() {
span.end();
}
SpanData spanData = span.toSpanData();
assertThat(spanData.getAttributes().size()).isEqualTo(17);
assertThat(spanData.getAttributes().size()).isEqualTo(18);
assertThat(spanData.getAttributes().get(stringKey("StringKey"))).isNotNull();
assertThat(spanData.getAttributes().get(stringKey("EmptyStringKey"))).isNotNull();
assertThat(spanData.getAttributes().get(stringKey("EmptyStringAttributeValue"))).isNotNull();
Expand All @@ -588,6 +589,8 @@ void setAttribute() {
assertThat(spanData.getAttributes().get(longKey("LongKey3"))).isEqualTo(6L);
assertThat(spanData.getAttributes().get(doubleKey("DoubleKey"))).isNotNull();
assertThat(spanData.getAttributes().get(booleanKey("BooleanKey"))).isNotNull();
assertThat(spanData.getAttributes().get(valueKey("BytesValueKey")))
.isEqualTo(Value.of(new byte[] {1, 2, 3}));
assertThat(spanData.getAttributes().get(stringArrayKey("ArrayStringKey"))).isNotNull();
assertThat(spanData.getAttributes().get(longArrayKey("ArrayLongKey"))).isNotNull();
assertThat(spanData.getAttributes().get(doubleArrayKey("ArrayDoubleKey"))).isNotNull();
Expand Down Expand Up @@ -630,7 +633,7 @@ void setAttribute_nullKeys() {
span.setAttribute(null, Collections.emptyList());
span.setAttribute(null, Collections.emptyList());
span.setAttribute(null, Collections.emptyList());
span.setAttribute(null, Value.empty());
span.setAttribute((AttributeKey<Value<?>>) null, Value.empty());
assertThat(span.toSpanData().getAttributes().size()).isZero();
}

Expand Down Expand Up @@ -658,7 +661,7 @@ void setAttribute_emptyArrayAttributeValue() {
@Test
void setAttribute_nullStringValue() {
SdkSpan span = createTestRootSpan();
span.setAttribute("nullString", null);
span.setAttribute("nullString", (String) null);
span.setAttribute("emptyString", "");
span.setAttribute(stringKey("nullStringAttributeValue"), null);
span.setAttribute(stringKey("emptyStringAttributeValue"), "");
Expand Down
Loading