Skip to content

Commit 17a3002

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 17a3002

File tree

1 file changed

+28
-5
lines changed

1 file changed

+28
-5
lines changed

specification/entities/data-model.md

Lines changed: 28 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -127,17 +127,40 @@ entities. The model provides:
127127
- The ability to avoid data duplication and inconsistencies.
128128
- A more efficient representation for encoding and transmission.
129129

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

132156
Attribute flattening allows multiple entities to reference the same attribute key,
133157
but with different values across the entities. In such situations, the following
134158
rule applies:
135159

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.
160+
If multiple entities share the same descriptive attribute key, the attribute
161+
MUST logically belong to **only one** of them. All others SHOULD NOT reference
162+
it. The attribute MUST be referenced by the **most specific** entity, the one
163+
closest in the topology graph to the entity associated with the telemetry signal.
141164

142165
**Example:**
143166

0 commit comments

Comments
 (0)