more javadoc

Author: trask

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

@@ -19,10 +19,13 @@ public enum AttributeType {
   LONG_ARRAY,
   DOUBLE_ARRAY,
   /**
-   * Simple attributes (i.e. anything other than {@code VALUE} attributes) SHOULD be used whenever
-   * possible. 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.
+   * Simple attributes ({@link AttributeType#STRING}, {@link AttributeType#LONG}, {@link
+   * AttributeType#DOUBLE}, {@link AttributeType#BOOLEAN}, {@link AttributeType#STRING_ARRAY},
+   * {@link AttributeType#LONG_ARRAY}, {@link AttributeType#DOUBLE_ARRAY}, {@link
+   * AttributeType#BOOLEAN_ARRAY}) SHOULD be used whenever possible. 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.
    */
   VALUE
 }

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

@@ -36,14 +36,8 @@ public interface Attributes {
   /**
    * Returns the value for the given {@link AttributeKey}, or {@code null} if not found.
    *
-   * <p>Simple attributes (i.e. anything other than {@link Value} attributes) SHOULD be used
-   * whenever possible. 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.
-   *
-   * <p>Note: when passing a key of type {@link AttributeType#VALUE}, the returned value will match
-   * a narrower type with the given key if one exists. This is the inverse of {@link
+   * <p>Note: this method will automatically convert simple attributes to complex attributes when
+   * passed a key of type {@link AttributeType#VALUE}. This is the inverse of {@link
    * AttributesBuilder#put(AttributeKey, Object)} when the key is {@link AttributeType#VALUE}.
    *
    * <ul>
@@ -72,7 +66,12 @@ public interface Attributes {
   @Nullable
   <T> T get(AttributeKey<T> key);
 
-  /** Iterates over all the key-value pairs of attributes contained by this instance. */
+  /**
+   * Iterates over all the key-value pairs of attributes contained by this instance.
+   *
+   * <p>Note: {@link AttributeType#VALUE} attributes will be represented as simple attributes if
+   * possible. See {@link AttributesBuilder#put(AttributeKey, Object)} for more details.
+   */
   void forEach(BiConsumer<? super AttributeKey<?>, ? super Object> consumer);
 
   /** The number of attributes contained in this. */
@@ -81,7 +80,12 @@ public interface Attributes {
   /** Whether there are any attributes contained in this. */
   boolean isEmpty();
 
-  /** Returns a read-only view of this {@link Attributes} as a {@link Map}. */
+  /**
+   * Returns a read-only view of this {@link Attributes} as a {@link Map}.
+   *
+   * <p>Note: {@link AttributeType#VALUE} attributes will be represented as simple attributes in
+   * this map if possible. See {@link AttributesBuilder#put(AttributeKey, Object)} for more details.
+   */
   Map<AttributeKey<?>, Object> asMap();
 
   /** Returns a {@link Attributes} instance with no attributes. */

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

@@ -40,8 +40,16 @@ public interface AttributesBuilder {
    * 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.
    *
-   * <p>Note: when passing a key of type {@link AttributeType#VALUE}, the call will be coerced into
-   * a narrower type if possible.
+   * <p>Simple attributes ({@link AttributeType#STRING}, {@link AttributeType#LONG}, {@link
+   * AttributeType#DOUBLE}, {@link AttributeType#BOOLEAN}, {@link AttributeType#STRING_ARRAY},
+   * {@link AttributeType#LONG_ARRAY}, {@link AttributeType#DOUBLE_ARRAY}, {@link
+   * AttributeType#BOOLEAN_ARRAY}) SHOULD be used whenever possible. 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.
+   *
+   * <p>Note: This method will automatically convert complex attributes ({@link
+   * AttributeType#VALUE}) to simple attributes when possible.
    *
    * <ul>
    *   <li>Calling {@code put(AttributeKey.valueKey("key"), Value.of("a"))} is equivalent to calling