[SDK] Add Entity support to Resource

[shashankxrm]

Part of #3652. This PR implements the SDK Resource portion of entity propagation; follow-up work remains as noted below.

Changes

Adds Entity support to the SDK Resource library, which is the next step identified on #3652 now that EnvEntityDetector / OTEL_ENTITIES parsing exists (#3795).

This PR:

• Introduces an Entity value type (type, identity, description, schema URL).
• Stores entities on Resource together with unassociated attributes.
• Keeps GetAttributes() as the flattened view: entity identity and description plus unassociated attributes, as required when entities are present.
• Adds GetEntities() and GetUnassociatedAttributes().
• Adds a three-argument Resource constructor that accepts attributes, schema URL, and entities, with entity validation and normalization.
• Adds entity-aware Merge when either resource contains entities.
• Adds Resource::Create(attributes, schema_url, entities) while leaving the existing two-argument Create in place.
• Extends sdk/test/resource coverage (new entity_test, plus Resource construction / merge / Create cases).

This does not complete entity propagation end-to-end. Detectors still emit flattened attributes, and exporters are unchanged.

Merge behavior

Attribute-only merge is unchanged: if neither resource has entities, the existing attribute merge behavior is preserved.

If either resource has entities, merge follows the resource data model:

• Start from the old resource’s entities. For each updating entity of the same type, overlay descriptions if identity and schema URL match; otherwise keep the old entity (identity or schema mismatch). New types are appended.
• Updating unassociated attributes take precedence over old unassociated attributes (same map-insert rule as today).
• An updating loose attribute that uses a key owned by an entity evicts that entity (specification Example 2).
• Entity type priority is taken from the updating resource’s entity order first, then types that exist only on the old resource. After ranking, construction-time key uniqueness drops the lower-priority entity when two entities share an attribute key.
• If surviving entities share one schema URL, that becomes the resource schema URL; if they differ, the resource schema URL is blank. If no entities survive, the historical (non-entity) schema URL rule is used.

These rules match specification Examples 1–3 (loose attribute vs entity, updating loose attribute evicting an entity, same-type identity mismatch plus key conflict dropping the lower-priority entity).

Two points are specified less tightly than the examples, so this implementation is an interpretation:

• Priority across two full resources. The data model describes merging entities in priority order (typically detector order). Here, types present on the updating resource rank above types that exist only on the old resource, which is what Example 3 requires in order to keep host and drop service.
• Schema URL when the entity set becomes empty. The “all surviving entities share a schema URL” rule does not apply; this code falls back to the historical schema URL merge.

