progress

Author: jack-berg

api/all/build.gradle.kts

@@ -19,8 +19,6 @@ dependencies {
 
   testImplementation("edu.berkeley.cs.jqf:jqf-fuzz")
   testImplementation("com.google.guava:guava-testlib")
-  testImplementation(project(":sdk:all"))
-  testImplementation(project(":sdk:testing"))
 }
 
 tasks.test {

api/all/src/test/java/io/opentelemetry/api/logs/DefaultLoggerTest.java

@@ -6,9 +6,7 @@
 package io.opentelemetry.api.logs;
 
 import io.opentelemetry.api.testing.internal.AbstractDefaultLoggerTest;
-import org.junit.jupiter.api.Disabled;
 
-@Disabled
 class DefaultLoggerTest extends AbstractDefaultLoggerTest {
 
   @Override

api/all/src/test/java/io/opentelemetry/api/trace/DefaultTracerTest.java

@@ -6,9 +6,7 @@
 package io.opentelemetry.api.trace;
 
 import io.opentelemetry.api.testing.internal.AbstractDefaultTracerTest;
-import org.junit.jupiter.api.Disabled;
 
-@Disabled
 class DefaultTracerTest extends AbstractDefaultTracerTest {
 
   @Override

api/incubator/README.md

@@ -7,6 +7,7 @@ Experimental APIs, including Event API, extended Log Bridge APIs, extended Metri
 Features:
 
 * Check if logger is enabled before emitting logs to avoid unnecessary computation
+* Add extended attributes to log records to encode complex data structures
 
 See [ExtendedLogsBridgeApiUsageTest](./src/test/java/io/opentelemetry/api/incubator/logs/ExtendedLogsBridgeApiUsageTest.java).
 

api/incubator/src/main/java/io/opentelemetry/api/incubator/common/ExtendedAttributeKey.java

@@ -11,7 +11,25 @@
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
 
-/** TODO. */
+/**
+ * This interface provides a handle for setting the values of {@link ExtendedAttributes}. The type
+ * of value that can be set with an implementation of this key is denoted by the type parameter.
+ *
+ * <p>Implementations MUST be immutable, as these are used as the keys to Maps.
+ *
+ * <p>The allowed {@link #getType()}s is a superset of those allowed in {@link AttributeKey}.
+ *
+ * <p>Convenience methods are provided for translating to / from {@link AttributeKey}:
+ *
+ * <ul>
+ *   <li>{@link #asAttributeKey()} converts from {@link ExtendedAttributeKey} to {@link
+ *       AttributeKey}
+ *   <li>{@link #fromAttributeKey(AttributeKey)} converts from {@link AttributeKey} to {@link
+ *       ExtendedAttributeKey}
+ * </ul>
+ *
+ * @param <T> The type of value that can be set with the key.
+ */
 @Immutable
 public interface ExtendedAttributeKey<T> {
   /** Returns the underlying String representation of the key. */
@@ -20,11 +38,17 @@ public interface ExtendedAttributeKey<T> {
   /** Returns the type of attribute for this key. Useful for building switch statements. */
   ExtendedAttributeType getType();
 
+  /**
+   * Return the equivalent {@link AttributeKey}, or {@code null} if the {@link #getType()} has no
+   * equivalent {@link io.opentelemetry.api.common.AttributeType}.
+   */
   @Nullable
   default AttributeKey<T> asAttributeKey() {
     return InternalExtendedAttributeKeyImpl.toAttributeKey(this);
   }
 
+  /** Return an ExtendedAttributeKey equivalent to the {@code attributeKey}. */
+  // TODO (jack-berg): remove once AttributeKey.asExtendedAttributeKey is available
   static <T> ExtendedAttributeKey<T> fromAttributeKey(AttributeKey<T> attributeKey) {
     return InternalExtendedAttributeKeyImpl.fromAttributeKey(attributeKey);
   }
@@ -70,12 +94,7 @@ static ExtendedAttributeKey<List<Double>> doubleArrayKey(String key) {
   }
 
   /** Returns a new ExtendedAttributeKey for Map valued attributes. */
-  static ExtendedAttributeKey<ExtendedAttributes> mapKey(String key) {
-    return InternalExtendedAttributeKeyImpl.create(key, ExtendedAttributeType.MAP);
-  }
-
-  /** Returns a new ExtendedAttributeKey for Map array valued attributes. */
-  static ExtendedAttributeKey<List<ExtendedAttributes>> mapArrayKey(String key) {
-    return InternalExtendedAttributeKeyImpl.create(key, ExtendedAttributeType.MAP_ARRAY);
+  static ExtendedAttributeKey<ExtendedAttributes> extendedAttributesKey(String key) {
+    return InternalExtendedAttributeKeyImpl.create(key, ExtendedAttributeType.EXTENDED_ATTRIBUTES);
   }
 }

api/incubator/src/main/java/io/opentelemetry/api/incubator/common/ExtendedAttributeType.java

@@ -5,8 +5,14 @@
 
 package io.opentelemetry.api.incubator.common;
 
-/** TODO. */
+/**
+ * An enum that represents all the possible value types for an {@link ExtendedAttributeKey} and
+ * hence the types of values that are allowed for {@link ExtendedAttributes}.
+ *
+ * <p>This is a superset of {@link io.opentelemetry.api.common.AttributeType},
+ */
 public enum ExtendedAttributeType {
+  // Types copied AttributeType
   STRING,
   BOOLEAN,
   LONG,
@@ -15,6 +21,6 @@ public enum ExtendedAttributeType {
   BOOLEAN_ARRAY,
   LONG_ARRAY,
   DOUBLE_ARRAY,
-  MAP,
-  MAP_ARRAY;
+  // Extended types unique to ExtendedAttributes
+  EXTENDED_ATTRIBUTES;
 }

api/incubator/src/main/java/io/opentelemetry/api/incubator/common/ExtendedAttributes.java

@@ -7,11 +7,47 @@
 
 import io.opentelemetry.api.common.AttributeKey;
 import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.incubator.logs.ExtendedLogRecordBuilder;
 import java.util.Map;
 import java.util.function.BiConsumer;
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
 
+/**
+ * An immutable container for extended attributes.
+ *
+ * <p>"extended" refers an extended set of allowed value types compared to standard {@link
+ * Attributes}. Notably, {@link ExtendedAttributes} values can be of type {@link
+ * ExtendedAttributeType#EXTENDED_ATTRIBUTES}, allowing nested {@link ExtendedAttributes} of
+ * arbitrary depth.
+ *
+ * <p>Where standard {@link Attributes} are accepted everyone that OpenTelemetry represents key /
+ * value pairs, {@link ExtendedAttributes} are only accepted in select places, such as log records
+ * (e.g. {@link ExtendedLogRecordBuilder#setAttribute(ExtendedAttributeKey, Object)}).
+ *
+ * <p>The keys are {@link ExtendedAttributeKey}s and the values are Object instances that match the
+ * type of the provided key.
+ *
+ * <p>Null keys will be silently dropped.
+ *
+ * <p>Note: The behavior of null-valued attributes is undefined, and hence strongly discouraged.
+ *
+ * <p>Implementations of this interface *must* be immutable and have well-defined value-based
+ * equals/hashCode implementations. If an implementation does not strictly conform to these
+ * requirements, behavior of the OpenTelemetry APIs and default SDK cannot be guaranteed.
+ *
+ * <p>For this reason, it is strongly suggested that you use the implementation that is provided
+ * here via the factory methods and the {@link ExtendedAttributesBuilder}.
+ *
+ * <p>Convenience methods are provided for translating to / from {@link Attributes}:
+ *
+ * <ul>
+ *   <li>{@link #asAttributes()} converts from {@link ExtendedAttributes} to {@link Attributes}
+ *   <li>{@link ExtendedAttributesBuilder#putAll(Attributes)} converts from {@link Attributes} to
+ *       {@link ExtendedAttributes}
+ *   <li>{@link #get(AttributeKey)} supports reading values using standard {@link AttributeKey}
+ * </ul>
+ */
 @Immutable
 public interface ExtendedAttributes {
 

api/incubator/src/main/java/io/opentelemetry/api/incubator/common/ExtendedAttributesBuilder.java

@@ -21,7 +21,7 @@
 import java.util.List;
 import java.util.function.Predicate;
 
-/** A builder of {@link Attributes} supporting an arbitrary number of key-value pairs. */
+/** A builder of {@link ExtendedAttributes} supporting an arbitrary number of key-value pairs. */
 public interface ExtendedAttributesBuilder {
   /** Create the {@link ExtendedAttributes} from this. */
   ExtendedAttributes build();
@@ -34,14 +34,14 @@ default <T> ExtendedAttributesBuilder put(AttributeKey<T> key, T value) {
     return put(ExtendedAttributeKey.fromAttributeKey(key), value);
   }
 
-  /** TODO. */
+  /** Puts a {@link ExtendedAttributeKey} with associated value into this. */
   <T> ExtendedAttributesBuilder put(ExtendedAttributeKey<T> key, T value);
 
   /**
    * Puts a String attribute into this.
    *
-   * <p>Note: It is strongly recommended to use {@link #put(AttributeKey, Object)}, and pre-allocate
-   * your keys, if possible.
+   * <p>Note: It is strongly recommended to use {@link #put(ExtendedAttributeKey, Object)}, and
+   * pre-allocate your keys, if possible.
    *
    * @return this Builder
    */
@@ -52,8 +52,8 @@ default ExtendedAttributesBuilder put(String key, String value) {
   /**
    * Puts a long attribute into this.
    *
-   * <p>Note: It is strongly recommended to use {@link #put(AttributeKey, Object)}, and pre-allocate
-   * your keys, if possible.
+   * <p>Note: It is strongly recommended to use {@link #put(ExtendedAttributeKey, Object)}, and
+   * pre-allocate your keys, if possible.
    *
    * @return this Builder
    */
@@ -64,8 +64,8 @@ default ExtendedAttributesBuilder put(String key, long value) {
   /**
    * Puts a double attribute into this.
    *
-   * <p>Note: It is strongly recommended to use {@link #put(AttributeKey, Object)}, and pre-allocate
-   * your keys, if possible.
+   * <p>Note: It is strongly recommended to use {@link #put(ExtendedAttributeKey, Object)}, and
+   * pre-allocate your keys, if possible.
    *
    * @return this Builder
    */
@@ -76,25 +76,32 @@ default ExtendedAttributesBuilder put(String key, double value) {
   /**
    * Puts a boolean attribute into this.
    *
-   * <p>Note: It is strongly recommended to use {@link #put(AttributeKey, Object)}, and pre-allocate
-   * your keys, if possible.
+   * <p>Note: It is strongly recommended to use {@link #put(ExtendedAttributeKey, Object)}, and
+   * pre-allocate your keys, if possible.
    *
    * @return this Builder
    */
   default ExtendedAttributesBuilder put(String key, boolean value) {
     return put(booleanKey(key), value);
   }
 
-  /** TODO. */
+  /**
+   * Puts a {@link ExtendedAttributes} attribute into this.
+   *
+   * <p>Note: It is strongly recommended to use {@link #put(ExtendedAttributeKey, Object)}, and
+   * pre-allocate your keys, if possible.
+   *
+   * @return this Builder
+   */
   default <T> ExtendedAttributesBuilder put(String key, ExtendedAttributes value) {
-    return put(ExtendedAttributeKey.mapKey(key), value);
+    return put(ExtendedAttributeKey.extendedAttributesKey(key), value);
   }
 
   /**
    * Puts a String array attribute into this.
    *
-   * <p>Note: It is strongly recommended to use {@link #put(AttributeKey, Object)}, and pre-allocate
-   * your keys, if possible.
+   * <p>Note: It is strongly recommended to use {@link #put(ExtendedAttributeKey, Object)}, and
+   * pre-allocate your keys, if possible.
    *
    * @return this Builder
    */
@@ -121,8 +128,8 @@ default <T> ExtendedAttributesBuilder put(AttributeKey<List<T>> key, T... value)
   /**
    * Puts a Long array attribute into this.
    *
-   * <p>Note: It is strongly recommended to use {@link #put(AttributeKey, Object)}, and pre-allocate
-   * your keys, if possible.
+   * <p>Note: It is strongly recommended to use {@link #put(ExtendedAttributeKey, Object)}, and
+   * pre-allocate your keys, if possible.
    *
    * @return this Builder
    */
@@ -136,8 +143,8 @@ default ExtendedAttributesBuilder put(String key, long... value) {
   /**
    * Puts a Double array attribute into this.
    *
-   * <p>Note: It is strongly recommended to use {@link #put(AttributeKey, Object)}, and pre-allocate
-   * your keys, if possible.
+   * <p>Note: It is strongly recommended to use {@link #put(ExtendedAttributeKey, Object)}, and
+   * pre-allocate your keys, if possible.
    *
    * @return this Builder
    */
@@ -151,8 +158,8 @@ default ExtendedAttributesBuilder put(String key, double... value) {
   /**
    * Puts a Boolean array attribute into this.
    *
-   * <p>Note: It is strongly recommended to use {@link #put(AttributeKey, Object)}, and pre-allocate
-   * your keys, if possible.
+   * <p>Note: It is strongly recommended to use {@link #put(ExtendedAttributeKey, Object)}, and
+   * pre-allocate your keys, if possible.
    *
    * @return this Builder
    */
@@ -163,14 +170,6 @@ default ExtendedAttributesBuilder put(String key, boolean... value) {
     return put(booleanArrayKey(key), toList(value));
   }
 
-  /** TODO. */
-  default <T> ExtendedAttributesBuilder put(String key, ExtendedAttributes... value) {
-    if (value == null) {
-      return this;
-    }
-    return put(ExtendedAttributeKey.mapArrayKey(key), Arrays.asList(value));
-  }
-
   /**
    * Puts all the provided attributes into this Builder.
    *
@@ -185,7 +184,11 @@ default ExtendedAttributesBuilder putAll(Attributes attributes) {
     return this;
   }
 
-  /** TODO. */
+  /**
+   * Puts all the provided attributes into this Builder.
+   *
+   * @return this Builder
+   */
   @SuppressWarnings({"unchecked"})
   default ExtendedAttributesBuilder putAll(ExtendedAttributes attributes) {
     if (attributes == null) {
@@ -205,17 +208,26 @@ default <T> ExtendedAttributesBuilder remove(AttributeKey<T> key) {
     return remove(ExtendedAttributeKey.fromAttributeKey(key));
   }
 
-  /** TODO. */
+  /**
+   * Remove all attributes where {@link ExtendedAttributeKey#getKey()} and {@link
+   * ExtendedAttributeKey#getType()} match the {@code key}.
+   *
+   * @return this Builder
+   */
   default <T> ExtendedAttributesBuilder remove(ExtendedAttributeKey<T> key) {
     if (key == null || key.getKey().isEmpty()) {
       return this;
     }
-    // TODO:
     return removeIf(
         entryKey ->
             key.getKey().equals(entryKey.getKey()) && key.getType().equals(entryKey.getType()));
   }
 
-  /** TODO. */
+  /**
+   * Remove all attributes that satisfy the given predicate. Errors or runtime exceptions thrown by
+   * the predicate are relayed to the caller.
+   *
+   * @return this Builder
+   */
   ExtendedAttributesBuilder removeIf(Predicate<ExtendedAttributeKey<?>> filter);
 }

api/incubator/src/main/java/io/opentelemetry/api/incubator/internal/InternalExtendedAttributeKeyImpl.java

@@ -47,6 +47,10 @@ public static <T> ExtendedAttributeKey<T> create(
     return new InternalExtendedAttributeKeyImpl<>(type, key != null ? key : "");
   }
 
+  /**
+   * Return an {@link ExtendedAttributeKey} equivalent to the {@code attributeKey}, caching entries
+   * in {@link #ATTRIBUTE_KEY_CACHE}.
+   */
   @SuppressWarnings("unchecked")
   public static <T> ExtendedAttributeKey<T> fromAttributeKey(AttributeKey<T> attributeKey) {
     return (ExtendedAttributeKey<T>)
@@ -120,7 +124,11 @@ private static int buildHashCode(ExtendedAttributeType type, String key) {
     return result;
   }
 
-  /** TODO. */
+  /**
+   * Return the equivalent {@link AttributeKey} for the {@link ExtendedAttributeKey}, or {@code
+   * null} if the {@link #getType()} has no equivalent {@link
+   * io.opentelemetry.api.common.AttributeType}.
+   */
   @Nullable
   public static <T> AttributeKey<T> toAttributeKey(ExtendedAttributeKey<T> extendedAttributeKey) {
     switch (extendedAttributeKey.getType()) {
@@ -145,15 +153,14 @@ public static <T> AttributeKey<T> toAttributeKey(ExtendedAttributeKey<T> extende
       case DOUBLE_ARRAY:
         return InternalAttributeKeyImpl.create(
             extendedAttributeKey.getKey(), AttributeType.DOUBLE_ARRAY);
-      case MAP:
-      case MAP_ARRAY:
+      case EXTENDED_ATTRIBUTES:
         return null;
     }
     throw new IllegalArgumentException(
         "Unrecognized extendedAttributeKey type: " + extendedAttributeKey.getType());
   }
 
-  /** TODO. */
+  /** Return the equivalent {@link ExtendedAttributeKey} for the {@link AttributeKey}. */
   public static <T> ExtendedAttributeKey<T> toExtendedAttributeKey(AttributeKey<T> attributeKey) {
     switch (attributeKey.getType()) {
       case STRING: