📚 课程目录第4章事件标准化模型

4. 事件标准化模型：定义统一事件Schema

事件触发引擎的核心是处理来自不同监控源、不同格式的原始告警。若缺乏统一的事件模型，引擎将陷入“适配器地狱”，每接入一个源就需要编写一套解析逻辑。因此，事件标准化模型（Event Schema）是引擎的“通用语言”，它定义了事件在引擎内部流转的数据结构。

4.1 统一事件Schema设计原则

通用性：Schema 必须能覆盖 Prometheus、Zabbix、CloudWatch、自研监控系统等主流监控源的告警特征。
可扩展性：核心字段固定，但允许通过扩展字段携带源系统的特有属性，避免频繁修改Schema。
不可变性：事件一旦生成，其 event_id 和 timestamp 不可变更，用于去重和时序追踪。
可路由性：通过 source、severity、resource 等字段，引擎能快速判断事件应匹配哪个剧本。

设计提示：不要试图用一个Schema穷举所有监控字段。坚持“核心必选 + 扩展可选”模式，保持Schema的轻量与稳定。

4.2 必选字段定义

以下五个字段是事件标准化模型的基石，任何进入引擎的事件都必须携带这些字段，否则将被视为无效事件并丢弃。

字段名	类型	说明	示例
`event_id`	String (UUID)	全局唯一事件标识，用于去重、追踪、关联。由引擎生成或源系统提供。	`evt-20250321-a1b2c3d4`
`source`	String	事件来源标识，如监控系统名称或集群ID。用于区分事件归属。	`prometheus/prod`、`zabbix/beijing`
`severity`	Enum	事件严重级别。建议使用 `critical`、`warning`、`info` 三级，便于剧本按级别过滤。	`critical`
`timestamp`	Integer (Unix秒)	事件发生时间戳（UTC）。用于时间窗口计算和事件排序。	`1742544000`
`resource`	String	事件影响的资源标识，通常是主机名、Pod名、服务名或IP。剧本据此定位目标。	`web-server-01`、`10.0.1.5`

  必选字段校验规则：事件接入层必须对以上五个字段进行非空校验。若 event_id 重复，引擎应执行幂等处理（丢弃或覆盖，取决于配置）；若 severity 不在枚举范围内，应默认降级为 info 并记录告警。

4.3 扩展字段设计

扩展字段用于承载源系统的个性化信息，避免因字段不足而丢失上下文。扩展字段采用 Key-Value 结构，引擎不对其做强校验，但剧本可通过条件表达式引用这些字段。

字段名	类型	说明	示例
`ext_fields`	Map<String, Object>	扩展字段容器，存储源系统原始告警中的非标准属性。	`{"metric": "cpu_usage", "value": 95.2, "threshold": 90}`
`title`	String	事件标题，用于告警通知展示。若源系统未提供，引擎自动拼接。	`CPU使用率超过阈值`
`message`	String	事件详细描述，包含触发原因、当前值、建议操作等。	`当前CPU使用率95.2%，阈值90%`
`region`	String	资源所属区域或可用区，用于多区域部署时的路由。	`us-east-1`
`tags`	List<String>	标签列表，用于事件分类、分组和剧本匹配。	`["production", "web-tier", "high-traffic"]`

4.4 事件标准化流程（内联SVG）

下图展示了从原始告警到标准化事件的转换流程，以及必选字段与扩展字段在引擎内部的流转关系。

4.5 事件Schema JSON示例

以下是一个完整的标准化事件示例，展示了必选字段与扩展字段在实际场景中的组合方式。

{
  "event_id": "evt-20250321-a1b2c3d4",
  "source": "prometheus/prod",
  "severity": "critical",
  "timestamp": 1742544000,
  "resource": "web-server-01",
  "ext_fields": {
    "metric": "cpu_usage",
    "value": 95.2,
    "threshold": 90,
    "duration_seconds": 120
  },
  "title": "CPU使用率超过阈值",
  "message": "web-server-01 当前CPU使用率95.2%，已持续120秒，阈值90%",
  "region": "us-east-1",
  "tags": ["production", "web-tier", "high-traffic"]
}

注意事项：ext_fields 中的字段名应避免与必选字段重名。若源系统告警中已包含 severity 字段，标准化引擎应优先使用必选字段的映射逻辑，而非直接透传，以确保级别枚举的统一性。

4.6 字段映射与兼容性策略

不同监控源的字段命名差异较大，标准化引擎需提供灵活的字段映射配置。下表列出常见源系统的字段映射关系。

标准化字段	Prometheus Alertmanager	Zabbix	AWS CloudWatch
`event_id`	`alert.fingerprint`	`eventid`	`AlarmName + Timestamp (MD5)`
`source`	固定值 `prometheus`	`host` 或固定值 `zabbix`	`Namespace`
`severity`	`alert.labels.severity`	`trigger.priority` (1-5)	`AlarmDescription` 中解析
`resource`	`alert.labels.instance`	`trigger.host`	`Dimensions[InstanceId]`
`timestamp`	`alert.startsAt`	`clock`	`StateChangeTime`

通过统一的Schema和灵活的字段映射，Event Trigger事件触发引擎能够屏蔽底层监控源的差异，让剧本编写者只关注“事件是什么”和“如何处理”，而不必关心“事件从哪里来”。