Skip to content

Clarify that SpanBuilder.setAttribute allows nulls #8072

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

Merged
jack-berg merged 1 commit into from
Feb 13, 2026
Merged

Clarify that SpanBuilder.setAttribute allows nulls #8072

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 2 additions & 2 deletions api/all/src/main/java/io/opentelemetry/api/trace/DefaultTracer.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ public NoopSpanBuilder addLink(SpanContext spanContext, Attributes attributes) {
}

@Override
public NoopSpanBuilder setAttribute(String key, String value) {
public NoopSpanBuilder setAttribute(String key, @Nullable String value) {
Copy link
Member

@jack-berg jack-berg Feb 12, 2026

Choose a reason for hiding this comment

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

How did you run into this in practice? Given that DefaultTracer is package private, I assume everyone is actually dealing with the public Tracer interface.

Maybe you're just trying to keep the annotations consistent across interfaces and implementations?

Copy link
Member Author

@trask trask Feb 12, 2026

Choose a reason for hiding this comment

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

I think nullaway gave me an error

return this;
}

Expand All @@ -94,7 +94,7 @@ public NoopSpanBuilder setAttribute(String key, boolean value) {
}

@Override
public <T> NoopSpanBuilder setAttribute(AttributeKey<T> key, T value) {
public <T> NoopSpanBuilder setAttribute(AttributeKey<T> key, @Nullable T value) {
return this;
}

Expand Down
10 changes: 5 additions & 5 deletions api/all/src/main/java/io/opentelemetry/api/trace/SpanBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
import io.opentelemetry.context.Context;
import java.time.Instant;
import java.util.concurrent.TimeUnit;
import javax.annotation.Nullable;

/**
* {@link SpanBuilder} is used to construct {@link Span} instances which define arbitrary scopes of
Expand Down Expand Up @@ -175,8 +176,7 @@ public interface SpanBuilder {
* Sets an attribute to the newly created {@code Span}. If {@code SpanBuilder} previously
* contained a mapping for the key, the old value is replaced by the specified value.
*
* <p>If a null or empty String {@code value} is passed in, the behavior is undefined, and hence
* strongly discouraged.
* <p>Note: Providing a null value is a no-op and will not remove previously set values.
*
* <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
* pre-allocate your keys, if possible.
Expand All @@ -185,7 +185,7 @@ public interface SpanBuilder {
* @param value the value for this attribute.
* @return this.
*/
SpanBuilder setAttribute(String key, String value);
SpanBuilder setAttribute(String key, @Nullable String value);

/**
* Sets an attribute to the newly created {@code Span}. If {@code SpanBuilder} previously
Expand Down Expand Up @@ -230,13 +230,13 @@ public interface SpanBuilder {
* Sets an attribute to the newly created {@code Span}. If {@code SpanBuilder} previously
* contained a mapping for the key, the old value is replaced by the specified value.
*
* <p>Note: the behavior of null values is undefined, and hence strongly discouraged.
* <p>Note: Providing a null value is a no-op.
*
* @param key the key for this attribute.
* @param value the value for this attribute.
* @return this.
*/
<T> SpanBuilder setAttribute(AttributeKey<T> key, T value);
<T> SpanBuilder setAttribute(AttributeKey<T> key, @Nullable T value);

/**
* Sets an attribute to the newly created {@code Span}. If {@code SpanBuilder} previously
Expand Down
4 changes: 2 additions & 2 deletions api/incubator/src/main/java/io/opentelemetry/api/incubator/trace/ExtendedDefaultTracer.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ public NoopSpanBuilder addLink(SpanContext spanContext, Attributes attributes) {
}

@Override
public NoopSpanBuilder setAttribute(String key, String value) {
public NoopSpanBuilder setAttribute(String key, @Nullable String value) {
return this;
}

Expand All @@ -114,7 +114,7 @@ public NoopSpanBuilder setAttribute(String key, boolean value) {
}

@Override
public <T> NoopSpanBuilder setAttribute(AttributeKey<T> key, T value) {
public <T> NoopSpanBuilder setAttribute(AttributeKey<T> key, @Nullable T value) {
return this;
}

Expand Down
5 changes: 3 additions & 2 deletions api/incubator/src/main/java/io/opentelemetry/api/incubator/trace/ExtendedSpanBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
import java.util.Map;
import java.util.concurrent.TimeUnit;
import java.util.function.BiConsumer;
import javax.annotation.Nullable;

/** Extended {@link SpanBuilder} with experimental APIs. */
public interface ExtendedSpanBuilder extends SpanBuilder {
Expand Down Expand Up @@ -109,7 +110,7 @@ <E extends Throwable> void startAndRun(

/** {@inheritDoc} */
@Override
ExtendedSpanBuilder setAttribute(String key, String value);
ExtendedSpanBuilder setAttribute(String key, @Nullable String value);

/** {@inheritDoc} */
@Override
Expand All @@ -125,7 +126,7 @@ <E extends Throwable> void startAndRun(

/** {@inheritDoc} */
@Override
<T> ExtendedSpanBuilder setAttribute(AttributeKey<T> key, T value);
<T> ExtendedSpanBuilder setAttribute(AttributeKey<T> key, @Nullable T value);

/** {@inheritDoc} */
@Override
Expand Down
5 changes: 3 additions & 2 deletions sdk/trace/src/main/java/io/opentelemetry/sdk/trace/ExtendedSdkSpanBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
import java.util.Map;
import java.util.concurrent.TimeUnit;
import java.util.function.BiConsumer;
import javax.annotation.Nullable;

/** {@link ExtendedSdkSpanBuilder} is SDK implementation of {@link ExtendedSpanBuilder}. */
final class ExtendedSdkSpanBuilder extends SdkSpanBuilder implements ExtendedSpanBuilder {
Expand Down Expand Up @@ -65,7 +66,7 @@ public ExtendedSpanBuilder addLink(SpanContext spanContext, Attributes attribute
}

@Override
public ExtendedSpanBuilder setAttribute(String key, String value) {
public ExtendedSpanBuilder setAttribute(String key, @Nullable String value) {
super.setAttribute(key, value);
return this;
}
Expand All @@ -89,7 +90,7 @@ public ExtendedSpanBuilder setAttribute(String key, boolean value) {
}

@Override
public <T> ExtendedSpanBuilder setAttribute(AttributeKey<T> key, T value) {
public <T> ExtendedSpanBuilder setAttribute(AttributeKey<T> key, @Nullable T value) {
super.setAttribute(key, value);
return this;
}
Expand Down
4 changes: 2 additions & 2 deletions sdk/trace/src/main/java/io/opentelemetry/sdk/trace/SdkSpanBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ private void addLink(LinkData link) {
}

@Override
public SpanBuilder setAttribute(String key, String value) {
public SpanBuilder setAttribute(String key, @Nullable String value) {
return setAttribute(stringKey(key), value);
}

Expand All @@ -146,7 +146,7 @@ public SpanBuilder setAttribute(String key, boolean value) {
}

@Override
public <T> SpanBuilder setAttribute(AttributeKey<T> key, T value) {
public <T> SpanBuilder setAttribute(AttributeKey<T> key, @Nullable T value) {
if (key == null || key.getKey().isEmpty() || value == null) {
return this;
}
Expand Down
Loading