From f788395454bb459069b98c530049dfb9b60b400e Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 1 Dec 2025 09:54:16 -0500 Subject: [PATCH 1/5] Initial entity merge specification. --- specification/entities/data-model.md | 36 ++++++++++++++++++++++++++++ specification/resource/data-model.md | 31 ++++++++++++++++++++++++ 2 files changed, 67 insertions(+) diff --git a/specification/entities/data-model.md b/specification/entities/data-model.md index 4c7c088657c..f3a9d7b3f1b 100644 --- a/specification/entities/data-model.md +++ b/specification/entities/data-model.md @@ -149,6 +149,42 @@ different values, then **only** the `k8s.node` entity can reference this key Other entities (e.g., `k8s.cluster`) can report this attribute in a separate telemetry channel (e.g., entity events) where full ownership context is known. +## Merging of Entities + +Entities MAY be merged if and only if their types are the same, their +identity attributes are exactly the same AND their schema_url is the same. +This means both Entities MUST have the same identity attribute keys and +for each key, the values of the key MUST be the same. + +Here's an example algorithm that will check compatibility: + +``` +can_merge(e, e') { + e.type == e'.type && + e.schema_url == e'.schema_url && + has_same_attributes(e.identity, e'.identity) +} +``` + +When merging entities, all attributes in description are merged together, with +one entity acting as "primary" where any conficting attribute values will be +chosen from the "primary" entity. + +Here's an example algorithm that will merge: + +``` +merge(e, e') { + if can_merge(e, e') { + for attribute in e'.description { + if !e.description.contains(attribute.key) { + e.description.insert(attribute) + } + // Ignore otehrwise. + } + } +} +``` + ## Examples of Entities _This section is non-normative and is present only for the purposes of diff --git a/specification/resource/data-model.md b/specification/resource/data-model.md index 6a9d579dc07..ed671990648 100644 --- a/specification/resource/data-model.md +++ b/specification/resource/data-model.md @@ -47,3 +47,34 @@ different if one contains an entity not found in the other. Some resources include raw attributes in additon to Entities. Raw attributes are considered identifying on a resource. That is, if the key-value pairs of raw attributes are different, then you can assume the resource is different. + +## Merging Resources + +Note: The current SDK specification outlines a [merge algorithm](sdk#merge). +This specification updates the algorithm to be compliant with entities. This +section will replace that section upon stabilization of entities. + +Merging resources is an action of joining together the context of observation. +That is, we can look at the resource context for a signal and *expand* that +context to include more details (see +[telescoping identity](README.md#telescoping)). As such, a merge SHOULD preserve +any identity that already existed on a Resource while adding in new identifying +information or descriptive attributes. + +### Merging Entities into a Resource + +We define the following algorithm for merging entities into an existing +resource. + +- Construct a set of existing entities on the resource, `E`. + - For each entity, `new_entity`, in priority order (highest first), + do one of the following: + - If an entity `e'` exsits in `E` with the same entity type as `new_entity`: + - Profrm a [Entity DataModel Merge](../entities/data-model.md#merging-of-entities), if applicable, otherwise ignore `new_entity`. + - Otherwise, add the entity `d'` to set `E` +- Update the Resource to use the set of entities `E`. + - If all entities within `E` have the same `schema_url`, set the + resources `schema_url` to match. + - Otherwise set the Resource `schema_url` blank. + - Remove any attribute from `Attributes` which exists in either the + description or identity of an entity in `E`. From 321199dd7334d17e7a89656a27dac67405172fe4 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 1 Dec 2025 09:55:43 -0500 Subject: [PATCH 2/5] markdown toc. --- specification/entities/data-model.md | 1 + specification/resource/data-model.md | 2 ++ 2 files changed, 3 insertions(+) diff --git a/specification/entities/data-model.md b/specification/entities/data-model.md index f3a9d7b3f1b..436c468519e 100644 --- a/specification/entities/data-model.md +++ b/specification/entities/data-model.md @@ -18,6 +18,7 @@ weight: 2 - [Resource and Entities](#resource-and-entities) * [Attribute Referencing Model](#attribute-referencing-model) * [Placement of Shared Descriptive Attributes](#placement-of-shared-descriptive-attributes) +- [Merging of Entities](#merging-of-entities) - [Examples of Entities](#examples-of-entities) diff --git a/specification/resource/data-model.md b/specification/resource/data-model.md index ed671990648..9847b1fe25b 100644 --- a/specification/resource/data-model.md +++ b/specification/resource/data-model.md @@ -13,6 +13,8 @@ weight: 2 - [Identity](#identity) +- [Merging Resources](#merging-resources) + * [Merging Entities into a Resource](#merging-entities-into-a-resource) From 5f7deebf9f9b7e1ff890bdb6fd23d6080565cb92 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 1 Dec 2025 09:59:22 -0500 Subject: [PATCH 3/5] Fix lint. --- specification/entities/data-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/entities/data-model.md b/specification/entities/data-model.md index 436c468519e..941313cdff9 100644 --- a/specification/entities/data-model.md +++ b/specification/entities/data-model.md @@ -152,7 +152,7 @@ telemetry channel (e.g., entity events) where full ownership context is known. ## Merging of Entities -Entities MAY be merged if and only if their types are the same, their +Entities MAY be merged if and only if their types are the same, their identity attributes are exactly the same AND their schema_url is the same. This means both Entities MUST have the same identity attribute keys and for each key, the values of the key MUST be the same. From 9b29ce298b5e4eb38234cd0fc5d01430226d5c74 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 1 Dec 2025 12:11:29 -0500 Subject: [PATCH 4/5] Fix spelling mistake and update note on merge algorithm. --- specification/resource/data-model.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/resource/data-model.md b/specification/resource/data-model.md index 9847b1fe25b..1f8d2e0e5a9 100644 --- a/specification/resource/data-model.md +++ b/specification/resource/data-model.md @@ -54,7 +54,8 @@ raw attributes are different, then you can assume the resource is different. Note: The current SDK specification outlines a [merge algorithm](sdk#merge). This specification updates the algorithm to be compliant with entities. This -section will replace that section upon stabilization of entities. +section will replace that section upon stabilization of entities. SDKs SHOULD +NOT update their merge algorithm until full Entity SDK support is provided. Merging resources is an action of joining together the context of observation. That is, we can look at the resource context for a signal and *expand* that @@ -72,7 +73,7 @@ resource. - For each entity, `new_entity`, in priority order (highest first), do one of the following: - If an entity `e'` exsits in `E` with the same entity type as `new_entity`: - - Profrm a [Entity DataModel Merge](../entities/data-model.md#merging-of-entities), if applicable, otherwise ignore `new_entity`. + - Perform a [Entity DataModel Merge](../entities/data-model.md#merging-of-entities), if applicable, otherwise ignore `new_entity`. - Otherwise, add the entity `d'` to set `E` - Update the Resource to use the set of entities `E`. - If all entities within `E` have the same `schema_url`, set the From 53cbb1835d4b7f59d46fc52823838695e28b66b5 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 1 Dec 2025 12:25:40 -0500 Subject: [PATCH 5/5] Fix algorithm to not use d' from teh OTEP. --- specification/resource/data-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/resource/data-model.md b/specification/resource/data-model.md index 1f8d2e0e5a9..a48c523adcd 100644 --- a/specification/resource/data-model.md +++ b/specification/resource/data-model.md @@ -74,7 +74,7 @@ resource. do one of the following: - If an entity `e'` exsits in `E` with the same entity type as `new_entity`: - Perform a [Entity DataModel Merge](../entities/data-model.md#merging-of-entities), if applicable, otherwise ignore `new_entity`. - - Otherwise, add the entity `d'` to set `E` + - Otherwise, add the entity `new_entity` to set `E` - Update the Resource to use the set of entities `E`. - If all entities within `E` have the same `schema_url`, set the resources `schema_url` to match.