Apache SkyWalking 8.4.0 版本全解析：日志可观测、多告警规则、MAL 与 Envoy V3 的落地实践

Apache SkyWalking 8.4.0 版本全解析：日志可观测、多告警规则、MAL 与 Envoy V3 的落地实践

【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址: https://gitcode.com/gh_mirrors/sk/skywalking

本文以 Apache SkyWalking 8.4.0 官方版本变更记录（changes-8.4.0.md）为核心骨架，结合当前仓库中的 OAP 源码、Agent 插件实现与真实配置样例，系统梳理该版本在日志收集与查询、告警体系、MAL 指标分析、Envoy V3 协议兼容、Java Agent 增强与工程化改进方面的全部要点，并给出可直接落地的配置方法与升级注意事项。读完本文，你将能判断 8.4.0 的兼容性边界、掌握 Feishu 告警等新增能力的配置方式，并理解这些能力背后的源码实现。

一、版本定位：8.4.0 的三个主线

从变更记录看，8.4.0 并非一次小修小补，而是围绕三条主线的大版本：

1. 日志可观测闭环：Agent 侧支持通过 gRPC 收集并转发日志（含 logback 1.x / log4j 2.x 的格式化与未格式化消息），OAP 侧实现日志的收集、存储与查询，UI 侧新增服务日志查看与 Trace 详情页查看日志——这是该版本功能增量最大的部分。
2. 告警能力升级：支持同一实体触发多条告警规则，并新增飞书（Feishu）告警渠道；告警记录存储实体 ID 结构发生破坏性变更。
3. 指标分析全面拥抱 MAL：Meter Receiver 支持 MAL，Envoy 指标服务分析器也迁移到 MAL，并新增基于 MAL 的 VM（node-exporter）监控模板。

与此同时，该版本还完成了 Envoy{AccessLog,Metrics}ServiceV3 协议支持、.proto文件package声明规范化、ElasticSearch 7.10 测试矩阵、skywalking-eyes 许可证检查工具替换等工程化改进。

二、告警体系：多规则触发与 Feishu 新渠道

2.1 同一实体支持多条告警规则（破坏性变更）

8.4.0 之前，一个实体（服务/实例/端点）在同一告警存储记录中只能关联一个触发规则。8.4.0 将规则名称（rule name）加入告警记录存储实体的 ID 组成部分，并从 ID 中移除了 scope id，从而支持同一实体被多条规则命中时各自生成独立告警记录。

这直接带来了该版本最重要的兼容性提示：

与使用 H2/MySQL/TiDB 存储选项的旧版本不兼容。如果你使用这三种存储且存在历史告警数据，升级 8.4.0 时需要评估数据迁移或重建方案；而 ElasticSearch 与 InfluxDB 存储不受此影响（其 ID 结构由文档/JSON 自由定义）。

从源码看，告警规则的绑定关系由 alarm-settings.yml 中的rules与hooks两段定义：规则通过hooks: ["slack.custom1"]这类{hookType}.{hookName}格式绑定具体通知渠道，未显式绑定的规则会走is-default: true的默认 hook（可同时存在多个默认 hook）。相关解析逻辑集中在 RulesReader.java。

2.2 新增 Feishu 告警渠道：配置与签名原理

8.4.0 新增“Support Alarm to feishu”，飞书机器人告警由此进入官方支持列表（与已有的 Slack、PagerDuty、DingTalk、WeChat、WeLink 等并列，hook 类型枚举见 AlarmHooksType.java 中的feishu）。

在 alarm-settings.yml 中，飞书告警的完整配置模板如下：

