Package io.opentelemetry.api.common

Interface Attributes

@Immutable public interface Attributes
An immutable container for attributes.

The keys are AttributeKeys and the values are Object instances that match the type of the provided key.

Null keys will be silently dropped.

Note: The behavior of null-valued attributes is undefined, and hence strongly discouraged.

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.

For this reason, it is strongly suggested that you use the implementation that is provided here via the factory methods and the AttributesBuilder.

  • Method Details

    • get

      @Nullable <T> T get(AttributeKey<T> key)
      Returns the value for the given AttributeKey, or null if not found.

      Note: this method will automatically return the corresponding Value instance when passed a key of type AttributeType.VALUE and a simple attribute is found. This is the inverse of AttributesBuilder.put(AttributeKey, Object) when the key is AttributeType.VALUE.

      • If put(AttributeKey.stringKey("key"), "a") was called, then get(AttributeKey.valueKey("key")) returns Value.of("a").
      • If put(AttributeKey.longKey("key"), 1L) was called, then get(AttributeKey.valueKey("key")) returns Value.of(1L).
      • If put(AttributeKey.doubleKey("key"), 1.0) was called, then get(AttributeKey.valueKey("key")) returns Value.of(1.0).
      • If put(AttributeKey.booleanKey("key"), true) was called, then get(AttributeKey.valueKey("key")) returns Value.of(true).
      • If put(AttributeKey.stringArrayKey("key"), Arrays.asList("a", "b")) was called, then get(AttributeKey.valueKey("key")) returns Value.of(Value.of("a"), Value.of("b")).
      • If put(AttributeKey.longArrayKey("key"), Arrays.asList(1L, 2L)) was called, then get(AttributeKey.valueKey("key")) returns Value.of(Value.of(1L), Value.of(2L)).
      • If put(AttributeKey.doubleArrayKey("key"), Arrays.asList(1.0, 2.0)) was called, then get(AttributeKey.valueKey("key")) returns Value.of(Value.of(1.0), Value.of(2.0)).
      • If put(AttributeKey.booleanArrayKey("key"), Arrays.asList(true, false)) was called, then get(AttributeKey.valueKey("key")) returns Value.of(Value.of(true), Value.of(false)).

      Further, if put(AttributeKey.valueKey("key"), Value.of(emptyList())) was called, then

      • get(AttributeKey.stringArrayKey("key"))
      • get(AttributeKey.longArrayKey("key"))
      • get(AttributeKey.booleanArrayKey("key"))
      • get(AttributeKey.doubleArrayKey("key"))

      all return an empty list (as opposed to null).

    • forEach

      void forEach(BiConsumer<? super AttributeKey<?>,? super Object> consumer)
      Iterates over all the key-value pairs of attributes contained by this instance.

      Note: AttributeType.VALUE attributes will be represented as simple attributes if possible. See AttributesBuilder.put(AttributeKey, Object) for more details.

    • size

      int size()
      The number of attributes contained in this.

    • isEmpty

      boolean isEmpty()
      Whether there are any attributes contained in this.

    • asMap

      Map<AttributeKey<?>,Object> asMap()
      Returns a read-only view of this Attributes as a Map.

      Note: AttributeType.VALUE attributes will be represented as simple attributes in this map if possible. See AttributesBuilder.put(AttributeKey, Object) for more details.

    • empty

      static Attributes empty()
      Returns a Attributes instance with no attributes.

    • of

      static <T> Attributes of(AttributeKey<T> key, T value)
      Returns a Attributes instance with a single key-value pair.

    • of

      static <T, U> Attributes of(AttributeKey<T> key1, T value1, AttributeKey<U> key2, U value2)
      Returns a Attributes instance with two key-value pairs. Order of the keys is not preserved. Duplicate keys will be removed.

    • of

      static <T, U, V> Attributes of(AttributeKey<T> key1, T value1, AttributeKey<U> key2, U value2, AttributeKey<V> key3, V value3)
      Returns a Attributes instance with three key-value pairs. Order of the keys is not preserved. Duplicate keys will be removed.

    • of

      static <T, U, V, W> Attributes of(AttributeKey<T> key1, T value1, AttributeKey<U> key2, U value2, AttributeKey<V> key3, V value3, AttributeKey<W> key4, W value4)
      Returns a Attributes instance with four key-value pairs. Order of the keys is not preserved. Duplicate keys will be removed.

    • of

      static <T, U, V, W, X> Attributes 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)
      Returns a Attributes instance with five key-value pairs. Order of the keys is not preserved. Duplicate keys will be removed.

    • of

      static <T, U, V, W, X, Y> Attributes 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)
      Returns a Attributes instance with the given key-value pairs. Order of the keys is not preserved. Duplicate keys will be removed.

    • builder

      static AttributesBuilder builder()
      Returns a new AttributesBuilder instance for creating arbitrary Attributes.

    • toBuilder

      AttributesBuilder toBuilder()
      Returns a new AttributesBuilder instance populated with the data of this Attributes.