From faead7f849ae71152011dd1f4b105ea7576b7180 Mon Sep 17 00:00:00 2001 From: Dmitry Anoshin Date: Sun, 19 Oct 2025 22:13:55 -0700 Subject: [PATCH 1/2] Add Entity Type Uniqueness and Attribute Ownership restrictions While working on adding API for managing the Resource Entity references in collector pipelines, I found that it's very complicated to maintain data integrity if we don't explicitly impose the following restrictions on the data model: 1. Entity Type Uniqueness: Enforces that all entities within a resource must have unique types, ensuring unambiguous identification and preventing attribute key collisions when combined with the prefix naming convention. 2. Attribute Ownership: Ensures each resource attribute key is owned by at most one entity, preventing data inconsistencies from multiple entities competing for control of the same attribute. --- specification/entities/data-model.md | 35 ++++++++++++++++++++++++---- 1 file changed, 30 insertions(+), 5 deletions(-) diff --git a/specification/entities/data-model.md b/specification/entities/data-model.md index 22c277edd82..b81ae42f43b 100644 --- a/specification/entities/data-model.md +++ b/specification/entities/data-model.md @@ -17,6 +17,8 @@ weight: 2 - [Identifying Attributes](#identifying-attributes) - [Resource and Entities](#resource-and-entities) * [Attribute Referencing Model](#attribute-referencing-model) + * [Entity Type Uniqueness](#entity-type-uniqueness) + * [Attribute Ownership](#attribute-ownership) * [Placement of Shared Descriptive Attributes](#placement-of-shared-descriptive-attributes) - [Examples of Entities](#examples-of-entities) @@ -127,17 +129,40 @@ entities. The model provides: - The ability to avoid data duplication and inconsistencies. - A more efficient representation for encoding and transmission. +### Entity Type Uniqueness + +All entities associated with a resource MUST have unique types. No two entities +within the same resource can share the same entity type. + +This ensures unambiguous identification when referencing entities within a +resource. Combined with the convention that identifying attributes use the +entity type as a prefix (e.g., `host.id` for `host` entity, `k8s.node.uid` for +`k8s.node` entity), this guarantees that identifying attributes from different +entities will never share the same keys in the resource attributes map. + +### Attribute Ownership + +Each resource attribute key MUST be owned by at most one entity within a +resource. When an entity adds an attribute to the shared resource attributes +map, no other entity in that resource can reference or modify that same +attribute key. This prevents data inconsistencies where multiple entities could +otherwise compete for control of the same attribute. + +For identifying attributes, ownership is implicitly enforced by the combination +of entity type uniqueness and the prefix naming convention. For descriptive +attributes, ownership is determined by the placement rules described in the +following section. + ### Placement of Shared Descriptive Attributes Attribute flattening allows multiple entities to reference the same attribute key, but with different values across the entities. In such situations, the following rule applies: -If multiple entities share the same descriptive attribute key with potentially -conflicting values, the attribute MUST logically belong to **only one** of them. -All others SHOULD NOT reference it. The attribute MUST be referenced by the -**most specific** entity, the one closest in the topology graph to the entity -associated with the telemetry signal. +If multiple entities share the same descriptive attribute key, the attribute +MUST logically belong to **only one** of them. All others SHOULD NOT reference +it. The attribute MUST be referenced by the **most specific** entity, the one +closest in the topology graph to the entity associated with the telemetry signal. **Example:** From 7e7864bfd0d545ece39cfe49ce4f232e0bc856c7 Mon Sep 17 00:00:00 2001 From: Dmitry Anoshin Date: Thu, 23 Oct 2025 13:55:53 -0700 Subject: [PATCH 2/2] Add an implementation note --- specification/entities/data-model.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/specification/entities/data-model.md b/specification/entities/data-model.md index b81ae42f43b..bb3de6bebbf 100644 --- a/specification/entities/data-model.md +++ b/specification/entities/data-model.md @@ -153,6 +153,14 @@ of entity type uniqueness and the prefix naming convention. For descriptive attributes, ownership is determined by the placement rules described in the following section. +> **Implementation Note**: The above constraints (entity type uniqueness, +> attribute ownership, and identifying attribute naming conventions) define +> validity requirements for Resources. Implementations (SDKs, Collectors) SHOULD +> validate these constraints when constructing or processing Resources. +> Implementations SHOULD reject or log errors for invalid Resources and MAY use +> fallback strategies such as dropping conflicting entities or attributes to +> maintain data integrity. + ### Placement of Shared Descriptive Attributes Attribute flattening allows multiple entities to reference the same attribute key,