Reboot the entity prototype

- Create Entity/EntityBuilder class in internal package
- Update serialization code

Need to discuss how to work with Resource going forward.

Author: jsuereth

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.getIdentifyingAttributes().asMap().keySet().stream()
+            .map(key -> key.getKey().getBytes(StandardCharsets.UTF_8))
+            .toArray(byte[][]::new),
+        e.getAttributes().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

@@ -37,7 +37,9 @@ public static ResourceMarshaler create(io.opentelemetry.sdk.resources.Resource r
 
       RealResourceMarshaler realMarshaler =
           new RealResourceMarshaler(
-              KeyValueMarshaler.createForAttributes(resource.getAttributes()));
+              KeyValueMarshaler.createForAttributes(resource.getAttributes()),
+              // TODO(jsuereth): This will support EntityRef in the future.
+              new EntityRefMarshaler[] {});
 
       ByteArrayOutputStream binaryBos =
           new ByteArrayOutputStream(realMarshaler.getBinarySerializedSize());
@@ -70,19 +72,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;
     }
   }
 }

exporters/otlp/common/src/test/java/io/opentelemetry/exporter/internal/otlp/EntityRefMarshalerTest.java

@@ -0,0 +1,86 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.exporter.internal.otlp;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.google.protobuf.InvalidProtocolBufferException;
+import com.google.protobuf.Message;
+import com.google.protobuf.util.JsonFormat;
+import io.opentelemetry.exporter.internal.marshal.Marshaler;
+import io.opentelemetry.proto.common.v1.EntityRef;
+import io.opentelemetry.sdk.resources.internal.Entity;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.nio.charset.StandardCharsets;
+import org.junit.jupiter.api.Test;
+
+class EntityRefMarshalerTest {
+  @Test
+  void toEntityRefs() {
+    Entity e =
+        Entity.builder("test")
+            .setSchemaUrl("test-url")
+            .withDescriptive(attr -> attr.put("desc.key", "desc.value"))
+            .withIdentifying(attr -> attr.put("id.key", "id.value"))
+            .build();
+    EntityRef proto = parse(EntityRef.getDefaultInstance(), EntityRefMarshaler.createForEntity(e));
+    assertThat(proto.getType()).isEqualTo("test");
+    assertThat(proto.getSchemaUrl()).isEqualTo("test-url");
+    assertThat(proto.getIdKeysList()).containsExactly("id.key");
+    assertThat(proto.getDescriptionKeysList()).containsExactly("desc.key");
+  }
+
+  @SuppressWarnings("unchecked")
+  private static <T extends Message> T parse(T prototype, Marshaler marshaler) {
+    byte[] serialized = toByteArray(marshaler);
+    T result;
+    try {
+      result = (T) prototype.newBuilderForType().mergeFrom(serialized).build();
+    } catch (InvalidProtocolBufferException e) {
+      throw new UncheckedIOException(e);
+    }
+    // Our marshaler should produce the exact same length of serialized output (for example, field
+    // default values are not outputted), so we check that here. The output itself may have slightly
+    // different ordering, mostly due to the way we don't output oneof values in field order all the
+    // tieme. If the lengths are equal and the resulting protos are equal, the marshaling is
+    // guaranteed to be valid.
+    assertThat(result.getSerializedSize()).isEqualTo(serialized.length);
+
+    // Compare JSON
+    String json = toJson(marshaler);
+    Message.Builder builder = prototype.newBuilderForType();
+    try {
+      JsonFormat.parser().merge(json, builder);
+    } catch (InvalidProtocolBufferException e) {
+      throw new UncheckedIOException(e);
+    }
+    assertThat(builder.build()).isEqualTo(result);
+
+    return result;
+  }
+
+  private static byte[] toByteArray(Marshaler marshaler) {
+    ByteArrayOutputStream bos = new ByteArrayOutputStream();
+    try {
+      marshaler.writeBinaryTo(bos);
+    } catch (IOException e) {
+      throw new UncheckedIOException(e);
+    }
+    return bos.toByteArray();
+  }
+
+  private static String toJson(Marshaler marshaler) {
+    ByteArrayOutputStream bos = new ByteArrayOutputStream();
+    try {
+      marshaler.writeJsonTo(bos);
+    } catch (IOException e) {
+      throw new UncheckedIOException(e);
+    }
+    return new String(bos.toByteArray(), StandardCharsets.UTF_8);
+  }
+}

