Review Feedback.

Author: tylerbenson

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

@@ -36,11 +36,15 @@ public interface AttributesBuilder {
   // version.
   <T> AttributesBuilder put(AttributeKey<Long> key, int value);
 
-  /** Puts an {@link AttributeKey} with an associated value into this if the value is non-null. */
+  /**
+   * 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.

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/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