[SDK] Add Entity support to Resource

CHANGELOG.md

@@ -15,6 +15,8 @@ Increment the:
 
 ## [Unreleased]
 
+* [SDK] Add Entity support to Resource
+  [#3652](https://github.com/open-telemetry/opentelemetry-cpp/issues/3652)
 * [CONFIGURATION] Add a configuration builder for the host resource detector
   [#4451](https://github.com/open-telemetry/opentelemetry-cpp/issues/4451)
 * [CONFIGURATION] Build the configured resource detectors in SdkBuilder, apply

sdk/include/opentelemetry/sdk/resource/entity.h

@@ -0,0 +1,52 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include <string>
+
+#include "opentelemetry/sdk/common/attribute_utils.h"
+#include "opentelemetry/version.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace sdk
+{
+namespace resource
+{
+
+using ResourceAttributes = opentelemetry::sdk::common::AttributeMap;
+
+class Entity
+{
+public:
+  Entity(const std::string &type,
+         const ResourceAttributes &identity,
+         const ResourceAttributes &description = ResourceAttributes{},
+         const std::string &schema_url         = std::string{}) noexcept;
+
+  Entity(const Entity &)            = default;
+  Entity(Entity &&)                 = default;
+  Entity &operator=(const Entity &) = default;
+  Entity &operator=(Entity &&)      = default;
+
+  ~Entity() = default;
+
+  const std::string &GetType() const noexcept;
+  const ResourceAttributes &GetIdentity() const noexcept;
+  const ResourceAttributes &GetDescription() const noexcept;
+  const std::string &GetSchemaURL() const noexcept;
+
+  bool IsValid() const noexcept;
+
+  bool operator==(const Entity &other) const noexcept;
+
+private:
+  std::string type_;
+  ResourceAttributes identity_;
+  ResourceAttributes description_;
+  std::string schema_url_;
+};
+
+}  // namespace resource
+}  // namespace sdk
+OPENTELEMETRY_END_NAMESPACE

sdk/include/opentelemetry/sdk/resource/resource.h

@@ -4,8 +4,10 @@
 #pragma once
 
 #include <string>
+#include <vector>
 
 #include "opentelemetry/sdk/common/attribute_utils.h"
+#include "opentelemetry/sdk/resource/entity.h"
 #include "opentelemetry/version.h"
 
 OPENTELEMETRY_BEGIN_NAMESPACE
@@ -25,6 +27,20 @@ class Resource
 
   Resource(const ResourceAttributes &attributes, const std::string &schema_url) noexcept;
 
+  /**
+   * Constructs a Resource from attributes, a schema URL, and entities.
+   *
+   * Invalid entities, later entities of a duplicate type, and entities that
+   * share attribute keys with a higher-priority (earlier) entity are dropped.
+   * Keys owned by surviving entities are removed from unassociated attributes.
+   * If any entity survives, the Resource schema URL is taken from those
+   * entities (common URL, or empty if they differ); the constructor schema
+   * URL is used only when no entity survives.
+   */
+  Resource(const ResourceAttributes &attributes,
+           const std::string &schema_url,
+           const std::vector<Entity> &entities) noexcept;
+
   Resource(const Resource &)            = default;
   Resource(Resource &&)                 = default;
   Resource &operator=(const Resource &) = default;
@@ -34,15 +50,21 @@ class Resource
 
   const ResourceAttributes &GetAttributes() const noexcept;
   const std::string &GetSchemaURL() const noexcept;
+  const std::vector<Entity> &GetEntities() const noexcept;
+  const ResourceAttributes &GetUnassociatedAttributes() const noexcept;
 
   /**
    * Returns a new, merged {@link Resource} by merging the current Resource
-   * with the other Resource. In case of a collision, the other Resource takes
-   * precedence.
+   * (old) with the other Resource (updating). In case of a collision, the
+   * other Resource takes precedence for unassociated attributes.
+   *
+   * When neither Resource has entities, attributes and schema URLs follow the
+   * historical merge rules. If schema urls collide, the resulting schema url
+   * is implementation-defined; this implementation picks @p other.
    *
-   * The specification notes that if schema urls collide, the resulting
-   * schema url is implementation-defined. In the C++ implementation, the
-   * schema url of @p other is picked.
+   * When either Resource has entities, merge follows the entity-aware
+   * resource data model: type-rank, description overlay, updating unassociated
+   * keys evicting entities, then construction-time key uniqueness.
    *
    * @param other the Resource that will be merged with this.
    * @returns the newly merged Resource.
@@ -61,6 +83,16 @@ class Resource
   static Resource Create(const ResourceAttributes &attributes,
                          const std::string &schema_url = std::string{});
 
+  /**
+   * Returns a newly created Resource with the specified attributes and
+   * entities. SDK attributes and OTEL attributes are merged in as with the
+   * two-argument Create.
+   */
+
+  static Resource Create(const ResourceAttributes &attributes,
+                         const std::string &schema_url,
+                         const std::vector<Entity> &entities);
+
   /**
    * Returns an Empty resource.
    */
@@ -74,6 +106,11 @@ class Resource
   static Resource &GetDefault();
 
 private:
+  void NormalizeEntities(const std::vector<Entity> &entities) noexcept;
+  void RefreshFlattenedAttributes() noexcept;
+
+  std::vector<Entity> entities_;
+  ResourceAttributes unassociated_attributes_;
   ResourceAttributes attributes_;
   std::string schema_url_;
 };

sdk/src/resource/CMakeLists.txt

@@ -1,7 +1,7 @@
 # Copyright The OpenTelemetry Authors
 # SPDX-License-Identifier: Apache-2.0
 
-add_library(opentelemetry_resources resource.cc resource_detector.cc
+add_library(opentelemetry_resources resource.cc resource_detector.cc entity.cc
                                     detail/percent_decode.cc)
 
 set_target_properties(opentelemetry_resources PROPERTIES EXPORT_NAME resources)

sdk/src/resource/entity.cc

@@ -0,0 +1,63 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+#include "opentelemetry/sdk/resource/entity.h"
+
+#include <string>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#include "opentelemetry/nostd/variant.h"
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace sdk
+{
+namespace resource
+{
+
+Entity::Entity(const std::string &type,
+               const ResourceAttributes &identity,
+               const ResourceAttributes &description,
+               const std::string &schema_url) noexcept
+    : type_(type), identity_(identity), description_(description), schema_url_(schema_url)
+{
+  for (const auto &kv : identity_)
+  {
+    description_.erase(kv.first);
+  }
+}
+
+const std::string &Entity::GetType() const noexcept
+{
+  return type_;
+}
+
+const ResourceAttributes &Entity::GetIdentity() const noexcept
+{
+  return identity_;
+}
+
+const ResourceAttributes &Entity::GetDescription() const noexcept
+{
+  return description_;
+}
+
+const std::string &Entity::GetSchemaURL() const noexcept
+{
+  return schema_url_;
+}
+
+bool Entity::IsValid() const noexcept
+{
+  return !type_.empty() && !identity_.empty();
+}
+
+bool Entity::operator==(const Entity &other) const noexcept
+{
+  return type_ == other.type_ && identity_ == other.identity_ &&
+         description_ == other.description_ && schema_url_ == other.schema_url_;
+}
+
+}  // namespace resource
+}  // namespace sdk
+OPENTELEMETRY_END_NAMESPACE