Skip to content

Commit 807298a

Browse files
committed
Remove aggregated events and update/state distinction
1 parent 8806da9 commit 807298a

File tree

1 file changed

+6
-75
lines changed

1 file changed

+6
-75
lines changed

specification/entities/entity-events.md

Lines changed: 6 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,6 @@ weight: 3
1717
- [Event Types](#event-types)
1818
* [Entity State Event](#entity-state-event)
1919
* [Entity Delete Event](#entity-delete-event)
20-
* [Aggregated Reporting](#aggregated-reporting)
2120
- [Entity Relationships](#entity-relationships)
2221
* [Relationship Structure](#relationship-structure)
2322
* [Standard Relationship Types](#standard-relationship-types)
@@ -65,9 +64,7 @@ additional context and relationship information.
6564
Entity information is communicated through the following event types:
6665

6766
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.
7168

7269
2. **Entity Delete Event** (`entity.delete`): Emitted when an entity is removed.
7370

@@ -86,33 +83,17 @@ change, or periodically to indicate the entity still exists.
8683
| `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. |
8784
| `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. |
8885
| `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. |
9687

9788
**Timestamp Field**:
9889

9990
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.
10391

104-
**State Changes vs Periodic Reports**:
92+
**Event Emission**:
10593

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.
11697

11798
### Entity Delete Event
11899

@@ -146,31 +127,6 @@ previously reported `report.interval` field. Recipients can use this value to co
146127
to expect the next Entity State event and, if the event does not arrive in a timely manner
147128
(plus some slack), consider the entity to be gone even if the Entity Delete event was not observed.
148129

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-
174130
## Entity Relationships
175131

176132
Entity relationships describe how entities are connected to each other. Relationships are
@@ -294,7 +250,6 @@ LogRecord:
294250
version: "1.21"
295251
tier: frontend
296252
k8s.pod.phase: Running
297-
entity.updated: 2026-01-12T10:30:00.000000000Z
298253
report.interval: 60000
299254
entity.relationships:
300255
- relationship.type: scheduled_on
@@ -330,30 +285,6 @@ LogRecord:
330285
report.interval: 60000
331286
```
332287

333-
### Aggregated Entity Update
334-
335-
When multiple changes are aggregated and sent in a single event:
336-
337-
```
338-
LogRecord:
339-
Timestamp: 2026-01-12T10:31:00.000000000Z
340-
EventName: entity.state
341-
Resource:
342-
k8s.cluster.name: prod-cluster
343-
Attributes:
344-
entity.type: k8s.pod
345-
entity.id:
346-
k8s.pod.uid: abc-123-def-456
347-
entity.description:
348-
k8s.pod.name: nginx-deployment-66b6c
349-
k8s.pod.labels:
350-
app: nginx
351-
version: "1.21"
352-
k8s.pod.phase: Running
353-
entity.updated: 2026-01-12T10:30:45.000000000Z
354-
report.interval: 60000
355-
```
356-
357288
### Entity Delete
358289

359290
When the Pod is terminated:

0 commit comments

Comments
 (0)