Clarify that AttributesBuilder.put allows nulls (#7271)

Author: tylerbenson

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

@@ -9,6 +9,7 @@
 import java.util.Arrays;
 import java.util.List;
 import java.util.function.Predicate;
+import javax.annotation.Nullable;
 
 class ArrayBackedAttributesBuilder implements AttributesBuilder {
   private final List<Object> data;
@@ -37,7 +38,7 @@ public <T> AttributesBuilder put(AttributeKey<Long> key, int value) {
   }
 
   @Override
-  public <T> AttributesBuilder put(AttributeKey<T> key, T value) {
+  public <T> AttributesBuilder put(AttributeKey<T> key, @Nullable T value) {
     if (key == null || key.getKey().isEmpty() || value == null) {
       return this;
     }

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

@@ -18,6 +18,7 @@
 import java.util.Arrays;
 import java.util.List;
 import java.util.function.Predicate;
+import javax.annotation.Nullable;
 
 /** A builder of {@link Attributes} supporting an arbitrary number of key-value pairs. */
 public interface AttributesBuilder {
@@ -35,18 +36,22 @@ public interface AttributesBuilder {
   // version.
   <T> AttributesBuilder put(AttributeKey<Long> key, int value);
 
-  /** Puts a {@link AttributeKey} with associated value into this. */
-  <T> AttributesBuilder put(AttributeKey<T> key, T value);
+  /**
+   * Puts an {@link AttributeKey} with an associated value into this if the value is non-null.
+   * Providing a null value does not remove or unset previously set values.
+   */
+  <T> AttributesBuilder put(AttributeKey<T> key, @Nullable T value);
 
   /**
-   * Puts a String attribute into this.
+   * Puts a String attribute into this if the value is non-null. Providing a null value does not
+   * remove or unset previously set values.
    *
    * <p>Note: It is strongly recommended to use {@link #put(AttributeKey, Object)}, and pre-allocate
    * your keys, if possible.
    *
    * @return this Builder
    */
-  default AttributesBuilder put(String key, String value) {
+  default AttributesBuilder put(String key, @Nullable String value) {
     return put(stringKey(key), value);
   }
 

api/all/src/main/java/io/opentelemetry/api/logs/DefaultLogger.java

@@ -10,6 +10,7 @@
 import io.opentelemetry.context.Context;
 import java.time.Instant;
 import java.util.concurrent.TimeUnit;
+import javax.annotation.Nullable;
 
 class DefaultLogger implements Logger {
 
@@ -77,7 +78,7 @@ public LogRecordBuilder setBody(Value<?> body) {
     }
 
     @Override
-    public <T> LogRecordBuilder setAttribute(AttributeKey<T> key, T value) {
+    public <T> LogRecordBuilder setAttribute(AttributeKey<T> key, @Nullable T value) {
       return this;
     }
 

api/all/src/main/java/io/opentelemetry/api/logs/LogRecordBuilder.java

@@ -16,6 +16,7 @@
 import io.opentelemetry.context.Context;
 import java.time.Instant;
 import java.util.concurrent.TimeUnit;
+import javax.annotation.Nullable;
 
 /**
  * Used to construct and emit log records from a {@link Logger}.
@@ -107,16 +108,20 @@ default LogRecordBuilder setAllAttributes(Attributes attributes) {
    * Sets an 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.
    *
+   * <p>Note: Providing a null value is a no-op and will not remove previously set values.
+   *
    * @param key the key for this attribute.
    * @param value the value for this attribute.
    * @return this.
    */
-  <T> LogRecordBuilder setAttribute(AttributeKey<T> key, T value);
+  <T> LogRecordBuilder setAttribute(AttributeKey<T> key, @Nullable T value);
 
   /**
    * Sets a String 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.
    *
+   * <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.
    *
@@ -125,7 +130,7 @@ default LogRecordBuilder setAllAttributes(Attributes attributes) {
    * @return this.
    * @since 1.48.0
    */
-  default LogRecordBuilder setAttribute(String key, String value) {
+  default LogRecordBuilder setAttribute(String key, @Nullable String value) {
     return setAttribute(stringKey(key), value);
   }
 

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

@@ -8,6 +8,7 @@
 import io.opentelemetry.api.common.AttributeKey;
 import io.opentelemetry.api.common.Attributes;
 import java.util.concurrent.TimeUnit;
+import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
 
 /**
@@ -42,7 +43,7 @@ private PropagatedSpan(SpanContext spanContext) {
   }
 
   @Override
-  public Span setAttribute(String key, String value) {
+  public Span setAttribute(String key, @Nullable String value) {
     return this;
   }
 
@@ -62,7 +63,7 @@ public Span setAttribute(String key, boolean value) {
   }
 
   @Override
-  public <T> Span setAttribute(AttributeKey<T> key, T value) {
+  public <T> Span setAttribute(AttributeKey<T> key, @Nullable T value) {
     return this;
   }
 

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

@@ -88,7 +88,9 @@ static Span wrap(SpanContext spanContext) {
    * 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.
    *
-   * <p>Empty String "" and null are valid attribute {@code value}, but not valid keys.
+   * <p>Empty String "" and null are valid attribute {@code value}s, but not valid keys.
+   *
+   * <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.
@@ -97,7 +99,7 @@ static Span wrap(SpanContext spanContext) {
    * @param value the value for this attribute.
    * @return this.
    */
-  default Span setAttribute(String key, String value) {
+  default Span setAttribute(String key, @Nullable String value) {
     return setAttribute(AttributeKey.stringKey(key), value);
   }
 
@@ -150,13 +152,13 @@ default Span setAttribute(String key, boolean 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.
    *
-   * <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> Span setAttribute(AttributeKey<T> key, T value);
+  <T> Span setAttribute(AttributeKey<T> key, @Nullable T value);
 
   /**
    * Sets an attribute to the {@code Span}. If the {@code Span} previously contained a mapping for

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

@@ -26,6 +26,7 @@
 import java.util.Map;
 import java.util.NoSuchElementException;
 import java.util.concurrent.atomic.AtomicBoolean;
+import javax.annotation.Nullable;
 import org.junit.jupiter.api.Test;
 
 /** Unit tests for {@link Attributes}s. */
@@ -565,7 +566,7 @@ public <T> AttributesBuilder put(AttributeKey<Long> key, int value) {
           }
 
           @Override
-          public <T> AttributesBuilder put(AttributeKey<T> key, T value) {
+          public <T> AttributesBuilder put(AttributeKey<T> key, @Nullable T value) {
             return null;
           }
 

api/incubator/src/main/java/io/opentelemetry/api/incubator/logs/ExtendedDefaultLogger.java

@@ -13,6 +13,7 @@
 import io.opentelemetry.context.Context;
 import java.time.Instant;
 import java.util.concurrent.TimeUnit;
+import javax.annotation.Nullable;
 
 class ExtendedDefaultLogger implements ExtendedLogger {
 
@@ -51,7 +52,7 @@ public <T> ExtendedLogRecordBuilder setAttribute(ExtendedAttributeKey<T> key, T
     }
 
     @Override
-    public <T> ExtendedLogRecordBuilder setAttribute(AttributeKey<T> key, T value) {
+    public <T> ExtendedLogRecordBuilder setAttribute(AttributeKey<T> key, @Nullable T value) {
       return this;
     }
 

api/incubator/src/main/java/io/opentelemetry/api/incubator/logs/ExtendedLogRecordBuilder.java

@@ -15,6 +15,7 @@
 import io.opentelemetry.context.Context;
 import java.time.Instant;
 import java.util.concurrent.TimeUnit;
+import javax.annotation.Nullable;
 
 /** Extended {@link LogRecordBuilder} with experimental APIs. */
 public interface ExtendedLogRecordBuilder extends LogRecordBuilder {
@@ -110,7 +111,7 @@ default ExtendedLogRecordBuilder setAllAttributes(ExtendedAttributes attributes)
    * attribute APIs.
    */
   @Override
-  <T> ExtendedLogRecordBuilder setAttribute(AttributeKey<T> key, T value);
+  <T> ExtendedLogRecordBuilder setAttribute(AttributeKey<T> key, @Nullable T value);
 
   /**
    * Set an attribute.

opencensus-shim/src/main/java/io/opentelemetry/opencensusshim/DelegatingSpan.java

@@ -15,6 +15,7 @@
 import io.opentelemetry.context.Scope;
 import java.time.Instant;
 import java.util.concurrent.TimeUnit;
+import javax.annotation.Nullable;
 
 /**
  * Delegates <i>all</i> {@link Span} methods to some underlying Span via {@link
@@ -52,12 +53,12 @@ default boolean isRecording() {
   }
 
   @Override
-  default <T> Span setAttribute(AttributeKey<T> key, T value) {
+  default <T> Span setAttribute(AttributeKey<T> key, @Nullable T value) {
     return getDelegate().setAttribute(key, value);
   }
 
   @Override
-  default Span setAttribute(String key, String value) {
+  default Span setAttribute(String key, @Nullable String value) {
     return getDelegate().setAttribute(key, value);
   }