[DO NOT MERGE] Entity Prototype for SDK Specification

api/incubator/src/main/java/io/opentelemetry/api/incubator/entities/EntityBuilder.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.entities;
+
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.common.AttributesBuilder;
+import java.util.function.Consumer;
+
+/**
+ * A builder of an Entity that allows to add identifying or descriptive {@link Attributes}, as well
+ * as type and schema_url.
+ *
+ * <p>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.
+ */
+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 {@link Consumer} which builds the descriptive attributes.
+   * @return this
+   */
+  EntityBuilder withDescription(Consumer<AttributesBuilder> f);
+
+  /**
+   * Modify the identifying attributes of this Entity.
+   *
+   * @param f A {@link Consumer} which builds the identifying attributes.
+   * @return this
+   */
+  EntityBuilder withId(Consumer<AttributesBuilder> f);
+
+  /** Emits the current entity. */
+  void emit();
+}

api/incubator/src/main/java/io/opentelemetry/api/incubator/entities/ExtendedOpenTelemetry.java

@@ -0,0 +1,21 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.entities;
+
+import io.opentelemetry.api.OpenTelemetry;
+
+/** Extension to {@link OpenTelemetry} that adds {@link ResourceProvider}. */
+public interface ExtendedOpenTelemetry extends OpenTelemetry {
+  /** Returns the {@link ResourceProvider} for this {@link OpenTelemetry}. */
+  default ResourceProvider getResourceProvider() {
+    return ResourceProvider.noop();
+  }
+
+  /** Returns the {@link Resource} that telemetry from this {@link OpenTelemetry} uses. */
+  default Resource getResource() {
+    return getResourceProvider().getResource();
+  }
+}

api/incubator/src/main/java/io/opentelemetry/api/incubator/entities/NoopEntityBuilder.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.entities;
+
+import io.opentelemetry.api.common.AttributesBuilder;
+import java.util.function.Consumer;
+
+final class NoopEntityBuilder implements EntityBuilder {
+  @Override
+  public EntityBuilder setSchemaUrl(String schemaUrl) {
+    return this;
+  }
+
+  @Override
+  public EntityBuilder withDescription(Consumer<AttributesBuilder> f) {
+    return this;
+  }
+
+  @Override
+  public EntityBuilder withId(Consumer<AttributesBuilder> f) {
+    return this;
+  }
+
+  @Override
+  public void emit() {}
+}

api/incubator/src/main/java/io/opentelemetry/api/incubator/entities/NoopResource.java

@@ -0,0 +1,19 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.entities;
+
+final class NoopResource implements Resource {
+
+  @Override
+  public boolean removeEntity(String entityType) {
+    return false;
+  }
+
+  @Override
+  public EntityBuilder attachEntity(String entityType) {
+    return new NoopEntityBuilder();
+  }
+}

api/incubator/src/main/java/io/opentelemetry/api/incubator/entities/NoopResourceProvider.java

@@ -0,0 +1,14 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.entities;
+
+final class NoopResourceProvider implements ResourceProvider {
+
+  @Override
+  public Resource getResource() {
+    return new NoopResource();
+  }
+}

api/incubator/src/main/java/io/opentelemetry/api/incubator/entities/Resource.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.entities;
+
+/** The active resource for which Telemetry is being generated. */
+public interface Resource {
+  /**
+   * Removes an entity from this resource.
+   *
+   * @param entityType the type of entity to remove.
+   * @return true if entity was found and removed.
+   */
+  public boolean removeEntity(String entityType);
+
+  /**
+   * Attaches an entity to the current {@link Resource}.
+   *
+   * @param entityType The type of the entity.
+   * @return A builder that can construct an entity.
+   */
+  public EntityBuilder attachEntity(String entityType);
+}

api/incubator/src/main/java/io/opentelemetry/api/incubator/entities/ResourceProvider.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.entities;
+
+/**
+ * A registry for interacting with {@link Resource}s. The name <i>Provider</i> is for consistency
+ * with other languages and it is <b>NOT</b> loaded using reflection.
+ *
+ * @see Resource
+ */
+public interface ResourceProvider {
+  /**
+   * Returns a no-op {@link ResourceProvider} which only creates no-op {@link Resource}s which do
+   * not record nor are emitted.
+   */
+  static ResourceProvider noop() {
+    return new NoopResourceProvider();
+  }
+
+  /** Returns the active {@link Resource} for which Telemetry is reported. */
+  Resource getResource();
+}

