[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.80952% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.24%. Comparing base (06423fb) to head (7a749a2).
⚠️ Report is 3 commits behind head on main.

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4490      +/-   ##
==========================================
+ Coverage   83.13%   83.24%   +0.12%     
==========================================
  Files         519      521       +2     
  Lines       20256    20414     +158     
==========================================
+ Hits        16837    16991     +154     
- Misses       3419     3423       +4     

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

... and 1 file with indirect coverage changes

🚀 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!