[Prototype] How to support complex attributes in logs/events? (Option C)

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

@@ -0,0 +1,62 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.common;
+
+import io.opentelemetry.api.internal.ImmutableKeyValuePairs;
+import java.util.ArrayList;
+import java.util.Comparator;
+import javax.annotation.Nullable;
+import javax.annotation.concurrent.Immutable;
+
+@Immutable
+final class ArrayBackedComplexAttribute extends ImmutableKeyValuePairs<AttributeKey<?>, Object>
+    implements ComplexAttribute {
+
+  // We only compare the key name, not type, when constructing, to allow deduping keys with the
+  // same name but different type.
+  private static final Comparator<AttributeKey<?>> KEY_COMPARATOR_FOR_CONSTRUCTION =
+      Comparator.comparing(AttributeKey::getKey);
+
+  static final ComplexAttribute EMPTY = ComplexAttribute.builder().build();
+
+  private ArrayBackedComplexAttribute(Object[] data, Comparator<AttributeKey<?>> keyComparator) {
+    super(data, keyComparator);
+  }
+
+  /**
+   * Only use this constructor if you can guarantee that the data has been de-duped, sorted by key
+   * and contains no null values or null/empty keys.
+   *
+   * @param data the raw data
+   */
+  ArrayBackedComplexAttribute(Object[] data) {
+    super(data);
+  }
+
+  @Override
+  public ComplexAttributeBuilder toBuilder() {
+    return new ArrayBackedComplexAttributeBuilder(new ArrayList<>(data()));
+  }
+
+  @SuppressWarnings("unchecked")
+  @Override
+  @Nullable
+  public <T> T get(AttributeKey<T> key) {
+    return (T) super.get(key);
+  }
+
+  static ComplexAttribute sortAndFilterToAttributes(Object... data) {
+    // null out any empty keys or keys with null values
+    // so they will then be removed by the sortAndFilter method.
+    for (int i = 0; i < data.length; i += 2) {
+      AttributeKey<?> key = (AttributeKey<?>) data[i];
+      if (key != null && key.getKey().isEmpty()) {
+        data[i] = null;
+      }
+    }
+    return new ArrayBackedComplexAttribute(data, KEY_COMPARATOR_FOR_CONSTRUCTION);
+  }
+}

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

@@ -0,0 +1,105 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.common;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import java.util.function.Predicate;
+
+class ArrayBackedComplexAttributeBuilder implements ComplexAttributeBuilder {
+  private final List<Object> data;
+
+  ArrayBackedComplexAttributeBuilder() {
+    data = new ArrayList<>();
+  }
+
+  ArrayBackedComplexAttributeBuilder(List<Object> data) {
+    this.data = data;
+  }
+
+  @Override
+  public ComplexAttribute build() {
+    // If only one key-value pair AND the entry hasn't been set to null (by #remove(AttributeKey<T>)
+    // or #removeIf(Predicate<AttributeKey<?>>)), then we can bypass sorting and filtering
+    if (data.size() == 2 && data.get(0) != null) {
+      return new ArrayBackedComplexAttribute(data.toArray());
+    }
+    return ArrayBackedComplexAttribute.sortAndFilterToAttributes(data.toArray());
+  }
+
+  @Override
+  public <T> ComplexAttributeBuilder put(AttributeKey<T> key, T value) {
+    if (key == null || key.getKey().isEmpty() || value == null) {
+      return this;
+    }
+    data.add(key);
+    data.add(value);
+    return this;
+  }
+
+  @Override
+  @SuppressWarnings({"unchecked", "rawtypes"})
+  public ComplexAttributeBuilder putAll(Attributes attributes) {
+    if (attributes == null) {
+      return this;
+    }
+    // Attributes must iterate over their entries with matching types for key / value, so this
+    // downcast to the raw type is safe.
+    attributes.forEach((key, value) -> put((AttributeKey) key, value));
+    return this;
+  }
+
+  @Override
+  public <T> ComplexAttributeBuilder remove(AttributeKey<T> key) {
+    if (key == null || key.getKey().isEmpty()) {
+      return this;
+    }
+    return removeIf(
+        entryKey ->
+            key.getKey().equals(entryKey.getKey()) && key.getType().equals(entryKey.getType()));
+  }
+
+  @Override
+  public ComplexAttributeBuilder removeIf(Predicate<AttributeKey<?>> predicate) {
+    if (predicate == null) {
+      return this;
+    }
+    for (int i = 0; i < data.size() - 1; i += 2) {
+      Object entry = data.get(i);
+      if (entry instanceof AttributeKey && predicate.test((AttributeKey<?>) entry)) {
+        // null items are filtered out in ArrayBackedAttributes
+        data.set(i, null);
+        data.set(i + 1, null);
+      }
+    }
+    return this;
+  }
+
+  static List<Double> toList(double... values) {
+    Double[] boxed = new Double[values.length];
+    for (int i = 0; i < values.length; i++) {
+      boxed[i] = values[i];
+    }
+    return Arrays.asList(boxed);
+  }
+
+  static List<Long> toList(long... values) {
+    Long[] boxed = new Long[values.length];
+    for (int i = 0; i < values.length; i++) {
+      boxed[i] = values[i];
+    }
+    return Arrays.asList(boxed);
+  }
+
+  static List<Boolean> toList(boolean... values) {
+    Boolean[] boxed = new Boolean[values.length];
+    for (int i = 0; i < values.length; i++) {
+      boxed[i] = values[i];
+    }
+    return Arrays.asList(boxed);
+  }
+}

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