hooks: feishu: default: is-default: true text-template: |- { "msg_type": "text", # at someone with feishu_user_ids # "ats": "feishu_user_id_1,feishu_user_id_2", "content": { "text": "Apache SkyWalking Alarm: \n %s." } } webhooks: - url: https://open.feishu.cn/open-apis/bot/v2/hook/dummy_token secret: dummysecret

各字段含义与注意事项：

配置解析由RulesReader.readFeishuConfig()（RulesReader.java）完成：text-template、recovery-text-template默认取空串，webhooks列表中每个元素读取secret与url，最终装配为 FeishuSettings.java 中的WebHookUrl(secret, url)列表。

签名与 @ 的实现原理（对应 FeishuHookCallback.java）：

• 签名：当secret非空时，取当前 Unix 时间戳（秒），以timestamp + "\n" + secret为待签名字符串，使用HmacSHA256计算摘要并 Base64 编码得到sign，与timestamp一起写入消息体（sign()方法，L129-L135）。该流程与飞书机器人官方签名校验算法一致。
• @ 指定用户：模板中若含ats字段，buildContent()（L110-L124）会按逗号切分用户 ID，为每条告警消息追加<at user_id="xxx"></at>标签。
• 发送：消息按 hook 分组后，对每个 webhook URL 逐条POST（L69-L78），单条失败仅记录错误日志，不影响其余消息发送。

该能力有配套单元测试 FeishuHookCallbackTest.java 与配置样例 alarm-settings.yml，可作二次开发参考。

2.3 告警相关的其他修复

• 修复parseInternalErrorCode中部分错误码永远无法命中的问题。
• 修复动态配置激活 UninstrumentedGateways 时的 CVE。
• timeBucket不再参与部分关系指标的EqualsAndHashCode，避免告警指标比较语义错误。

三、日志可观测：从 Agent 到 UI 的完整链路

8.4.0 的“Log collecting and query implementation”是贯穿三端的端到端能力：

Agent 侧：

• 支持收集日志并通过 gRPC 转发到 OAP（“Support collecting logs and forwarding through gRPC”）。
• 新增对 logback 1.x 与 log4j 2.x 的格式化与未格式化消息传输支持——这意味着无论日志以何种格式输出，都能被采集。
• 配套的agent.trace.ignore_path等运行时配置可动态调整采集范围（见下文 Agent 章节）。

OAP 侧：

• 实现日志接收、分析与存储链路；日志分析可通过 lal.yaml 这类 LAL（Log Analysis Language）规则进行解析（LAL 的完整语法见 lal.md）。
• ElasticSearch 存储新增日志查询文本分析器（“Add the text analyzer for querying log in the es storage”），支持对日志正文做分词检索。
• 移除无用的日志查询参数，并修复了接收端分析错误计数指标。

UI 侧：

• 实现服务日志查看（“Implement the service logs on UI”）。
• 支持在 Trace 详情页直接查看关联日志（“Implement viewing logs on trace page”）。
• 修复日志查询条件、日志时间显示与日志搜索界面等细节问题。

从变更记录推断，该版本日志查询协议、UI 日志查询模板等配套内容随后续版本持续完善；8.4.0 是 SkyWalking 从“Trace/Metrics 双支柱”走向“Trace/Metrics/Log 三支柱”的关键起点。

四、MAL 全面接管指标分析

4.1 Meter Receiver 支持 MAL

8.4.0 将 Meter Receiver 从旧的 OAL 度量定义迁移到 MAL（Metric Analysis Language）。MAL 的 DSL 设计与执行机制可参考 mal.md 与 MAL 语法定义。核心执行入口位于 Analyzer.java 与 MetricConvert.java，规则配置类为 MetricRuleConfig.java。

同期修复的 MAL 相关问题：

• 并发执行问题（“Fix MAL concurrent execution issues”）；
• 同名 sample 冲突：同一 MAL 表达式中同名 sample 在Analyzer.analyse中触发IllegalArgumentException，已修复。

4.2 Envoy 指标服务分析器采用 MAL

Envoy MetricsService 的分析器由硬编码规则迁移到 MAL（“Adopt the MAL in Envoy metrics service analyzer”），并修复了 ALS 分析器的优先级设置失效问题。结合 Envoy V3 支持（见下文），8.4.0 在服务网格可观测上完成了“V3 协议 + MAL 分析”的组合升级。

4.3 VM 监控：MAL + node-exporter

新增 VM MAL 规则与 UI 模板（“Add VM MAL and ui-template configration”），支持接收由 OpenTelemetry-collector 推送的 Prometheus node-exporter 虚拟机指标。这为传统虚拟机监控场景提供了开箱即用的指标建模方案。

4.4 OAL 与指标查询

• OAL 支持在数值上下文中取多值（“OAL supports multiple values when as numeric”）。
• 移除 OAL disable 语句参数的严格限制。
• 修复全局级指标查询的合法性问题：不再支持全局级别的指标查询，属于行为收敛，升级后需确认既有查询是否依赖全局聚合。

五、Envoy / Istio：V3 协议全量支持

• 协议支持：新增 Envoy{AccessLog,Metrics}ServiceAPI V3 支持，OAP 侧 Envoy ALS handler 同步清理了重复代码。ALS 分析器还从 OpenCensus proto 的样本中提取节点信息（node 信息进入 sample labels），用于识别指标数据来源。
• 测试验证：在 Istio 1.8.2 环境下搭建 Envoy ALS / MetricsService 测试，验证 Envoy V3 协议兼容性。
• UI/面板：Istio 控制平面移除冗余指标并优化面板布局；修复 istio 版本指标类型与 otel 规则不匹配的问题；新增 Envoy 代理组件 Logo 与拓扑图标修复。

六、Java Agent：可观测性增强与兼容性调整

6.1 操作名（Operation Name）变更 —— 升级需关注

两个插件对 Span 操作名的格式进行了破坏性调整：

变更后，依赖旧操作名进行告警规则、端点分组、追踪查询的历史数据将无法与新数据对齐，升级后建议重新审视相关告警规则与端点聚合配置。

6.2 插件机制与新增插件

• Witness 方法机制（“Add witness method mechanism in the agent plugin core”）：通过探测类中是否存在特定“见证方法”来判断目标类版本，提升插件匹配的准确性与健壮性，是插件核心（apm-agent-core）的新能力。
• 新增 Dolphinscheduler 插件定义：Apache Dolphinscheduler 从此进入官方支持列表，UI 同步添加了 Dolphinscheduler 的 Logo。
• elasticsearch-6.x-plugin 增强：新增analyze、searchScroll、clearScroll、searchTemplate、deleteByQuery五个方法的拦截器；同时修复该插件导致的线程泄漏问题。
• mssql-plugin 修复：调用返回生成键（generate key）的方法时出现的ClassCastException已修复。

6.3 采样与配置热更新

• 采样在 Trace 忽略插件激活时仍能正常工作（“Make sampling still works when the trace ignores plug-in activation”）。
• 以下配置支持运行时动态修改（无需重启 Agent）：agent.sample_n_per_3_secs（每 3 秒采样条数）、agent.ignore_suffix（忽略后缀）、agent.trace.ignore_path（忽略路径）。此能力与 OAP 侧新增的ConfigurationDiscovery（configuration-discovery-receiver-plugin）相配合——Agent 通过 gRPC 向 OAP 订阅动态配置，OAP 侧配置文件改动后可下发至 Agent 生效。

6.4 传输与网络

• DNS 周期解析机制：Agent 支持对后端服务地址做周期性 DNS 解析以更新后端服务列表，适应后端实例 IP 动态变化的场景。
• gRPC TLS：支持构建 gRPC TLS 通道但不要求必须提供 CA 文件。
• trace_sql_parameters：修复启用后可能出现的 NPE。
• 链路头部覆盖修复：jdk-http 与 okhttp-3.x 插件未覆盖旧 trace header 的问题已修复。
• RestTemplate：修复 URL tag 记录错误端口的问题。
• thrift 插件：修复中间服务未挂载 Agent 时链路断裂，以及无参方法收集错误参数的问题。
• rocketmq-plugin：修复设置错误 tag 的问题。
• Toolkit 支持读取 segmentId 与 spanId：业务代码可通过 toolkit API 直接获取链路上下文标识。
• 其他：修复EnhancedInstance接口重复添加、Tomcat 插件意外的RunningContext重建、DataCarrier 的Buffer在IF_POSSIBLE模式下未激活及ArrayBlockingQueueBuffer无用列表问题；byte-buddy升级到 1.10.19。

七、协议兼容性：proto 文件新增 package 声明

8.4.0 为.proto文件添加了package声明，避免在某些语言中污染顶层命名空间。由此带来明确的兼容性矩阵：

• 新版 OAP（>= 8.4.0）仍兼容旧版 Agent（Agent 上报协议未破坏）；
• 旧版 OAP（<= 8.3.0）无法识别新版 Agent（>= 8.4.0）——若 Agent 与 OAP 混合部署且版本跨越 8.4.0，必须先升级 OAP。

升级路径建议：先升级 OAP 到 8.4.0（此时旧 Agent 仍可上报），再分批滚动升级 Agent。

八、工程与测试改进

• ElasticSearch 7.10 纳入测试矩阵并验证可用，ES 存储兼容面扩展至 7.x 系列。
• 许可证检查工具替换：用 skywalking-eyes 替换 Apache RAT 检查 license header，UI 与后端同步补齐缺失的 license header。
• 发布脚本：适配create_source_release.sh使其可在 Linux 上运行。
• E2E 测试：修复 Kafka 的 flaky E2E 测试。

九、UI 与文档

UI 侧除日志查看、拓扑改进外，还包含：Trace 查询页支持 tag 值中的=字符、拓扑支持按组筛选并新增图例、刷新周期不允许负数、日志与 Dashboard 选择器数据分离避免冲突、profile 任务列表按钮图标化、Python aiohttp/pyramid 与 http 类型图标新增等。文档侧则更新了后端 fetcher、自可观测性、服务分组名、Trace 采样、Kafka 插件支持版本（2.6.1）等说明，并新增 Mac M1 芯片编译 FAQ。

十、升级 8.4.0 检查清单

1. 告警存储：H2/MySQL/TiDB 存储因告警记录 ID 结构变化与旧版本不兼容，评估数据迁移或接受告警历史重建。
2. 协议版本：先升级 OAP 再升级 Agent；8.4.0 的 OAP 兼容旧 Agent，反之不兼容。
3. 操作名：quartz-scheduler、dubbo 系列插件操作名格式变更，检查依赖旧格式的告警规则、分组规则与查询。
4. 全局指标查询：不再支持全局级别指标查询，校验既有查询是否受影响。
5. 新能力可选配置：按需开启 Feishu 告警（hooks 段）、日志采集与查询、VM node-exporter 监控等新增能力。

结语

8.4.0 以“日志 + 告警 + MAL”三驾马车完成了 SkyWalking 可观测数据面的重要升级：日志链路打通了采集、存储、查询与 UI 呈现；告警支持一实体多规则与 Feishu 渠道；MAL 成为指标分析的统一引擎。对于正在使用 8.3.x 及更早版本的用户，请务必对照本文第十章检查清单评估兼容性后再升级。

【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址: https://gitcode.com/gh_mirrors/sk/skywalking