Clarify that SpanBuilder.setAttribute allows nulls (#8072)

Author: trask

api/all/src/main/java/io/opentelemetry/api/trace/DefaultTracer.java

@@ -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) {
       return this;
     }
 
@@ -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;
     }
 

api/all/src/main/java/io/opentelemetry/api/trace/SpanBuilder.java

@@ -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
@@ -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.
@@ -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
@@ -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

api/incubator/src/main/java/io/opentelemetry/api/incubator/trace/ExtendedDefaultTracer.java

@@ -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;
     }
 
@@ -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;
     }
 

api/incubator/src/main/java/io/opentelemetry/api/incubator/trace/ExtendedSpanBuilder.java

@@ -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 {
@@ -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
@@ -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

sdk/trace/src/main/java/io/opentelemetry/sdk/trace/ExtendedSdkSpanBuilder.java

@@ -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 {
@@ -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;
   }
@@ -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;
   }

sdk/trace/src/main/java/io/opentelemetry/sdk/trace/SdkSpanBuilder.java

@@ -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);
   }
 
@@ -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;
     }