@@ -65,4 +65,14 @@ static AttributeKey<List<Long>> longArrayKey(String key) {
   static AttributeKey<List<Double>> doubleArrayKey(String key) {
     return InternalAttributeKeyImpl.create(key, AttributeType.DOUBLE_ARRAY);
   }
+
+  /**
+   * Returns a new AttributeKey for complex valued attributes.
+   *
+   * <p>IMPORTANT: complex valued attributes are only supported by Logs. Spans and Metrics do not
+   * support complex valued attributes.
+   */
+  static AttributeKey<ComplexAttribute> complexKey(String key) {
+    return InternalAttributeKeyImpl.create(key, AttributeType.COMPLEX);
+  }
 }

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

@@ -17,5 +17,10 @@ public enum AttributeType {
   STRING_ARRAY,
   BOOLEAN_ARRAY,
   LONG_ARRAY,
-  DOUBLE_ARRAY
+  DOUBLE_ARRAY,
+  /**
+   * IMPORTANT: complex valued attributes are only supported by Logs. Spans and Metrics do not
+   * support complex valued attributes.
+   */
+  COMPLEX
 }

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

@@ -0,0 +1,181 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.common;
+
+import static io.opentelemetry.api.common.ArrayBackedComplexAttribute.sortAndFilterToAttributes;
+
+import java.util.Map;
+import java.util.function.BiConsumer;
+import javax.annotation.Nullable;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * An immutable container for a complex attribute.
+ *
+ * <p>The keys are {@link AttributeKey}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 ComplexAttributeBuilder}.
+ */
+@SuppressWarnings("rawtypes")
+@Immutable
+public interface ComplexAttribute {
+
+  /** Returns the value for the given {@link AttributeKey}, or {@code null} if not found. */
+  @Nullable
+  <T> T get(AttributeKey<T> key);
+
+  /** Iterates over all the key-value pairs of attributes contained by this instance. */
+  void forEach(BiConsumer<? super AttributeKey<?>, ? super Object> consumer);
+
+  /** The number of attributes contained in this. */
+  int size();
+
+  /** Whether there are any attributes contained in this. */
+  boolean isEmpty();
+
+  /** Returns a read-only view of this {@link ComplexAttribute} as a {@link Map}. */
+  Map<AttributeKey<?>, Object> asMap();
+
+  /** Returns a {@link ComplexAttribute} instance with no attributes. */
+  static ComplexAttribute empty() {
+    return ArrayBackedComplexAttribute.EMPTY;
+  }
+
+  /** Returns a {@link ComplexAttribute} instance with a single key-value pair. */
+  static <T> ComplexAttribute of(AttributeKey<T> key, T value) {
+    if (key == null || key.getKey().isEmpty() || value == null) {
+      return empty();
+    }
+    return new ArrayBackedComplexAttribute(new Object[] {key, value});
+  }
+
+  /**
+   * Returns a {@link ComplexAttribute} instance with two key-value pairs. Order of the keys is not
+   * preserved. Duplicate keys will be removed.
+   */
+  static <T, U> ComplexAttribute of(
+      AttributeKey<T> key1, T value1, AttributeKey<U> key2, U value2) {
+    if (key1 == null || key1.getKey().isEmpty() || value1 == null) {
+      return of(key2, value2);
+    }
+    if (key2 == null || key2.getKey().isEmpty() || value2 == null) {
+      return of(key1, value1);
+    }
+    if (key1.getKey().equals(key2.getKey())) {
+      // last one in wins
+      return of(key2, value2);
+    }
+    if (key1.getKey().compareTo(key2.getKey()) > 0) {
+      return new ArrayBackedComplexAttribute(new Object[] {key2, value2, key1, value1});
+    }
+    return new ArrayBackedComplexAttribute(new Object[] {key1, value1, key2, value2});
+  }
+
+  /**
+   * Returns a {@link ComplexAttribute} instance with three key-value pairs. Order of the keys is
+   * not preserved. Duplicate keys will be removed.
+   */
+  static <T, U, V> ComplexAttribute of(
+      AttributeKey<T> key1,
+      T value1,
+      AttributeKey<U> key2,
+      U value2,
+      AttributeKey<V> key3,
+      V value3) {
+    return sortAndFilterToAttributes(key1, value1, key2, value2, key3, value3);
+  }
+
+  /**
+   * Returns a {@link ComplexAttribute} instance with four key-value pairs. Order of the keys is not
+   * preserved. Duplicate keys will be removed.
+   */
+  static <T, U, V, W> ComplexAttribute of(
+      AttributeKey<T> key1,
+      T value1,
+      AttributeKey<U> key2,
+      U value2,
+      AttributeKey<V> key3,
+      V value3,
+      AttributeKey<W> key4,
+      W value4) {
+    return sortAndFilterToAttributes(key1, value1, key2, value2, key3, value3, key4, value4);
+  }
+
+  /**
+   * Returns a {@link ComplexAttribute} instance with five key-value pairs. Order of the keys is not
+   * preserved. Duplicate keys will be removed.
+   */
+  @SuppressWarnings("TooManyParameters")
+  static <T, U, V, W, X> ComplexAttribute of(
+      AttributeKey<T> key1,
+      T value1,
+      AttributeKey<U> key2,
+      U value2,
+      AttributeKey<V> key3,
+      V value3,
+      AttributeKey<W> key4,
+      W value4,
+      AttributeKey<X> key5,
+      X value5) {
+    return sortAndFilterToAttributes(
+        key1, value1,
+        key2, value2,
+        key3, value3,
+        key4, value4,
+        key5, value5);
+  }
+
+  /**
+   * Returns a {@link ComplexAttribute} instance with the given key-value pairs. Order of the keys
+   * is not preserved. Duplicate keys will be removed.
+   */
+  @SuppressWarnings("TooManyParameters")
+  static <T, U, V, W, X, Y> ComplexAttribute of(
+      AttributeKey<T> key1,
+      T value1,
+      AttributeKey<U> key2,
+      U value2,
+      AttributeKey<V> key3,
+      V value3,
+      AttributeKey<W> key4,
+      W value4,
+      AttributeKey<X> key5,
+      X value5,
+      AttributeKey<Y> key6,
+      Y value6) {
+    return sortAndFilterToAttributes(
+        key1, value1,
+        key2, value2,
+        key3, value3,
+        key4, value4,
+        key5, value5,
+        key6, value6);
+  }
+
+  /**
+   * Returns a new {@link ComplexAttributeBuilder} instance for creating arbitrary {@link
+   * ComplexAttribute}.
+   */
+  static ComplexAttributeBuilder builder() {
+    return new ArrayBackedComplexAttributeBuilder();
+  }
+
+  /**
+   * Returns a new {@link ComplexAttributeBuilder} instance populated with the data of this {@link
+   * ComplexAttribute}.
+   */
+  ComplexAttributeBuilder toBuilder();
+}