docs/apidiffs/current_vs_latest/opentelemetry-sdk-common.txt

@@ -1,2 +1,5 @@
 Comparing source compatibility of opentelemetry-sdk-common-1.52.0-SNAPSHOT.jar against opentelemetry-sdk-common-1.51.0.jar
-No changes.
+***  MODIFIED CLASS: PUBLIC ABSTRACT io.opentelemetry.sdk.resources.Resource  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.resources.Resource create(io.opentelemetry.api.common.Attributes, java.lang.String, java.util.Collection<io.opentelemetry.sdk.resources.internal.Entity>)
+	***  MODIFIED METHOD: PUBLIC NON_ABSTRACT (<- ABSTRACT) io.opentelemetry.api.common.Attributes getAttributes()

docs/apidiffs/current_vs_latest/opentelemetry-sdk-testing.txt

@@ -1,2 +1,10 @@
 Comparing source compatibility of opentelemetry-sdk-testing-1.52.0-SNAPSHOT.jar against opentelemetry-sdk-testing-1.51.0.jar
-No changes.
++++  NEW CLASS: PUBLIC(+) io.opentelemetry.sdk.testing.assertj.EntityAssert  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.sdk.testing.assertj.EntityAssert hasDescriptionSatisfying(org.assertj.core.api.ThrowingConsumer<io.opentelemetry.api.common.Attributes>)
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.sdk.testing.assertj.EntityAssert hasIdSatisfying(org.assertj.core.api.ThrowingConsumer<io.opentelemetry.api.common.Attributes>)
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.sdk.testing.assertj.EntityAssert hasSchemaUrl(java.lang.String)
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.sdk.testing.assertj.EntityAssert hasType(java.lang.String)
+***  MODIFIED CLASS: PUBLIC FINAL io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.testing.assertj.EntityAssert assertThat(io.opentelemetry.sdk.resources.internal.Entity)

exporters/otlp/common/src/main/java/io/opentelemetry/exporter/internal/otlp/EntityRefMarshaler.java

@@ -0,0 +1,83 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.exporter.internal.otlp;
+
+import io.opentelemetry.api.internal.StringUtils;
+import io.opentelemetry.exporter.internal.marshal.MarshalerUtil;
+import io.opentelemetry.exporter.internal.marshal.MarshalerWithSize;
+import io.opentelemetry.exporter.internal.marshal.Serializer;
+import io.opentelemetry.proto.common.v1.internal.EntityRef;
+import io.opentelemetry.sdk.resources.internal.Entity;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import javax.annotation.Nullable;
+
+/**
+ * A Marshaler of {@link io.opentelemetry.sdk.resources.Entity}.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
+ */
+public final class EntityRefMarshaler extends MarshalerWithSize {
+  @Nullable private final byte[] schemaUrlUtf8;
+  private final byte[] typeUtf8;
+  private final byte[][] idKeysUtf8;
+  private final byte[][] descriptionKeysUtf8;
+
+  @Override
+  protected void writeTo(Serializer output) throws IOException {
+    if (schemaUrlUtf8 != null) {
+      output.writeString(EntityRef.SCHEMA_URL, schemaUrlUtf8);
+    }
+    output.writeString(EntityRef.TYPE, typeUtf8);
+    output.writeRepeatedString(EntityRef.ID_KEYS, idKeysUtf8);
+    output.writeRepeatedString(EntityRef.DESCRIPTION_KEYS, descriptionKeysUtf8);
+  }
+
+  /** Consttructs an entity reference marshaler from a full entity. */
+  public static EntityRefMarshaler createForEntity(Entity e) {
+    byte[] schemaUrlUtf8 = null;
+    if (!StringUtils.isNullOrEmpty(e.getSchemaUrl())) {
+      schemaUrlUtf8 = e.getSchemaUrl().getBytes(StandardCharsets.UTF_8);
+    }
+    return new EntityRefMarshaler(
+        schemaUrlUtf8,
+        e.getType().getBytes(StandardCharsets.UTF_8),
+        e.getId().asMap().keySet().stream()
+            .map(key -> key.getKey().getBytes(StandardCharsets.UTF_8))
+            .toArray(byte[][]::new),
+        e.getDescription().asMap().keySet().stream()
+            .map(key -> key.getKey().getBytes(StandardCharsets.UTF_8))
+            .toArray(byte[][]::new));
+  }
+
+  private EntityRefMarshaler(
+      @Nullable byte[] schemaUrlUtf8,
+      byte[] typeUtf8,
+      byte[][] idKeysUtf8,
+      byte[][] descriptionKeysUtf8) {
+    super(calculateSize(schemaUrlUtf8, typeUtf8, idKeysUtf8, descriptionKeysUtf8));
+    this.schemaUrlUtf8 = schemaUrlUtf8;
+    this.typeUtf8 = typeUtf8;
+    this.idKeysUtf8 = idKeysUtf8;
+    this.descriptionKeysUtf8 = descriptionKeysUtf8;
+  }
+
+  private static int calculateSize(
+      @Nullable byte[] schemaUrlUtf8,
+      byte[] typeUtf8,
+      byte[][] idKeysUtf8,
+      byte[][] descriptionKeysUtf8) {
+    int size = 0;
+    if (schemaUrlUtf8 != null) {
+      size += MarshalerUtil.sizeBytes(EntityRef.SCHEMA_URL, schemaUrlUtf8);
+    }
+    size += MarshalerUtil.sizeBytes(EntityRef.TYPE, typeUtf8);
+    MarshalerUtil.sizeRepeatedString(EntityRef.ID_KEYS, idKeysUtf8);
+    MarshalerUtil.sizeRepeatedString(EntityRef.DESCRIPTION_KEYS, descriptionKeysUtf8);
+    return size;
+  }
+}

