实体生成与写入

系统字段

字段说明

自定义字段

除系统字段外，可以添加 EntitySet 中定义的各类 Field 字段：

{
  "__domain__": "apm",
  "__entity_type__": "apm.service",
  "__entity_id__": "391274C9A1D369FB5222E273D02B81B8",
  "__method__": "Update",
  "__last_observed_time__": 1700000001,
  "__keep_alive_seconds__": 3600,
  "service_name": "user-service",
  "version": "v1.2.3",
  "cluster": "production",
  "labels": {
    "env": "prod",
    "team": "backend"
  }
}

时间区间基础概念

实体在 EntityStore 中具有明确的时间可见范围，查询引擎只有在查询时间窗口与实体可见时间产生交集时，才会返回该实体。

时间交集判断规则

查询引擎使用以下规则判断实体是否应该被返回：

查询返回实体 = 查询时间窗口 ∩ 实体可见时间

具体判断逻辑：

if (QueryEndTime >= EntityFirstObservedTime && 
    QueryStartTime <= EntityVisibleEndTime) {
    返回实体
} else {
    不返回实体
}

Create - 创建实体

使用场景：明确创建新实体时使用，如监听到Pod创建事件。

行为逻辑：

• 若实体已存在：不做任何操作。

• 若实体不存在：创建新实体，覆盖所有字段。

示例：

{
  "__domain__": "k8s",
  "__entity_type__": "k8s.pod",
  "__entity_id__": "abc123...",
  "__method__": "Create",
  "__first_observed_time__": 1700000000,
  "__last_observed_time__": 1700000000,
  "pod_name": "web-app-123",
  "namespace": "default"
}

Update - 更新实体

使用场景：大部分场景使用，包括定期全量更新、增量更新等。

行为逻辑：

• 覆盖除__first_observed_time__外的所有字段。

• 对于__first_observed_time__：

  • 若实体已存在：不修改原值。

  • 若实体不存在且事件包含该字段：使用事件中的值。

  • 若实体不存在且事件不包含该字段：使用__last_observed_time__的值。

示例：

{
  "__domain__": "apm",
  "__entity_type__": "apm.service",
  "__entity_id__": "def456...",
  "__method__": "Update",
  "__last_observed_time__": 1700000100,
  "service_name": "payment-service",
  "status": "running",
  "instance_count": 3
}

Expire - 实体过期

使用场景：实体明确被删除时使用，如监听到Pod删除事件。

行为逻辑：

• 标记实体的__deleted__为true。

• 更新__last_observed_time__。

• 查询时不再附加计算KeepAlive时间。

时间范围变化：

• 过期前：[FirstObservedTime, LastObservedTime + KeepAliveSeconds]。

• 过期后：[FirstObservedTime, LastObservedTime]。

示例：

{
  "__domain__": "k8s",
  "__entity_type__": "k8s.pod",
  "__entity_id__": "abc123...",
  "__method__": "Expire",
  "__last_observed_time__": 1700000200
}

Delete - 删除实体（谨慎使用）

使用场景：功能被禁用或需要实体在全周期都不可见的场景。

行为逻辑：

• 直接从底层数据库删除实体记录。

• 任何时间段的查询都无法找到该实体。

⚠️ 注意：这是不可逆操作，请谨慎使用。

Revise - 订正实体（谨慎使用）

使用场景：数据写错需要强制订正时使用，通常与Delete组合使用。

行为逻辑：

• 直接覆盖所有字段，包括__first_observed_time__。

• 不考虑原有数据状。

推荐方式：增量事件 + 定期全量

核心思路是以增量事件为主，定期全量写入作为数据校对和容错机制。

配置建议：

• 增量事件：实时或近实时写入。

• 定期全量：频率建议1小时及以上。

• KeepAlive时间：根据业务需求设置，通常10分钟到1小时。

• 说明：KeepAlive时间根据上报周期进行调整，建议不低于1个上报周期。此外定期上报周期建议不低于5分钟，避免频繁更新影响查询性能。

实际场景应用

// 云资源创建事件
{
  "__domain__": "acs",
  "__entity_type__": "acs.ecs.instance",
  "__entity_id__": "i-bp1234567890",
  "__method__": "Create",
  "__first_observed_time__": 1700000000,
  "__last_observed_time__": 1700000000,
  "__keep_alive_seconds__": 86400,
  "instance_id": "i-bp1234567890",
  "instance_name": "web-server-01",
  "instance_type": "ecs.c6.large",
  "status": "Running"
}

// K8s Pod全量采集
{
  "__domain__": "k8s",
  "__entity_type__": "k8s.pod",
  "__entity_id__": "pod-web-app-123",
  "__method__": "Update",
  "__last_observed_time__": 1700000400,
  "__keep_alive_seconds__": 3600,
  "pod_name": "web-app-123",
  "namespace": "production",
  "node_name": "worker-01",
  "pod_ip": "10.0.1.100",
  "labels": {
    "app": "web-app",
    "version": "v1.0"
  }
}

不推荐的写入方式