sdk/common/src/main/java/io/opentelemetry/sdk/resources/internal/Entity.java

@@ -0,0 +1,78 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.sdk.resources.internal;
+
+import com.google.auto.value.AutoValue;
+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.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
+ */
+@Immutable
+@AutoValue
+public abstract class Entity {
+  /**
+   * Returns the entity type string of this entity. Must not be null.
+   *
+   * @return the entity type.
+   */
+  public abstract String getType();
+
+  /**
+   * Returns a map of attributes that identify the entity.
+   *
+   * @return a map of attributes.
+   */
+  public abstract Attributes getIdentifyingAttributes();
+
+  /**
+   * Returns a map of attributes that describe the entity.
+   *
+   * @return a map of attributes.
+   */
+  public abstract Attributes getAttributes();
+
+  /**
+   * 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
+  public abstract String getSchemaUrl();
+
+  static final Entity create(
+      String entityType,
+      Attributes identifying,
+      Attributes descriptive,
+      @Nullable String schemaUrl) {
+    return new AutoValue_Entity(entityType, identifying, descriptive, schemaUrl);
+  }
+
+  public final EntityBuilder toBuilder() {
+    return new EntityBuilder(this);
+  }
+
+  public static final EntityBuilder builder(String entityType) {
+    return new EntityBuilder(entityType);
+  }
+}

sdk/common/src/main/java/io/opentelemetry/sdk/resources/internal/EntityBuilder.java

@@ -0,0 +1,78 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.sdk.resources.internal;
+
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.common.AttributesBuilder;
+import java.util.function.Consumer;
+import javax.annotation.Nullable;
+
+/**
+ * A builder of {@link Entity} that allows to add identifying or descriptive {@link Attributes}, as
+ * well as type and schema_url.
+ *
+ * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
+ * at any time.
+ */
+public class EntityBuilder {
+  private final String entityType;
+  private final AttributesBuilder attributesBuilder;
+  private final AttributesBuilder identifyingBuilder;
+  @Nullable private String schemaUrl;
+
+  EntityBuilder(String entityType) {
+    this.entityType = entityType;
+    this.attributesBuilder = Attributes.builder();
+    this.identifyingBuilder = Attributes.builder();
+  }
+
+  EntityBuilder(Entity seed) {
+    this.entityType = seed.getType();
+    this.schemaUrl = seed.getSchemaUrl();
+    this.identifyingBuilder = seed.getIdentifyingAttributes().toBuilder();
+    this.attributesBuilder = seed.getAttributes().toBuilder();
+  }
+
+  /**
+   * 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
+   */
+  public EntityBuilder setSchemaUrl(String schemaUrl) {
+    this.schemaUrl = schemaUrl;
+    return this;
+  }
+
+  /**
+   * Modify the descriptive attributes of this Entity.
+   *
+   * @param f A thunk which manipulates descriptive attributes.
+   * @return this
+   */
+  public EntityBuilder withDescriptive(Consumer<AttributesBuilder> f) {
+    f.accept(this.attributesBuilder);
+    return this;
+  }
+
+  /**
+   * Modify the identifying attributes of this Entity.
+   *
+   * @param f A thunk which manipulates identifying attributes.
+   * @return this
+   */
+  public EntityBuilder withIdentifying(Consumer<AttributesBuilder> f) {
+    f.accept(this.identifyingBuilder);
+    return this;
+  }
+
+  /** Create the {@link Entity} from this. */
+  public Entity build() {
+    // TODO - Better Checks, e.g. identifying attributes are non-zero.
+    return Entity.create(
+        entityType, identifyingBuilder.build(), attributesBuilder.build(), schemaUrl);
+  }
+}