Add experimental support for log extended attributes (#7123)

Author: jack-berg

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

@@ -26,6 +26,11 @@ public interface AttributeKey<T> {
   /** Returns the type of attribute for this key. Useful for building switch statements. */
   AttributeType getType();
 
+  // TODO (jack-berg): uncomment when extended attributes are promoted from incubator to API
+  // default ExtendedAttributeKey<T> asExtendedAttributeKey() {
+  //  return InternalAttributeKeyImpl.toExtendedAttributeKey(this);
+  // }
+
   /** Returns a new AttributeKey for String valued attributes. */
   static AttributeKey<String> stringKey(String key) {
     return InternalAttributeKeyImpl.create(key, AttributeType.STRING);

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/ArrayBackedExtendedAttributes.java

@@ -0,0 +1,86 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.common;
+
+import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.common.AttributesBuilder;
+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 ArrayBackedExtendedAttributes
+    extends ImmutableKeyValuePairs<ExtendedAttributeKey<?>, Object> implements ExtendedAttributes {
+
+  // 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<ExtendedAttributeKey<?>> KEY_COMPARATOR_FOR_CONSTRUCTION =
+      Comparator.comparing(ExtendedAttributeKey::getKey);
+
+  static final ExtendedAttributes EMPTY = ExtendedAttributes.builder().build();
+
+  @Nullable private Attributes attributes;
+
+  private ArrayBackedExtendedAttributes(
+      Object[] data, Comparator<ExtendedAttributeKey<?>> 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
+   */
+  ArrayBackedExtendedAttributes(Object[] data) {
+    super(data);
+  }
+
+  @Override
+  public ExtendedAttributesBuilder toBuilder() {
+    return new ArrayBackedExtendedAttributesBuilder(new ArrayList<>(data()));
+  }
+
+  @SuppressWarnings("unchecked")
+  @Override
+  @Nullable
+  public <T> T get(ExtendedAttributeKey<T> key) {
+    return (T) super.get(key);
+  }
+
+  @SuppressWarnings("unchecked")
+  @Override
+  public Attributes asAttributes() {
+    if (attributes == null) {
+      AttributesBuilder builder = Attributes.builder();
+      forEach(
+          (extendedAttributeKey, value) -> {
+            AttributeKey<Object> attributeKey =
+                (AttributeKey<Object>) extendedAttributeKey.asAttributeKey();
+            if (attributeKey != null) {
+              builder.put(attributeKey, value);
+            }
+          });
+      attributes = builder.build();
+    }
+    return attributes;
+  }
+
+  static ExtendedAttributes 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) {
+      ExtendedAttributeKey<?> key = (ExtendedAttributeKey<?>) data[i];
+      if (key != null && key.getKey().isEmpty()) {
+        data[i] = null;
+      }
+    }
+    return new ArrayBackedExtendedAttributes(data, KEY_COMPARATOR_FOR_CONSTRUCTION);
+  }
+}

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

@@ -0,0 +1,84 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.common;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import java.util.function.Predicate;
+
+class ArrayBackedExtendedAttributesBuilder implements ExtendedAttributesBuilder {
+  private final List<Object> data;
+
+  ArrayBackedExtendedAttributesBuilder() {
+    data = new ArrayList<>();
+  }
+
+  ArrayBackedExtendedAttributesBuilder(List<Object> data) {
+    this.data = data;
+  }
+
+  @Override
+  public ExtendedAttributes 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 ArrayBackedExtendedAttributes(data.toArray());
+    }
+    return ArrayBackedExtendedAttributes.sortAndFilterToAttributes(data.toArray());
+  }
+
+  @Override
+  public <T> ExtendedAttributesBuilder put(ExtendedAttributeKey<T> key, T value) {
+    if (key == null || key.getKey().isEmpty() || value == null) {
+      return this;
+    }
+    data.add(key);
+    data.add(value);
+    return this;
+  }
+
+  @Override
+  public ExtendedAttributesBuilder removeIf(Predicate<ExtendedAttributeKey<?>> predicate) {
+    if (predicate == null) {
+      return this;
+    }
+    for (int i = 0; i < data.size() - 1; i += 2) {
+      Object entry = data.get(i);
+      if (entry instanceof ExtendedAttributeKey
+          && predicate.test((ExtendedAttributeKey<?>) 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/incubator/src/main/java/io/opentelemetry/api/incubator/common/ExtendedAttributeKey.java

@@ -0,0 +1,100 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.common;
+
+import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.incubator.internal.InternalExtendedAttributeKeyImpl;
+import java.util.List;
+import javax.annotation.Nullable;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * 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. */
+  String getKey();
+
+  /** 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.toExtendedAttributeKey(attributeKey);
+  }
+
+  /** Returns a new ExtendedAttributeKey for String valued attributes. */
+  static ExtendedAttributeKey<String> stringKey(String key) {
+    return fromAttributeKey(AttributeKey.stringKey(key));
+  }
+
+  /** Returns a new ExtendedAttributeKey for Boolean valued attributes. */
+  static ExtendedAttributeKey<Boolean> booleanKey(String key) {
+    return fromAttributeKey(AttributeKey.booleanKey(key));
+  }
+
+  /** Returns a new ExtendedAttributeKey for Long valued attributes. */
+  static ExtendedAttributeKey<Long> longKey(String key) {
+    return fromAttributeKey(AttributeKey.longKey(key));
+  }
+
+  /** Returns a new ExtendedAttributeKey for Double valued attributes. */
+  static ExtendedAttributeKey<Double> doubleKey(String key) {
+    return fromAttributeKey(AttributeKey.doubleKey(key));
+  }
+
+  /** Returns a new ExtendedAttributeKey for List&lt;String&gt; valued attributes. */
+  static ExtendedAttributeKey<List<String>> stringArrayKey(String key) {
+    return fromAttributeKey(AttributeKey.stringArrayKey(key));
+  }
+
+  /** Returns a new ExtendedAttributeKey for List&lt;Boolean&gt; valued attributes. */
+  static ExtendedAttributeKey<List<Boolean>> booleanArrayKey(String key) {
+    return fromAttributeKey(AttributeKey.booleanArrayKey(key));
+  }
+
+  /** Returns a new ExtendedAttributeKey for List&lt;Long&gt; valued attributes. */
+  static ExtendedAttributeKey<List<Long>> longArrayKey(String key) {
+    return fromAttributeKey(AttributeKey.longArrayKey(key));
+  }
+
+  /** Returns a new ExtendedAttributeKey for List&lt;Double&gt; valued attributes. */
+  static ExtendedAttributeKey<List<Double>> doubleArrayKey(String key) {
+    return fromAttributeKey(AttributeKey.doubleArrayKey(key));
+  }
+
+  /** Returns a new ExtendedAttributeKey for Map valued attributes. */
+  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

@@ -0,0 +1,26 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.common;
+
+/**
+ * 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,
+  DOUBLE,
+  STRING_ARRAY,
+  BOOLEAN_ARRAY,
+  LONG_ARRAY,
+  DOUBLE_ARRAY,
+  // Extended types unique to ExtendedAttributes
+  EXTENDED_ATTRIBUTES;
+}