You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -65,9 +64,7 @@ additional context and relationship information.
65
64
Entity information is communicated through the following event types:
66
65
67
66
1.**Entity State Event** (`entity.state`): Emitted when an entity is created, when its
68
-
attributes change, or periodically to indicate the entity still exists. The presence or
69
-
absence of the `entity.updated` attribute distinguishes between state changes and
70
-
periodic reports.
67
+
attributes change, or periodically to indicate the entity still exists.
71
68
72
69
2.**Entity Delete Event** (`entity.delete`): Emitted when an entity is removed.
73
70
@@ -86,33 +83,17 @@ change, or periodically to indicate the entity still exists.
86
83
|`entity.id`| map<string, string> | Attributes that identify the entity. MUST not change during the lifetime of the entity. The map MUST contain at least one attribute. Keys and values MUST be strings. SHOULD follow OpenTelemetry [semantic conventions](https://github.com/open-telemetry/semantic-conventions) for attribute names. |
87
84
|`entity.description`| map<string, AnyValue> | Descriptive (non-identifying) attributes of the entity. These attributes are not part of the entity's identity. Each Entity State event contains the complete current state of the entity's description. Follows [AnyValue](../common/README.md#anyvalue) definition: can contain scalar values, arrays, or nested maps. SHOULD follow OpenTelemetry [semantic conventions](https://github.com/open-telemetry/semantic-conventions) for attributes. |
88
85
|`entity.relationships`| array of maps | Relationships to other entities. Each relationship is a map containing: `type` (string, describes the relationship), `entity.type` (string, the type of the related entity), and `entity.id` (map<string, string>, identifying attributes of the related entity). |
89
-
|`report.interval`| int64 (milliseconds) | The reporting interval for this entity. MUST be a non-negative value. A value of `0` indicates that periodic reporting is disabled and only state changes will be reported. A positive value indicates the interval at which periodic state events (without `entity.updated`) will be emitted. Can be used by receivers to infer that a no longer reported entity is gone, even if the Entity Delete event was not observed. |
90
-
91
-
**Optional Attributes**:
92
-
93
-
| Attribute | Type | Description |
94
-
| --------- | ---- | ----------- |
95
-
|`entity.updated`| string | The timestamp when the entity's state last changed, in ISO 8601 format. When present, indicates this is a state change event. When absent, indicates this is a periodic report with no changes since the last report. When multiple changes occur between reports (aggregated reporting), this represents the timestamp of the most recent change. |
86
+
|`report.interval`| int64 (milliseconds) | The reporting interval for this entity. MUST be a non-negative value. A value of `0` indicates that periodic reporting is disabled and only state changes will be reported. A positive value indicates the interval at which periodic state events will be emitted. Can be used by receivers to infer that a no longer reported entity is gone, even if the Entity Delete event was not observed. |
96
87
97
88
**Timestamp Field**:
98
89
99
90
The `Timestamp` field of the LogRecord represents the time when this event was generated and sent.
100
-
For immediate reporting without aggregation, this will typically match `entity.updated`. For
101
-
aggregated reporting, this represents when the event was sent, while `entity.updated` represents
102
-
when the most recent state change occurred.
103
91
104
-
**State Changes vs Periodic Reports**:
92
+
**Event Emission**:
105
93
106
-
- When `entity.updated` is **present**, this is a state change event indicating the entity
107
-
was created or its attributes were modified. The value of `entity.updated` indicates when
108
-
the most recent change occurred.
109
-
- When `entity.updated` is **absent**, this is a periodic report indicating the entity still
110
-
exists but has not changed since the last report.
111
-
112
-
Implementations SHOULD emit state change events whenever entity descriptive attributes change,
113
-
periodic state events based on the `report.interval` value, and delete events when entities
114
-
are removed. Implementations MAY provide configuration options to allow users to disable
115
-
state change events or periodic state events independently.
94
+
Implementations SHOULD emit Entity State events whenever entity descriptive attributes change,
95
+
and periodically based on the `report.interval` value to indicate the entity still exists.
96
+
Implementations SHOULD also emit Entity Delete events when entities are removed.
116
97
117
98
### Entity Delete Event
118
99
@@ -146,31 +127,6 @@ previously reported `report.interval` field. Recipients can use this value to co
146
127
to expect the next Entity State event and, if the event does not arrive in a timely manner
147
128
(plus some slack), consider the entity to be gone even if the Entity Delete event was not observed.
148
129
149
-
### Aggregated Reporting
150
-
151
-
Implementations MAY provide aggregated reporting as an optional capability to reduce the amount
152
-
of data sent over the wire. When aggregated reporting is enabled:
153
-
154
-
- Multiple rapid changes to the same entity are collapsed into a single Entity State event
155
-
- Only the **latest state** of the entity is reported
156
-
- Intermediate state changes are not preserved
157
-
- The `entity.updated` attribute contains the timestamp of the **most recent change** that
158
-
occurred during the aggregation period
159
-
- The LogRecord `Timestamp` represents when the aggregated event was sent
160
-
161
-
**Example**:
162
-
163
-
If a Pod's phase changes from "Pending" → "Running" → "Running" (with label update) between
164
-
reports, only one event is sent with:
165
-
166
-
- The final state (Running with updated labels)
167
-
-`entity.updated` = timestamp of the label update (the most recent change)
168
-
- LogRecord `Timestamp` = when the aggregated event was sent
169
-
170
-
Aggregated reporting reduces data volume at the cost of losing visibility into intermediate
171
-
states. When provided, implementations SHOULD document the aggregated reporting capability
172
-
and allow configuration of the aggregation behavior.
173
-
174
130
## Entity Relationships
175
131
176
132
Entity relationships describe how entities are connected to each other. Relationships are
@@ -294,7 +250,6 @@ LogRecord:
294
250
version: "1.21"
295
251
tier: frontend
296
252
k8s.pod.phase: Running
297
-
entity.updated: 2026-01-12T10:30:00.000000000Z
298
253
report.interval: 60000
299
254
entity.relationships:
300
255
- relationship.type: scheduled_on
@@ -330,30 +285,6 @@ LogRecord:
330
285
report.interval: 60000
331
286
```
332
287
333
-
### Aggregated Entity Update
334
-
335
-
When multiple changes are aggregated and sent in a single event:
0 commit comments