OpenTelemetry Entity Events 怎样表达资源关系变化

OpenTelemetry Entity Events 表达资源关系变化的关键，不是把关系拆成另一类“边事件”，而是由关系的源实体重新发送一条完整的 entity.state 事件，并在 entity.relationships 中携带当前出边。新增关系就加入描述符，关系消失就从数组中移除；实体整体消失时再使用 entity.delete。这样消费者只要按实体身份保存最新状态，就能重放事件恢复关系图。

官方资料：https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/entities/entity-events.md

官方总览：https://opentelemetry.io/docs/specs/otel/entities/

当前 Entity Events 规范状态仍是 Development。设计时可以采用它的事件语义，但应把字段扩展、关系枚举和消费者兼容策略留出余地。

先分清 Resource 和 Entity Events 的职责

Resource 适合描述一条指标、日志或链路来自哪些实体；Entity Events 则适合传递没有直接遥测信号的对象、复杂描述、实体之间的关系，以及独立于指标日志的创建、变更和删除生命周期。资源属性通常是简单值，而事件可以承载嵌套 map、数组和关系描述。

事件名是 Logs Data Model 的 EventName，主要有两个：

• entity.state：创建实体、描述属性变化，或按周期证明实体仍然存在。
• entity.delete：表达实体已经删除；但消费者不能假设这条事件一定送达。

entity.type 和 entity.id 是身份，生命周期内不能改变；entity.description 是可变的完整描述。身份里只放最小且稳定的键，例如进程通常需要 PID 和创建时间，而不是把可变的命令行塞进身份。

关系描述符要同时表达类型、方向和目标身份

关系数组中的每一项至少需要关系类型、目标实体类型和目标实体身份。方向始终是“发送这条状态事件的源实体 ——关系类型——> 被引用的目标实体”，所以同一条关系不应在消费者侧凭名称猜方向。

下面是规范中的逻辑结构示意，不是 OTLP 的实际线格式。示例用 YAML 便于展示嵌套字段：

# 这是 entity.state 的逻辑结构示意，不是可直接发送的 OTLP 报文
EventName: entity.state
Attributes:
  entity.type: service.instance
  entity.id:
    service.name: payment-service
    service.namespace: prod
    service.instance.id: payment-prod-a
  entity.description:
    service.version: "2.3.1"
  # 关系由 service.instance 作为源实体发出
  entity.relationships:
    - relationship.type: runs_on
      entity.type: process
      entity.id:
        process.pid: "4821"
        process.start_time: "1736928900"
    - relationship.type: part_of
      entity.type: service
      entity.id:
        service.name: payment-service
        service.namespace: prod

这里的两条关系分别表示实例运行在进程上、实例属于逻辑服务。目标的身份键要遵循对应实体定义；它不是一段展示名称，也不是可随时改写的标签。

关系变化用完整状态快照处理

Entity State 事件包含实体描述的完整当前值，而不是只发送一个 patch。关系的生命周期因此很直接：

• 新增关系：发送新的 entity.state，把关系描述符加入数组。
• 修改关系：发送新的 entity.state，用当前数组替换旧数组。
• 删除关系：发送新的 entity.state，移除该描述符；缺少 entity.relationships 应按空数组理解。
• 删除实体：发送 entity.delete；后端还应把涉及该实体的关系视为隐式删除。

不要把“没收到删除事件”直接当成网络故障。生产消费者应结合 entity.report.interval 设置过期时间：周期状态事件停止且超过合理宽限后，把实体标为过期。删除事件乱序到达时，也要继续接受后来的完整状态，因为状态事件本身可以重建已删除记录。

关系放在哪个实体上更省事件

关系嵌在状态事件里，所以关系放置位置会直接影响发送量。规范建议优先让生命周期更短、变化更频繁的实体拥有关系。比如让 process 表达 runs_on -> host，比让长寿命的 host 维护全部进程列表更省更新；让容器表达 part_of -> k8s.pod，也比 Pod 不断重发容器清单更适合高 churn 场景。

关系类型是开放枚举，标准类型应由语义约定定义，领域系统可以增加自定义类型。但消费者不要把未知关系当成解析失败：先保存关系类型和目标身份，展示层再决定是否理解它。

兼容策略可以归纳为三点：

1. 身份键只增补新实体类型，不在同一实体生命周期内改写 entity.id。
2. 对缺失的可选关系和描述使用空集合，不把它们当成 malformed event。
3. 保留事件时间、接收时间和来源信息，避免用不同生产者的时钟强行排出全局顺序。

消费者侧的最小落地模型

无论后端使用关系数据库、图数据库还是内存投影，最小处理逻辑都可以保持一致：按 entity.type + entity.id 找到实体，覆盖描述和关系出边；收到删除就标记删除；周期任务负责处理心跳超时。

// 伪代码：展示消费者的状态覆盖规则，不代表某个 SDK 的现成 API
func applyEntityState(event Event) {
    // 身份只用于定位，不能用 description 中的字段替换它
    key := identityKey(event.Type, event.ID)

    // state 是完整快照，直接覆盖描述和出边，避免残留旧关系
    graph.UpsertEntity(key, event.Description)
    graph.ReplaceOutgoingRelations(key, event.Relationships)

    // 正数 interval 用于设置下一次心跳的预期时间
    graph.SetExpiry(key, event.ReportInterval)
}

func applyEntityDelete(event Event) {
    // 删除事件可能迟到，但删除关系由投影层统一处理
    graph.MarkDeleted(identityKey(event.Type, event.ID))
}

这段伪代码最重要的不是函数名，而是“覆盖完整快照”和“身份不可漂移”两个决定。先把出边替换掉，才能正确表达关系删除；把心跳作为生命周期信号，才能在删除事件丢失时收敛到合理状态。

常见问题

关系变化要单独发送 relationship 事件吗？

按当前规范，不需要。关系属于源实体的 entity.relationships，通过新的 entity.state 发送完整当前关系集合。

entity.delete 到达后还能接受 entity.state 吗？

可以。消费者应允许乱序，并把后来的完整状态当作可恢复的 upsert，而不是永久拒绝这个实体。

为什么不把所有关系都放在长寿命实体上？

因为短寿命对象的创建和销毁会迫使长寿命实体频繁重发完整状态，通常会增加事件量；让高 churn 实体携带出边更容易控制成本。

如果你的系统只需要给一条遥测信号附加来源，Resource 仍是更简单的选择；当你需要关系、复杂描述或独立生命周期时，再引入 Entity Events，并把 Development 状态下的演进风险纳入消费者设计。