exporters/otlp/common/src/main/java/io/opentelemetry/exporter/internal/otlp/ResourceMarshaler.java

@@ -10,6 +10,7 @@
 import io.opentelemetry.exporter.internal.marshal.MarshalerWithSize;
 import io.opentelemetry.exporter.internal.marshal.Serializer;
 import io.opentelemetry.proto.resource.v1.internal.Resource;
+import io.opentelemetry.sdk.resources.internal.EntityUtil;
 import java.io.ByteArrayOutputStream;
 import java.io.IOException;
 import java.io.UncheckedIOException;
@@ -37,7 +38,10 @@ public static ResourceMarshaler create(io.opentelemetry.sdk.resources.Resource r
 
       RealResourceMarshaler realMarshaler =
           new RealResourceMarshaler(
-              KeyValueMarshaler.createForAttributes(resource.getAttributes()));
+              KeyValueMarshaler.createForAttributes(resource.getAttributes()),
+              EntityUtil.getEntities(resource).stream()
+                  .map(EntityRefMarshaler::createForEntity)
+                  .toArray(MarshalerWithSize[]::new));
 
       ByteArrayOutputStream binaryBos =
           new ByteArrayOutputStream(realMarshaler.getBinarySerializedSize());
@@ -70,19 +74,26 @@ public void writeTo(Serializer output) throws IOException {
 
   private static final class RealResourceMarshaler extends MarshalerWithSize {
     private final KeyValueMarshaler[] attributes;
+    private final MarshalerWithSize[] entityRefs;
 
-    private RealResourceMarshaler(KeyValueMarshaler[] attributes) {
-      super(calculateSize(attributes));
+    private RealResourceMarshaler(KeyValueMarshaler[] attributes, MarshalerWithSize[] entityRefs) {
+      super(calculateSize(attributes, entityRefs));
       this.attributes = attributes;
+      this.entityRefs = entityRefs;
     }
 
     @Override
     protected void writeTo(Serializer output) throws IOException {
       output.serializeRepeatedMessage(Resource.ATTRIBUTES, attributes);
+      output.serializeRepeatedMessage(Resource.ENTITY_REFS, entityRefs);
     }
 
-    private static int calculateSize(KeyValueMarshaler[] attributeMarshalers) {
-      return MarshalerUtil.sizeRepeatedMessage(Resource.ATTRIBUTES, attributeMarshalers);
+    private static int calculateSize(
+        KeyValueMarshaler[] attributeMarshalers, MarshalerWithSize[] entityRefs) {
+      int size = 0;
+      size += MarshalerUtil.sizeRepeatedMessage(Resource.ATTRIBUTES, attributeMarshalers);
+      size += size += MarshalerUtil.sizeRepeatedMessage(Resource.ENTITY_REFS, entityRefs);
+      return size;
     }
   }
 }