Skip to content

Commit d95a822

Browse files
committed
[entities] Update terminology for entity attributes
Update terminology in specification/entities/data-model.md. Replace "Identifying Attributes" with "Entity Identity" and "Descriptive Attributes" with "Description Attributes". Related to #4700
1 parent 7f6d35f commit d95a822

File tree

1 file changed

+22
-22
lines changed

1 file changed

+22
-22
lines changed

specification/entities/data-model.md

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,10 @@ weight: 2
1414

1515
- [Minimally Sufficient Identity](#minimally-sufficient-identity)
1616
- [Repeatable Identity](#repeatable-identity)
17-
- [Identifying Attributes](#identifying-attributes)
17+
- [Attributes of Entity Identity](#attributes-of-entity-identity)
1818
- [Resource and Entities](#resource-and-entities)
1919
* [Attribute Referencing Model](#attribute-referencing-model)
20-
* [Placement of Shared Descriptive Attributes](#placement-of-shared-descriptive-attributes)
20+
* [Placement of Shared Attributes of Entity Description](#placement-of-shared-attributes-of-entity-description)
2121
- [Examples of Entities](#examples-of-entities)
2222

2323
<!-- tocstop -->
@@ -48,8 +48,8 @@ physical format and encoding of how entity data is recorded).
4848
| Field | Type | Description |
4949
|--------------|----------------------------------------|-----------------|
5050
| Type | string | Defines the type of the entity. MUST not change during the lifetime of the entity. For example: "service" or "host". This field is required and MUST not be empty for valid entities. |
51-
| Id | map<string, attribute value> | Attributes that identify the entity.<p>MUST not change during the lifetime of the entity. The Id must contain at least one attribute.<p>Follows OpenTelemetry [attribute definition](../common/README.md#attribute). SHOULD follow OpenTelemetry [semantic conventions](https://github.com/open-telemetry/semantic-conventions) for attributes. |
52-
| Description | map<string, attribute value> | Descriptive (non-identifying) attributes of the entity.<p>MAY change over the lifetime of the entity. MAY be empty. These attributes are not part of entity's identity.<p>Follows OpenTelemetry [attribute definition](../common/README.md#attribute). SHOULD follow OpenTelemetry [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md) for attributes. |
51+
| Id | map<string, attribute value> | Attributes of entity identity.<p>MUST not change during the lifetime of the entity. The Id must contain at least one attribute.<p>Follows OpenTelemetry [Standard attribute definition](../common/README.md#standard-attribute). SHOULD follow OpenTelemetry [semantic conventions](https://github.com/open-telemetry/semantic-conventions) for attributes. |
52+
| Description | map<string, attribute value> | Attributes of entity description.<p>MAY change over the lifetime of the entity. MAY be empty. These attributes are not part of entity's identity.<p>Follows [any](../logs/data-model.md#type-any) value definition in the OpenTelemetry spec. Arbitrary deep nesting of values for arrays and maps is allowed.<p>SHOULD follow OpenTelemetry [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md) for attributes. |
5353

5454
## Minimally Sufficient Identity
5555

@@ -62,37 +62,37 @@ Minimally Sufficient Identity rule.
6262

6363
## Repeatable Identity
6464

65-
The identifying attributes for entity SHOULD be values that can be repeatably
65+
The attributes of entity identity SHOULD be values that can be repeatably
6666
obtained by observers of that entity. For example, a `process` entity SHOULD
6767
have the same identity (and be recognized as the same process), regardless of whether
6868
the identity was generated from the process itself, e.g. via SDK, or by an
6969
OpenTelemetry Collector running on the same host, or by some other system
7070
describing the process.
7171

72-
> Aside: There are many ways to accomplish repeatable identifying attributes
72+
> Aside: There are many ways to accomplish repeatable attributes of entity identity
7373
> across multiple observers. While many successful systems rely on pushing down
7474
> identity from a central registry or knowledge store, OpenTelemetry must
7575
> support all possible scenarios.
7676
77-
## Identifying Attributes
77+
## Attributes of Entity Identity
7878

79-
OpenTelemetry Semantic Conventions MUST define a set of identifying attribute
79+
OpenTelemetry Semantic Conventions MUST define a set of identity attribute
8080
keys for every defined entity type.
8181

82-
Names of the identifying attributes SHOULD use the entity type as a prefix to avoid
82+
Names of the identity attributes SHOULD use the entity type as a prefix to avoid
8383
collisions with other entity types. For example, the `k8s.node` entity uses
84-
`k8s.node.uid` as an identifying attribute.
84+
`k8s.node.uid` as an identity attribute.
8585

8686
When an entity can be emitted by multiple observers, the following rules apply:
8787

8888
* Two independent observers that report the same entity MUST be able to
89-
supply identical values for all identifying attributes.
89+
supply identical values for all identity attributes.
9090

91-
* If an observer cannot reliably obtain one or more identifying attributes, it
91+
* If an observer cannot reliably obtain one or more identity attributes, it
9292
MUST NOT emit telemetry using that entity type. Instead, it SHOULD:
9393
1. delegate to the observer that _can_ supply the full set and treat that
9494
observer as the _source of truth_, or
95-
2. emit a _different_ entity type with a set of identifying attributes it
95+
2. emit a _different_ entity type with a set of identity attributes it
9696
can populate reliably.
9797

9898
This ensures that entity identity is consistent and unambiguous across
@@ -113,8 +113,8 @@ compatibility with existing Resource attributes.
113113

114114
### Attribute Referencing Model
115115

116-
Entities can be defined in the `resource` section of a telemetry signal. Their
117-
identifying and descriptive attributes reference shared attributes defined in
116+
Entities can be defined in the `resource` section of a telemetry signal. Attributes
117+
of their identity and description reference shared attributes defined in
118118
the Resource. For example, in OTLP, entities do not carry their own key-value
119119
pairs directly. Instead, they reference keys in `resource.attributes` to remain
120120
backward compatible with OTLP 1.x.
@@ -127,13 +127,13 @@ entities. The model provides:
127127
- The ability to avoid data duplication and inconsistencies.
128128
- A more efficient representation for encoding and transmission.
129129

130-
### Placement of Shared Descriptive Attributes
130+
### Placement of Shared Attributes of Entity Description
131131

132132
Attribute flattening allows multiple entities to reference the same attribute key,
133133
but with different values across the entities. In such situations, the following
134134
rule applies:
135135

136-
If multiple entities share the same descriptive attribute key with potentially
136+
If multiple entities share the same description attribute key with potentially
137137
conflicting values, the attribute MUST logically belong to **only one** of them.
138138
All others SHOULD NOT reference it. The attribute MUST be referenced by the
139139
**most specific** entity, the one closest in the topology graph to the entity
@@ -142,7 +142,7 @@ associated with the telemetry signal.
142142
**Example:**
143143

144144
If a signal includes both `k8s.cluster` and `k8s.node` entities with
145-
the `cloud.availability_zone` descriptive attribute, which may have
145+
the `cloud.availability_zone` description attribute, which may have
146146
different values, then **only** the `k8s.node` entity can reference this key
147147
— as it is the more specific entity.
148148

@@ -154,8 +154,8 @@ telemetry channel (e.g., entity events) where full ownership context is known.
154154
_This section is non-normative and is present only for the purposes of
155155
demonstrating the data model._
156156

157-
Here are examples of entities, the typical identifying attributes they
158-
have and some examples of descriptive attributes that may be
157+
Here are examples of entities, the typical identity attributes they
158+
have and some examples of description attributes that may be
159159
associated with the entity.
160160

161161
_Note: These examples MAY diverge from semantic conventions._
@@ -166,9 +166,9 @@ _Note: These examples MAY diverge from semantic conventions._
166166
</td>
167167
<td><strong>Entity Type</strong>
168168
</td>
169-
<td><strong>Identifying Attributes</strong>
169+
<td><strong>Identity Attributes</strong>
170170
</td>
171-
<td><strong>Descriptive Attributes</strong>
171+
<td><strong>Description Attributes</strong>
172172
</td>
173173
</tr>
174174
<tr>

0 commit comments

Comments
 (0)