Skip to content

Commit faead7f

Browse files
committed
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.
1 parent b4bb23c commit faead7f

File tree

1 file changed

+30
-5
lines changed

1 file changed

+30
-5
lines changed

specification/entities/data-model.md

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ weight: 2
1717
- [Identifying Attributes](#identifying-attributes)
1818
- [Resource and Entities](#resource-and-entities)
1919
* [Attribute Referencing Model](#attribute-referencing-model)
20+
* [Entity Type Uniqueness](#entity-type-uniqueness)
21+
* [Attribute Ownership](#attribute-ownership)
2022
* [Placement of Shared Descriptive Attributes](#placement-of-shared-descriptive-attributes)
2123
- [Examples of Entities](#examples-of-entities)
2224

@@ -127,17 +129,40 @@ entities. The model provides:
127129
- The ability to avoid data duplication and inconsistencies.
128130
- A more efficient representation for encoding and transmission.
129131

132+
### Entity Type Uniqueness
133+
134+
All entities associated with a resource MUST have unique types. No two entities
135+
within the same resource can share the same entity type.
136+
137+
This ensures unambiguous identification when referencing entities within a
138+
resource. Combined with the convention that identifying attributes use the
139+
entity type as a prefix (e.g., `host.id` for `host` entity, `k8s.node.uid` for
140+
`k8s.node` entity), this guarantees that identifying attributes from different
141+
entities will never share the same keys in the resource attributes map.
142+
143+
### Attribute Ownership
144+
145+
Each resource attribute key MUST be owned by at most one entity within a
146+
resource. When an entity adds an attribute to the shared resource attributes
147+
map, no other entity in that resource can reference or modify that same
148+
attribute key. This prevents data inconsistencies where multiple entities could
149+
otherwise compete for control of the same attribute.
150+
151+
For identifying attributes, ownership is implicitly enforced by the combination
152+
of entity type uniqueness and the prefix naming convention. For descriptive
153+
attributes, ownership is determined by the placement rules described in the
154+
following section.
155+
130156
### Placement of Shared Descriptive Attributes
131157

132158
Attribute flattening allows multiple entities to reference the same attribute key,
133159
but with different values across the entities. In such situations, the following
134160
rule applies:
135161

136-
If multiple entities share the same descriptive attribute key with potentially
137-
conflicting values, the attribute MUST logically belong to **only one** of them.
138-
All others SHOULD NOT reference it. The attribute MUST be referenced by the
139-
**most specific** entity, the one closest in the topology graph to the entity
140-
associated with the telemetry signal.
162+
If multiple entities share the same descriptive attribute key, the attribute
163+
MUST logically belong to **only one** of them. All others SHOULD NOT reference
164+
it. The attribute MUST be referenced by the **most specific** entity, the one
165+
closest in the topology graph to the entity associated with the telemetry signal.
141166

142167
**Example:**
143168

0 commit comments

Comments
 (0)