Create still does GetDefault().Merge(OTELResourceDetector).Merge(user resource). When both attributes and entities are passed, the user resource is built so entity-owned keys are not left as unassociated attributes (equivalent to creating from attributes and then merging a resource that holds those entities). [service.name](http://service.name/) fallback inspects flattened attributes so an entity-owned [service.name](http://service.name/) is not overwritten.

Compatibility

• Existing two-argument Resource constructors are unchanged.
• Existing Resource::Create(attributes, schema_url) is unchanged for callers; it delegates to the new overload with an empty entity list.
• Attribute-only Merge behavior is preserved.
• New APIs are additive (Entity, getters, three-argument constructor, Create overload).

Resource now stores entities_ and unassociated_attributes_ in addition to the flattened attributes_ map, so object layout changes. This is an SDK type; this PR does not claim ABI stability across versions.

Scope / Follow-up work

This PR is limited to the SDK Resource library, as discussed on #3652: add entities to Resource first, then populate detectors and OTLP.

Intentionally not in this PR:

• Populating Entity objects from resource detectors (including EnvEntityDetector, which still returns flattened attributes).
• Changing OTEL_ENTITIES parsing.
• OTLP / protobuf entity_refs (or exporter attribute helpers).
• ResourceDetector::Create overload that accepts entities.
• Running EnvEntityDetector from default Resource::Create() (it remains opt-in via opentelemetry_resource_detectors).
• SdkBuilder / declarative configuration.

Those are follow-up steps, not omissions.

Testing

Locally:

• entity_test: 8/8 passed
• resource_test: 51/51 passed (existing Resource tests kept as regression coverage)
• clang-format-18 --Werror -n passed

CI has not run on this PR yet.

References

• Implement entity propagation #3652
• Entity propagation
• OTEP 0264 — Resource and Entities
• Resource data model
• Resource SDK — Create
• Resource SDK — Merge without entities
• Resource SDK — Merge with entities
• [SDK] Implement EnvEntityDetector for OTEL_ENTITIES parsing (#3652) #3795 (EnvEntityDetector; out of scope here)

• CHANGELOG.md updated for non-trivial changes
• Unit tests have been added
• Changes in public API reviewed

[codecov]

Codecov Report

❌ Patch coverage is 98.73418% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.55%. Comparing base (e81d957) to head (f4bf097).

Files with missing lines	Patch %	Lines
sdk/src/resource/resource.cc	98.37%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4490      +/-   ##
==========================================
+ Coverage   86.41%   86.55%   +0.14%     
==========================================
  Files         524      525       +1     
  Lines       20435    20660     +225     
==========================================
+ Hits        17657    17880     +223     
- Misses       2778     2780       +2     

Files with missing lines	Coverage Δ
sdk/include/opentelemetry/sdk/resource/resource.h	100.00% <ø> (ø)
sdk/src/resource/entity.cc	100.00% <100.00%> (ø)
sdk/src/resource/resource.cc	98.04% <98.37%> (+3.93%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[shashankxrm]

Hi @dbarker, I’ve opened a PR implementing the SDK Resource Entity support discussed here: #3652

It covers the Resource data model, entity-aware Create/Merge behavior, flattening, and tests. Detectors and OTLP integration are intentionally left for the follow-up steps you mentioned.

All CI checks are currently passing. Would appreciate your feedback when you get a chance.

[dbarker]

Hi @dbarker, I’ve opened a PR implementing the SDK Resource Entity support discussed here: #3652

It covers the Resource data model, entity-aware Create/Merge behavior, flattening, and tests. Detectors and OTLP integration are intentionally left for the follow-up steps you mentioned.

All CI checks are currently passing. Would appreciate your feedback when you get a chance.

Thanks for the PR! I will review later this week. We are working towards a release soon and this PR likely be held back until the release is completed.

[shashankxrm]

Hi @dbarker, I’ve opened a PR implementing the SDK Resource Entity support discussed here: #3652

It covers the Resource data model, entity-aware Create/Merge behavior, flattening, and tests. Detectors and OTLP integration are intentionally left for the follow-up steps you mentioned.

All CI checks are currently passing. Would appreciate your feedback when you get a chance.

Thanks for the PR! I will review later this week. We are working towards a release soon and this PR likely be held back until the release is completed.

Thanks for the update!

[dbarker]

Thanks for the PR! Looks good overall and covers the Resource API expansion from spec 1.60.0

• Create now takes Entities
• Retrieve entities and unassociated attributes is supported with new accessors

The merge algorithms appear well tested with the legacy merge without entities is unaffected.

Please see minor feedback below.

[dbarker]

Thanks for the updates. Approved with a request for minor cleanup and to add comments with spec details on the merge algorithms.

[ThomsonTan]

Constructor normalization drops conflicting entities before loose-attribute cleanup and schema selection. This can retain a stale service.name and report schema-A instead of the required empty schema. Please compute both results from the pre-conflict entity set in the merge path, then preserve them through entity removal.

[shashankxrm]

addressed

[ThomsonTan]

Non-blocking: attribute-only resources now retain two owned copies of their attributes, so callers that never use entities still pay extra storage and copying costs. Please either avoid the second map for entity-free resources or document the intentional tradeoff. A fast path must also update the getter, legacy merge, and service-name fallback rather than merely skipping cache construction.

[shashankxrm]

Thanks, addressed. Attribute-only Resources now use unassociated_attributes_ directly as the flattened representation, while attributes_ remains the cache for entity-aware Resources.

I also updated GetAttributes(), MergeWithoutEntities(), and the service-name fallback accordingly, with regression coverage for the entity-free fallback and the all-entities-evicted merge case.

[lalitb]

Should these identities match when only the C++ integer width differs? For example, two detectors could report the same process.pid as int32_t{123} and int64_t{123}. With the same entity type and schema URL, this still rejects the merge, so any additional description from the second detector is ignored. Is that intentional, or should we compare these as the same integer value?

[shashankxrm]

Entity identity comparison reuses ResourceAttributes / OwnedAttributeValue equality rather than defining a separate numeric comparison. In the C++ SDK, different integer variant alternatives are type-strict, so int32_t{123} and int64_t{123} are not equal, consistent with the existing attribute equality behavior.

The OpenTelemetry data model has a single signed 64-bit integer type; the C++ SDK supports additional integer widths as representation types. We don't want to introduce integer-width normalization only for Entity identity, since that would make Entity identity semantics differ from ResourceAttributes and Entity::operator==.

I will add a regression test documenting the current type-strict identity behavior. Callers should use a consistent integer representation for identifying attributes (preferably int64_t).

Happy to hear your thoughts if you see this differently.

[lalitb]

Thanks for clarifying. I still think these identities should match. OpenTelemetry has one signed integer type, and OTLP exports int32_t{123} and int64_t{123} identically. Rejecting the merge because of the C++ width loses the second entity’s description, even though both identify the same entity.

Could we normalize integer identity values to int64_t in the Entity constructor, including integer arrays and uint64_t values that fit? That would keep identity matching and Entity::operator== consistent without changing ResourceAttributes globally. Please also add a test showing that these two representations merge and retain the incoming description.

[lalitb]

The overall approach looks good. I’m requesting changes until we clarify the integer identity comparison below, since two detectors reporting the same process ID could fail to merge, losing additional details from the second detector.