Add incubating EntityProvider API for specification work

Author: jsuereth

sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/entities/Entity.java

@@ -0,0 +1,71 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.sdk.extension.incubator.entities;
+
+import io.opentelemetry.api.common.Attributes;
+import javax.annotation.Nullable;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * Entity represents an object of interest associated with produced telemetry: traces, metrics or
+ * logs.
+ *
+ * <p>For example, telemetry produced using OpenTelemetry SDK is normally associated with a Service
+ * entity. Similarly, OpenTelemetry defines system metrics for a host. The Host is the entity we
+ * want to associate metrics with in this case.
+ *
+ * <p>Entities may be also associated with produced telemetry indirectly. For example a service that
+ * produces telemetry is also related with a process in which the service runs, so we say that the
+ * Service entity is related to the Process entity. The process normally also runs on a host, so we
+ * say that the Process entity is related to the Host entity.
+ */
+@Immutable
+public interface Entity {
+  /**
+   * Returns the entity type string of this entity. Must not be null.
+   *
+   * @return the entity type.
+   */
+  String getType();
+
+  /**
+   * Returns a map of attributes that identify the entity.
+   *
+   * @return a map of attributes.
+   */
+  Attributes getId();
+
+  /**
+   * Returns a map of attributes that describe the entity.
+   *
+   * @return a map of attributes.
+   */
+  Attributes getDescription();
+
+  /**
+   * Returns the URL of the OpenTelemetry schema used by this resource. May be null if this entity
+   * does not abide by schema conventions (i.e. is custom).
+   *
+   * @return An OpenTelemetry schema URL.
+   * @since 1.4.0
+   */
+  @Nullable
+  String getSchemaUrl();
+
+  /**
+   * Returns a new {@link EntityBuilder} instance populated with the data of this {@link Entity}.
+   */
+  EntityBuilder toBuilder();
+
+  /**
+   * Returns a new {@link EntityBuilder} instance for creating arbitrary {@link Entity}.
+   *
+   * @param entityType the entity type string of this entity.
+   */
+  public static EntityBuilder builder(String entityType) {
+    return PassthroughEntity.builder(entityType);
+  }
+}

sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/entities/EntityBuilder.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.sdk.extension.incubator.entities;
+
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.common.AttributesBuilder;
+import java.util.function.Consumer;
+
+/**
+ * A builder of {@link Entity} that allows to add identifying or descriptive {@link Attributes}, as
+ * well as type and schema_url.
+ */
+public interface EntityBuilder {
+  /**
+   * Assign an OpenTelemetry schema URL to the resulting Entity.
+   *
+   * @param schemaUrl The URL of the OpenTelemetry schema being used to create this Entity.
+   * @return this
+   */
+  EntityBuilder setSchemaUrl(String schemaUrl);
+
+  /**
+   * Modify the descriptive attributes of this Entity.
+   *
+   * @param f A thunk which manipulates descriptive attributes.
+   * @return this
+   */
+  EntityBuilder withDescription(Consumer<AttributesBuilder> f);
+
+  /**
+   * Modify the identifying attributes of this Entity.
+   *
+   * @param f A thunk which manipulates identifying attributes.
+   * @return this
+   */
+  EntityBuilder withId(Consumer<AttributesBuilder> f);
+
+  /** Create the {@link Entity} from this. */
+  Entity build();
+}

sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/entities/EntityDetector.java

@@ -0,0 +1,22 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.sdk.extension.incubator.entities;
+
+import java.util.Collection;
+
+/**
+ * The Entity detector in the SDK is responsible for detecting possible entities that could identify
+ * the SDK (called "associated entities"). For Example, if the SDK is running in a kubernetes pod,
+ * it may provide an Entity for that pod.
+ */
+public interface EntityDetector {
+  /**
+   * Discovers {@link Entity} and their current attributes.
+   *
+   * @return a list of discovered entities.
+   */
+  public Collection<Entity> detect();
+}

sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/entities/EntityProvider.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.sdk.extension.incubator.entities;
+
+import io.opentelemetry.sdk.resources.Resource;
+
+/**
+ * A provider of {@link Resource} for this SDK.
+ *
+ * <p>{@code EntityProvider} is responsible for:
+ *
+ * <p>- Detecting Entities using registered detectors. - Providing thread-safe access to the current
+ * resource.
+ *
+ * <p>The future of this class may include the ability to add/remove {@link Entity} objects or
+ * re-run detectors.
+ */
+public interface EntityProvider {
+  /** the current {@link Resource} detected. */
+  public Resource getResource();
+
+  /** A builder of {@link EntityProvider}. */
+  public static EntityProviderBuilder builder() {
+    return new SdkEntityProviderBuilder();
+  }
+}

sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/entities/EntityProviderBuilder.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.sdk.extension.incubator.entities;
+
+import io.opentelemetry.sdk.resources.Resource;
+
+/** Builder of {@link EntityProvider}. */
+public interface EntityProviderBuilder {
+  /** Adds an entity detector, which will detect {@link Entity}s to place in the resource. */
+  EntityProviderBuilder addDetector(EntityDetector detector);
+
+  /**
+   * Adds a discovered resource to include in resolving the SDK's resource.
+   *
+   * @deprecated Use {@link #addDetector(EntityDetector)}.
+   */
+  @Deprecated
+  EntityProviderBuilder addDetectedResource(Resource resource);
+
+  /** Sets whether or not default entity detectors will be included. */
+  EntityProviderBuilder includeDefaults(boolean include);
+
+  /**
+   * Returns the SDK entity provider which uses these detectors.
+   *
+   * @return the EntityProvider.
+   */
+  EntityProvider build();
+}

sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/entities/PassthroughEntity.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.sdk.extension.incubator.entities;
+
+import io.opentelemetry.api.common.Attributes;
+import javax.annotation.Nullable;
+
+final class PassthroughEntity implements Entity {
+  private final io.opentelemetry.sdk.resources.internal.Entity entity;
+
+  PassthroughEntity(io.opentelemetry.sdk.resources.internal.Entity entity) {
+    this.entity = entity;
+  }
+
+  io.opentelemetry.sdk.resources.internal.Entity getPassthrough() {
+    return entity;
+  }
+
+  @Override
+  public String getType() {
+    return entity.getType();
+  }
+
+  @Override
+  public Attributes getId() {
+    return entity.getId();
+  }
+
+  @Override
+  public Attributes getDescription() {
+    return entity.getDescription();
+  }
+
+  @Override
+  @Nullable
+  public String getSchemaUrl() {
+    return entity.getSchemaUrl();
+  }
+
+  @Override
+  public EntityBuilder toBuilder() {
+    return new PassthroughEntityBuilder(entity.toBuilder());
+  }
+
+  static EntityBuilder builder(String entityType) {
+    return new PassthroughEntityBuilder(
+        io.opentelemetry.sdk.resources.internal.Entity.builder(entityType));
+  }
+}

sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/entities/PassthroughEntityBuilder.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.sdk.extension.incubator.entities;
+
+import io.opentelemetry.api.common.AttributesBuilder;
+import java.util.function.Consumer;
+
+final class PassthroughEntityBuilder implements EntityBuilder {
+  private final io.opentelemetry.sdk.resources.internal.EntityBuilder builder;
+
+  PassthroughEntityBuilder(io.opentelemetry.sdk.resources.internal.EntityBuilder builder) {
+    this.builder = builder;
+  }
+
+  @Override
+  public EntityBuilder setSchemaUrl(String schemaUrl) {
+    builder.setSchemaUrl(schemaUrl);
+    return this;
+  }
+
+  @Override
+  public EntityBuilder withDescription(Consumer<AttributesBuilder> f) {
+    builder.withDescription(f);
+    return this;
+  }
+
+  @Override
+  public EntityBuilder withId(Consumer<AttributesBuilder> f) {
+    builder.withId(f);
+    return this;
+  }
+
+  @Override
+  public Entity build() {
+    return new PassthroughEntity(builder.build());
+  }
+}

sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/entities/SdkEntityProvider.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.sdk.extension.incubator.entities;
+
+import io.opentelemetry.sdk.resources.Resource;
+
+/**
+ * Instance of {@link EntityProvider}.
+ *
+ * <p>This class doesn't do much now, but will expand in responsibilities.
+ */
+class SdkEntityProvider implements EntityProvider {
+  private final Resource resource;
+
+  SdkEntityProvider(Resource resource) {
+    this.resource = resource;
+  }
+
+  @Override
+  public Resource getResource() {
+    return resource;
+  }
+}

sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/entities/SdkEntityProviderBuilder.java

@@ -0,0 +1,66 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.sdk.extension.incubator.entities;
+
+import io.opentelemetry.sdk.extension.incubator.entities.detectors.ServiceDetector;
+import io.opentelemetry.sdk.extension.incubator.entities.detectors.TelemetrySdkDetector;
+import io.opentelemetry.sdk.resources.Resource;
+import io.opentelemetry.sdk.resources.internal.EntityUtil;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.stream.Collectors;
+
+class SdkEntityProviderBuilder implements EntityProviderBuilder {
+  private final List<EntityDetector> entityDetectors = new ArrayList<>();
+  private final List<Resource> detectedResources = new ArrayList<>();
+  private boolean includeDefaults = true;
+
+  @Override
+  public EntityProviderBuilder addDetector(EntityDetector detector) {
+    this.entityDetectors.add(detector);
+    return this;
+  }
+
+  @Override
+  @Deprecated
+  public EntityProviderBuilder addDetectedResource(Resource resource) {
+    this.detectedResources.add(resource);
+    return this;
+  }
+
+  private final Resource mergeDetectedAndRaw() {
+    if (includeDefaults) {
+      entityDetectors.add(new ServiceDetector());
+      entityDetectors.add(new TelemetrySdkDetector());
+    }
+    Resource result = Resource.empty();
+    for (EntityDetector detector : entityDetectors) {
+      result =
+          result.merge(
+              EntityUtil.addAllEntity(
+                      Resource.builder(),
+                      detector.detect().stream()
+                          .map(e -> ((PassthroughEntity) e).getPassthrough())
+                          .collect(Collectors.toList()))
+                  .build());
+    }
+    for (Resource next : detectedResources) {
+      result = result.merge(next);
+    }
+    return result;
+  }
+
+  @Override
+  public EntityProvider build() {
+    return new SdkEntityProvider(mergeDetectedAndRaw());
+  }
+
+  @Override
+  public EntityProviderBuilder includeDefaults(boolean include) {
+    this.includeDefaults = include;
+    return this;
+  }
+}