Apache SkyWalking 事件Event体系详解定义、上报协议与关联可视化【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址: https://gitcode.com/gh_mirrors/sk/skywalkingApache SkyWalking 在可观测性三大支柱日志、指标、链路追踪之外提供了一套原生的事件Event采集与呈现能力用于记录升级、重启、混沌演练等不一定反映在日志中的系统事件。本文将基于 event.md 与 OAP 后端源码完整讲解事件模型字段、gRPC / HTTP / Kafka 三种上报方式、事件与指标的关联可视化逻辑以及Start、Shutdown、Kubernetes 相关事件的来源帮助读者掌握从事件上报到查询展示的完整链路。为什么 SkyWalking 需要独立的事件体系SkyWalking 已经覆盖了可观测性的三大支柱日志Logs、指标Metrics和链路追踪Traces。但在真实的生产系统中还存在大量可能影响系统性能的事件例如服务升级Upgrade主机或实例重启Reboot混沌工程演练Chaos TestingPod 被杀掉、镜像拉取、探针失败等 Kubernetes 编排动作虽然其中一部分事件会以日志的形式留存但更多事件并不会出现在日志里。为此SkyWalking 提供了一种更原生的方式采集这些事件让运维人员能够把系统发生了什么与系统当时的性能表现如何放在同一时间轴上观察。这也是本仓库 docs/en/concepts-and-designs/event.md 所阐述的核心动机。如何上报事件三种采集协议SkyWalking 后端支持三种协议采集事件gRPC、HTTP 和 Kafka。任何实现了其中一种协议的 Agent 或 CLI 工具都可以向 SkyWalking 上报事件。官方支持的上报客户端客户端状态说明Java Agent Toolkit开发中在应用内通过 Java Agent Toolkit 上报事件SkyWalking CLI✅ 已支持通过命令行界面上报事件Kubernetes Event Exporter✅ 已支持部署事件导出器清洗并上报 Kubernetes 事件其中 Kubernetes Event Exporter 对应仓库为apache/skywalking-kubernetes-event-exporter部署后可将 Kubernetes 集群中产生的编排事件Killing、Pulling、Unhealthy 等持续上报给 SkyWalking。gRPC 上报gRPC 路径由 EventGrpcServiceHandler 实现它继承自协议定义的EventServiceGrpc.EventServiceImplBase提供流式接口collect(stream Event) returns (Commands)。上报方通过一次双向流连续推送Event消息后端在每个onNext回调中完成校验并交给事件分析器处理。该处理器内部还会创建两类遥测指标见同文件构造器event_in_latency事件数据的处理时延按协议维度打标签protocolgrpcevent_error_count事件分析失败次数。同时处理器对事件做了一处重要校验自 v9.0.0 起layer字段为必填若事件缺少layer或layer无法被Layer.nameOf识别会直接以INVALID_ARGUMENT状态拒绝该事件错误信息为 Layer field is required since v9.0.0, please upgrade your event report tools。因此使用旧版工具上报事件时需要升级到支持layer字段的版本。HTTP 上报HTTP 路径由 EventRestServiceHandler 实现注册于共享 HTTP 服务端口 12800接口为POST /v3/events。请求体为 JSON 数组一次可批量上报多个事件。与 gRPC 相同该处理器也创建event_in_latency、event_error_countprotocolhttp指标并校验每个事件的layer字段。一个完整的 JSON 事件记录示例来源docs/en/api/event.md[ { uuid: f498b3c0-8bca-438d-a5b0-3701826ae21c, source: { service: SERVICE-A, instance: INSTANCE-1 }, name: Reboot, type: Normal, message: App reboot., parameters: {}, startTime: 1628044330000, endTime: 1628044331000 } ]Kafka 上报除 gRPC 与 HTTP 外事件同样可以通过 Kafka 消息通道采集。上报方将序列化后的Event消息投递到 Kafka由 OAP 的 Kafka Fetcher 消费后进入事件分析链路。具体接入配置可参考 kafka-fetcher.md。接收器如何注册gRPC 与 HTTP 两个处理器都由 EventModuleProvider 在模块启动阶段注册到共享服务Sharing Server上其依赖模块包括CoreModule、EventAnalyzerModule与SharingServerModule。这意味着只要 OAP 启动时加载了skywalking-event-receiver-plugin事件接收能力便默认可用无需额外开关。事件字段定义事件由以下字段构成完整 protobuf 定义可参考协议仓库中的event目录本仓库 docs/en/api/event.md 也给出了完整协议文本。下表汇总各字段的语义与约束字段类型必填说明uuidstring✅事件唯一 ID用于关联同一事件的开始与结束sourceSource✅事件发生的对象service / serviceInstance / endpointnamestring✅事件名称如Start、Stop、Crash、Reboot、Upgradetypeenum✅事件类型Normal正常或Error异常如 Crashmessagestring建议事件详情一行文字简要说明事件原因parametersmapstring,string可选message中的参数键值对形式startTimeint64毫秒✅事件开始时间事件发生时必填endTimeint64毫秒条件必填事件结束时间未结束时可为空layerstring✅v9.0.0事件所属的层名称LayerSource 对象约束Source描述事件作用的对象其字段组合遵循严格约束见协议注释事件仅发生在服务上service必填serviceInstance、endpoint可选事件发生在服务实例上service与serviceInstance必填endpoint可选事件发生在**端点Endpoint**上service与endpoint必填serviceInstance可选。各字段细节说明UUID事件可能跨越较长的时间段例如一次持续数分钟的升级。只有借助 UUID才能把同一事件的开始时间与结束时间关联起来。Name事件的名称例如Start、Stop、Crash、Reboot、Upgrade等用于快速识别事件类别。Type面向 UI 可视化的友好字段。Normal类型被视为正常操作Error类型被视为意外操作如Crash。UI 会用不同颜色区分两类事件便于快速定位异常。Message描述事件发生原因的一行文本。例如一次Upgrade事件可以写作Upgrade from ${from_version} to ${to_version}。不建议把详细日志如异常堆栈塞进 message 字段。Parametersmessage中的参数映射是一个简单的string, stringmap例如把from_version、to_version作为参数附带。Start Time / End Time均为 Unix 毫秒时间戳。事件发生时startTime必填endTime在事件未结束时可为空否则必须是一个晚于startTime的合法时间戳。上报调用模式上报事件时通常需要调用两次上报接口第一次报告事件开始第二次报告事件结束两次使用相同的 UUID。也存在一次调用即可完成的场景——例如从第三方系统导出事件时开始与结束时间已经确定只需调用一次上报接口即可。事件在后端的处理与存储分析链路事件进入 OAP 后由 EventAnalyzerServiceImpl 执行分析。其中有一个值得注意的兜底逻辑如果事件的startTime与endTime都不大于 0即均无效会打印告警日志并将其都设置为当前时间避免时间字段缺失导致后续查询异常。随后 EventRecordAnalyzerListener 完成字段映射其核心处理包括解析layer并设置到事件上event.setLayer(Layer.nameOf(e.getLayer()))通过NamingControl对 service / serviceInstance / endpoint 名称做统一格式化对应源码中的formatServiceName、formatInstanceName、formatEndpointName保证与指标、追踪中的实体命名一致——这正是后续事件与指标关联可视化的基础将parameters序列化为 JSON 字符串存储若startTime 0则以startTime计算时间桶TimeBucket与时间戳否则回退到endTime。最终通过RecordStreamProcessor将事件写入存储build()方法中的RecordStreamProcessor.getInstance().in(event)。存储模型事件的存储模型定义在 server-core 的 Event 记录类 中索引名为event属于 Record 流RecordStreamProcessor。其关键存储列包括存储列说明uuid事件唯一 ID同时是 SeriesIDBanyanDB索引位 0service/service_instance/endpoint事件来源对象经命名规整后写入event_name事件名称type事件类型Normal / Error 的字符串形式message事件消息storageOnlytrue最大长度 2000parameters参数 JSONstorageOnlytrue最大长度 4000start_time/end_time起止时间毫秒时间戳start_time与timestamp开启 DocValues 便于排序layer所属 Layer以整型值存储timestamp事件时间戳BanyanDB 的时间列存储 ID 由time_bucket uuid共同构成保证同一时间桶内 UUID 唯一。查询与合并事件查询由 EventQueryService 提供支持单条件与多条件查询GraphQL 层对应 EventQuery。查询时有两点约束值得注意未提供 UUID 时时间范围time必填否则抛出IllegalArgumentException查询结果会按 UUID 进行合并同一 UUID 的多条记录开始事件与结束事件分开上报的情况会被合并为一条取最早的startTime与最晚的endTime再按时间戳升序或降序排序默认降序。这一合并逻辑由mergeAndSortEvents方法实现它把同一事件的开始/结束两条记录在查询侧还原为一条完整事件与文档中两次上报使用相同 UUID的设计相互印证。事件与指标的关联SkyWalking UI 会在仪表盘中可视化事件当事件的 service / instance / endpoint 与仪表盘当前展示的 service / instance / endpoint 匹配时事件就会出现在对应的时间线上。由于事件在入库前已经通过NamingControl做了与服务、实例、端点一致的命名规整因此事件天然能够与同实体下的指标、追踪数据对齐到同一时间轴。运维人员可以直观地看到某次升级/重启/混沌演练期间服务的响应时间与错误率发生了什么变化从而把事件与性能指标关联起来做根因分析。已知事件清单来自 Java Agent 的事件名称类型触发时机来源StartNormal安装了 SkyWalking Agent 的 Java 应用启动时SkyWalking Agent 上报ShutdownNormal安装了 SkyWalking Agent 的 Java 应用停止时SkyWalking Agent 上报来自 Kubernetes Event Exporter 的事件以下事件均由 Kubernetes Event Exporter 上报如需在 SkyWalking 中看到这些事件请确保已部署该导出器名称类型触发时机来源KillingNormalKubernetes Pod 正在被终止时Kubernetes Event ExporterPullingNormal正在拉取部署所需的 Docker 镜像时Kubernetes Event ExporterPulledNormal部署所需 Docker 镜像拉取完成时Kubernetes Event ExporterCreatedNormalPod 内容器创建完成时Kubernetes Event ExporterStartedNormalPod 内容器启动完成时Kubernetes Event ExporterUnhealthyErrorreadiness 探针失败时Kubernetes Event Exporter完整的 Kubernetes 事件列表可在 Kubernetes 代码库的pkg/kubelet/events/event.go中查看但需要注意并非所有 Kubernetes 事件都被导出器支持实际可用事件以 exporter 的实现为准。协议定义速查事件上报协议的核心定义gRPC 服务与消息格式完整收录在本仓库 docs/en/api/event.md 中要点如下service EventService { rpc collect (stream Event) returns (Commands) { } }Event消息字段编号依次为uuid1、source2、name3、type4、message5、parameters6、startTime7、endTime8、layer9Type枚举为Normal 0、Error 1。事件类型、Source 约束与本文前述字段说明完全一致可作为实现上报客户端或排查上报问题的一手依据。总结SkyWalking 的事件体系补全了日志、指标、链路之外的可观测性视角让升级、重启、Kubernetes 编排等系统级事件能够以结构化的方式进入统一平台上报链路支持 gRPC流式、HTTPPOST /v3/events批量 JSON与 Kafka 三种协议接收端默认注册于 OAP 共享服务数据模型以 UUID 关联事件起止包含 source、name、type、message、parameters、起止时间与 layer 等字段layer自 v9.0.0 起为必填处理与存储事件经分析器归一化命名后写入event索引Record 流查询侧按 UUID 合并开始/结束记录并按时间排序可视化关联事件与同 service / instance / endpoint 的指标在同一仪表盘时间轴展示便于结合性能指标做根因分析。对于希望上报自定义事件的开发者可参照本文的协议定义与 JSON 示例直接对接POST /v3/events或 gRPCcollect接口对于运维 Kubernetes 集群的团队部署 Kubernetes Event Exporter 即可将容器编排事件纳入统一可观测平台。【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址: https://gitcode.com/gh_mirrors/sk/skywalking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考