Package io.opentelemetry.api.incubator.common

Interface ExtendedAttributes

@Immutable public interface ExtendedAttributes
An immutable container for extended attributes.

"extended" refers an extended set of allowed value types compared to standard Attributes. Notably, ExtendedAttributes values can be of type ExtendedAttributeType.VALUE, allowing attributes backed by Value.

Where standard Attributes are accepted everyone that OpenTelemetry represents key / value pairs, ExtendedAttributes are only accepted in select places, such as log records (e.g. ExtendedLogRecordBuilder.setAttribute(ExtendedAttributeKey, Object)).

The keys are ExtendedAttributeKeys 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 ExtendedAttributesBuilder.

Convenience methods are provided for translating to / from Attributes:

  • Method Details

    • get

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

    • get

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

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

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

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

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

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

    • forEach

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

      Note: ExtendedAttributeType.VALUE attributes will be represented as simple attributes if possible. See ExtendedAttributesBuilder.put(ExtendedAttributeKey, 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<ExtendedAttributeKey<?>,Object> asMap()
      Returns a read-only view of this ExtendedAttributes as a Map.

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

    • asAttributes

      io.opentelemetry.api.common.Attributes asAttributes()
      Return a view of this extended attributes with entries limited to those representable as standard attributes.

    • empty

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

    • builder

      static ExtendedAttributesBuilder builder()
      Returns a new ExtendedAttributesBuilder instance for creating arbitrary ExtendedAttributes.
      Returns:
      a new ExtendedAttributesBuilder instance

    • toBuilder

      ExtendedAttributesBuilder toBuilder()
      Returns a new ExtendedAttributesBuilder instance populated with the data of this ExtendedAttributes.