SkyWalking 的高级可观测性功能 —— Event（事件上报）。

在分布式系统中，除了“链路、指标、日志”三支柱外，业务或系统事件（如发布、配置变更、告警、审批）也是重要的上下文信息。SkyWalking 的 Event 功能允许你将这些离散的事件“标记”在时间轴上，与其他观测数据（如 Trace、Metrics）联动分析，极大提升问题排查和运营分析的效率。

---

📅 SkyWalking 高级特性：Event（事件上报）功能详解

✅ 目标：
理解 Event 的作用、如何上报事件、如何在 UI 中查看并用于根因分析。

---

一、什么是 Event（事件）？

Event（事件） 是 SkyWalking 提供的一种离散、有意义的时间点记录，用于标记系统中发生的重要动作或状态变更。

✅ 类比：就像 Git 的 commit，你在时间轴上打一个“标记”，告诉监控系统：“此时发生了某件事”。

---

二、为什么需要 Event？

问题	Event 如何帮助
❓ 发布后接口变慢了？	上报“发布事件” → 在 UI 时间轴上看到“发布”与“P99 上升”重合
❓ 配置变更导致错误率升高？	标记“配置更新”事件 → 关联分析异常起始时间
❓ 运维操作引发故障？	记录“重启服务”事件 → 排查是否与超时有关
❓ 业务审批流程卡住？	上报“审批通过”事件 → 结合 Trace 查看后续处理耗时

✅ 核心价值：

将“操作”与“现象”关联起来，实现“因果分析”。

---

三、Event 的核心属性

一个 Event 包含以下关键字段：

字段	说明
source	事件来源：服务名、实例、端点
name	事件名称（如 Deployment、Config Update）
type	事件类型：MANUAL / AUTOMATIC
time	事件发生时间（毫秒级）
tags	事件标签（KV 结构，用于携带上下文）
message	事件详情（可选，支持多行文本）

---

四、如何上报 Event？

SkyWalking 提供多种方式上报事件，以下是三种主要方式：

方式 1️⃣：通过 OAP 的 gRPC API 上报（推荐）

使用 SkyWalking 的 Event Service API 手动发送事件。

示例（Java + gRPC）

// 1. 创建 Event 请求
EventRequest event = EventRequest.newBuilder()
    .setSource(Service.newBuilder().setName("order-service").build())
    .setName("Deployment")
    .setType(EventType.MANUAL)
    .setTime(System.currentTimeMillis())
    .addTags(KeyStringValuePair.newBuilder().setKey("version").setValue("v1.2.0").build())
    .addTags(KeyStringValuePair.newBuilder().setKey("operator").setValue("zhangsan").build())
    .setMessage("发布新版本，修复支付超时问题")
    .build();

// 2. 发送到 OAP
eventServiceBlockingStub.send(event);

🔧 需要引入 skywalking-client-java 或直接调用 gRPC。

---

方式 2️⃣：通过 HTTP API 上报（简单，适合脚本）

SkyWalking OAP 提供 RESTful 接口：

POST http://oap-server:12800/oap/receive/event
Content-Type: application/json

{
  "source": {
    "serviceName": "order-service"
  },
  "name": "Config Updated",
  "type": "MANUAL",
  "time": 1712345678000,
  "tags": [
    { "key": "key", "value": "payment.timeout" },
    { "key": "oldValue", "value": "3000" },
    { "key": "newValue", "value": "5000" }
  ],
  "message": "调整支付超时时间"
}

✅ 适合 CI/CD 脚本、运维工具调用。

---

方式 3️⃣：通过 Agent 插件 上报（自动）

你可以开发自定义 Agent 插件，在特定方法执行时自动上报事件。

示例场景：

• 某个 @Transactional 方法执行失败 → 上报 TransactionFailed 事件
• @Scheduled 定时任务开始/结束 → 上报 JobStarted / JobCompleted

🔧 需要熟悉 SkyWalking Agent 插件开发。

---

五、在 SkyWalking UI 中查看 Event

1. Event 页面

• 路径：UI → 左侧菜单 → “Event”
• 可按服务、时间、事件名过滤
• 查看事件列表、标签、消息

2. 与 Trace 联动

• 在 Trace 详情页，Event 会以“标记”形式显示在时间轴上
• 一眼看出“发布”是否与“慢请求”重合

3. 与 Dashboard 联动

• 在 指标图表下方，显示该时间段内的 Events
• 例如：P99 曲线突增 → 下方显示“Deployment v1.2.0”

P99 响应时间
  ^
  |           ●
  |         ●   ●
  |       ●       ●
  |     ●           ●
  |   ●               ●
  +----------------------->
  10:00      10:15      10:30

  [Event] Deployment v1.2.0 ──┘

---

六、实战场景示例

场景：发布后错误率升高

1. CI/CD 系统在发布完成后调用 SkyWalking Event API：

   {
     "source": { "serviceName": "user-service" },
     "name": "Deployment",
     "time": 1712345678000,
     "tags": { "version": "v2.1.0", "gitSha": "abc123" },
     "message": "发布新版本"
   }
   

2. 运维在 UI 中发现：

   • 错误率从 0.1% 升至 5%
   • 时间轴上“发布事件”与“错误率上升”完全重合

3. 结论：新版本引入 bug → 回滚或热修复

---

七、Event 与 Logging 的区别

维度	Event	Logging
结构	结构化（固定字段 + Tags）	半结构化（文本 + MDC）
用途	标记重要状态变更	记录执行过程
查询	支持按 name、tags 精确查询	支持全文检索
展示	时间轴标记、联动图表	按 traceId 关联
典型场景	发布、配置变更、审批	方法调用、异常堆栈

✅ 最佳实践：

Event 用于“标记”，Logging 用于“记录”，两者互补。

---

八、生产环境建议

项目	建议
🎯 事件命名	语义化，如 Deployment、ConfigUpdate、DataMigration
🏷️ 标签设计	携带关键上下文：version、operator、env
⏱️ 时间精度	使用毫秒时间戳，确保时序准确
🔐 安全	HTTP API 应启用认证（如 Token）
📅 保留策略	事件默认保留与指标相同（TTL 配置）

---

✅ 总结：Event 使用口诀

“一定义事件，二上报时间，三打标签，四看联动”

Event 是你的 “系统记事本”，让你在回顾问题时，不仅能“看到现象”，还能“知道发生了什么”。