Skip to content

Commit 6d31fa7

Browse files
committed
[entities] Define rules for setting identifying attributes
Add a requirement that each entity type must have a canonical set of identifying attributes. Observers unable to provide the full set must either defer to another source or use a different entity type. Resolves #4253
1 parent cdac031 commit 6d31fa7

File tree

1 file changed

+25
-0
lines changed

1 file changed

+25
-0
lines changed

specification/entities/data-model.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99

1010
- [Minimally Sufficient Identity](#minimally-sufficient-identity)
1111
- [Repeatable Identity](#repeatable-identity)
12+
- [Identifying Attributes](#identifying-attributes)
1213
- [Examples of Entities](#examples-of-entities)
1314

1415
<!-- tocstop -->
@@ -117,6 +118,30 @@ describing the process.
117118
> identity from a central registry or knowledge store, OpenTelemetry must
118119
> support all possible scenarios.
119120
121+
## Identifying Attributes
122+
123+
OpenTelemetry Semantic Conventions MUST define a set of identifying attribute
124+
keys for every defined entity type.
125+
126+
Names of the identifying attributes SHOULD use the entity type as a prefix to avoid
127+
collisions with other entity types. For example, the `k8s.node` entity uses
128+
`k8s.node.uid` as an identifying attribute.
129+
130+
When an entity can be emitted by multiple observers, the following rules apply:
131+
132+
* Two independent observers that report the same entity MUST be able to
133+
supply identical values for all identifying attributes.
134+
135+
* If an observer cannot reliably obtain one or more identifying attributes, it
136+
MUST NOT emit telemetry using that entity type. Instead, it SHOULD:
137+
1. delegate to the observer that _can_ supply the full set and treat that
138+
observer as the _source of truth_, or
139+
2. emit a _different_ entity type with a set of identifying attributes it
140+
can populate reliably.
141+
142+
This ensures that entity identity is consistent and unambiguous across
143+
observers.
144+
120145
## Examples of Entities
121146

122147
_This section is non-normative and is present only for the purposes of

0 commit comments

Comments
 (0)