SkyWalking 各版本 Agent 与 OAP 后端兼容性指南原生 Agent 与生态 Agent 全览【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址: https://gitcode.com/gh_mirrors/sky/skywalkingSkyWalking 从 8.0 开始全面采用 v3 系列通信协议Trace Data Protocol v3、Cross Process Propagation Headers Protocol v3Agent 与 OAP 后端之间不再要求版本号完全一致。本文基于仓库 agent-compatibility.md 的官方兼容性矩阵系统梳理 SkyWalking 原生 AgentJava、Python、NodeJS、LUA、Kong、Browser、Rust、PHP、Go、Rover、Satellite与生态 AgentDotNet、cpp2sky在各 OAP 版本下的匹配关系并解读 v3 协议、unimplemented错误等关键机制帮助你在升级 OAP 或选用 Agent 版本时快速做出正确决策。一、兼容性总览v3 协议带来的版本解耦1.1 核心前提SkyWalking 8.0 使用 v3 协议官方兼容性文档开篇即明确SkyWalking 8.0 使用 v3 协议Agent 无需与 OAP 后端保持完全相同的版本号。这里的 v3 指的是 SkyWalking 自 8.0 起全面切换的数据通信协议族主要包括Trace Data Protocol v3定义 Agent/SDK 与后端之间 Trace 数据的传输格式基于 gRPC 定义并实现于 HTTP 1.1。协议中以SegmentObject为基本上报单元一个 Segment 包含一次请求上下文通常是一个 OS 进程内的单线程的全部 Span并通过SegmentReference携带跨线程/跨进程的父子关系。Cross Process Propagation Headers Protocol v3即sw8传播协议负责跨进程上下文传播。标准 Headersw8由 8 个以-分隔的字段组成采样标记、Trace ID、父 Segment ID、父 Span ID、父服务名、父实例名、父端点名、目标地址值长度默认不超过 2k扩展 Headersw8-x则用于 Tracing Mode、发送时间戳等高级交互。正是协议版本而非发布版本作为兼容基准使得 Agent 与后端可以在较大版本跨度内自由组合这也是整个兼容性矩阵成立的技术根基。协议的具体定义与字段说明可进一步参考 Trace Data Protocol v3 与 Cross Process Propagation Headers Protocol v3。1.2 阅读兼容性矩阵的规则表格中“OAP Server Version”列表示后端OAP 服务器版本区间各 Agent 列中的版本号表示该 Agent 与对应 OAP 区间兼容的版本范围All表示该 Agent 的所有发布版本均兼容No表示在该 OAP 版本区间内尚无该 Agent或官方未声明兼容 x.y.z表示仅需满足最低版本要求更高版本同样兼容例如8.0.0 - 8.3.0表示兼容 8.0.0 至 8.3.0含之间的所有版本。二、SkyWalking 原生 Agent 兼容矩阵原生 Agent 由 Apache SkyWalking 官方维护其源码与发行物均归属于 Apache 软件基金会。以下矩阵完整摘录自 agent-compatibility.mdOAP Server VersionJavaPythonNodeJSLUAKongBrowser AgentRustPHPGoRoverSatellite8.0.1 - 8.1.08.0.0 - 8.3.0 0.6.0 0.3.0AllAllNoAllNoNoNoNo8.2.0 - 8.3.08.0.0 - 8.3.0 0.6.0 0.3.0AllAllAllAllNoNoNoNo8.4.0 - 8.8.1 8.0.0AllAllAllAllAllAllAllNoNoNo8.9.0 8.0.0AllAllAllAllAllAllAllNoNo 0.4.09.0.0 8.0.0AllAllAllAllAllAllAllNoNo 0.4.09.1.0 8.0.0AllAllAllAllAllAllAllNo 0.1.0 1.0.09.5.0 8.0.0 9.0.0AllAllAllAllAllAllAll 0.1.0 0.5.0 1.2.02.1 Java Agent最稳定的兼容基线Java Agent 是所有原生 Agent 中兼容面最宽的8.0.1 - 8.3.0仅兼容 Java Agent 8.0.0 - 8.3.0属于早期 v3 协议过渡期Java Agent 版本需跟随 OAP 保持在同一代际8.4.0 起Java Agent 8.0.0 即可版本要求大幅放宽9.5.0 起要求同时满足 8.0.0与 9.0.0即 9.x 线需 9.0.0这意味着从 9.5.0 开始后端要求 Java Agent 的 9.x 主版本不低于 9.0.0以避免旧版 9.0.0 之前的协议行为差异。提示表中 8.0.0 9.0.0是一种“双线约束”写法——即 8.x 系列取 8.0.09.x 系列取 9.0.0两条件同时成立。2.2 Python / NodeJS / LUA / Kong / Rust / PHP / GoPython早期仅支持 0.6.08.0.1 - 8.3.0自8.4.0 起放开为 All即所有 Python Agent 版本均可用NodeJS早期仅支持 0.3.0自8.4.0 起放开为 AllLUA从 8.0.1 起即为 All是兼容性最好的原生 Agent 之一Kong全部 OAP 版本均兼容AllRust自 8.0.1 起即为 AllPHP自8.4.0 起开始支持此前为 No并持续为 AllGo自9.5.0 起开始支持要求 0.1.0此前所有 OAP 版本均为 No——注意 Go Agent 是原生 Agent 中支持最晚、版本门槛明确的一个。2.3 Rover 与 SatelliteRoverSkyWalking RovereBPF 采集器自9.1.0 起支持要求 0.1.0自9.5.0 起要求 0.5.0随 OAP 功能演进逐步抬高版本基线Satellite自8.9.0 起支持要求 0.4.09.1.0 起要求 1.0.09.5.0 起要求 1.2.0。可以观察到清晰的规律OAP 版本越新对后加入的 AgentGo、Rover、Satellite的最低版本要求越高这通常是因为新 OAP 版本依赖这些 Agent 提供的新上报字段与协议扩展。2.4 Browser AgentBrowser Agent浏览器端监控负责采集页面性能与浏览器侧的 Trace自8.2.0 起支持且自该版本起为 All在 8.0.1 - 8.1.0 期间为 No尚未提供。启用浏览器监控需确保后端receiver-browser模块开启该模块自 8.2.0 起默认开启详见 browser-agent.md。三、SkyWalking 生态 Agent 兼容矩阵生态 Agent 同样是 SkyWalking 生态的组成部分但其源码与发行物不属于 Apache 软件基金会而是由各自社区独立维护。官方兼容矩阵如下OAP Server VersionDotNetcpp2sky8.0.1 - 8.3.01.0.0 - 1.3.0 0.2.08.4.0 1.0.0All9.0.0 1.0.0AllDotNet8.0.1 - 8.3.0 区间要求 1.0.0 - 1.3.0自 8.4.0 起放宽为 1.0.0cpp2skyC Agent早期要求 0.2.0自 8.4.0 起为 All。官方文档特别强调这些项目由各自的社区维护如果遇到兼容性问题请直接联系对应社区——即生态 Agent 的兼容性保证力度与原生 Agent 不同升级前应主动向对应社区确认。四、兼容性边界遇到unimplemented错误怎么办兼容性矩阵末尾给出了一个非常重要的排障指引以上所有兼容性信息仅供参考。如果你遇到unimplemented错误说明你需要升级 OAP 后端以支持 Agent 中使用的更新特性。4.1 错误成因当 Agent 向 OAP 上报数据时如果携带了后端尚未实现的服务方法、命令或扩展字段OAP 会以 gRPC 标准状态码UNIMPLEMENTED拒绝处理Agent 侧表现为unimplemented错误。这通常发生在Agent 版本较新使用了 OAP 后端旧版本尚未实现的协议能力如新增的上报服务、新的命令类型你参考兼容性矩阵选择了“仅供参考”的组合但实际功能存在版本落差。4.2 处理策略首选方案升级 OAP 后端到能够覆盖所用 Agent 特性的版本而不是降级 Agent——因为 Agent 新特性往往依赖后端的分析能力次选方案在兼容矩阵允许的范围内将 Agent 回退到与当前 OAP 版本匹配的版本区间验证手段升级后重新观察上报数据是否恢复正常确认后端的receiver-*模块如 skywalking-trace-receiver-plugin 对应的 Trace 接收器已正确加载并暴露对应 gRPC 服务。五、配套阅读协议与 Agent 文档兼容性矩阵只是“选型表”要真正理解为什么某些版本组合可行建议结合仓库中的协议与部署文档一起阅读Trace Data Protocol v3Segment、SpanEntrySpan/LocalSpan/ExitSpan与 SegmentReference 的数据结构定义Cross Process Propagation Headers Protocol v3sw8/sw8-x请求头的字段规范browser-agent.md浏览器端 Agent 的启用方式与receiver-browser模块说明server-agents.md服务端侧各类 Agent 的部署指引v8-version-upgrade.md8.0 升级时 v3 协议切换的注意事项。六、结论与选型建议优先匹配协议而非版本号8.0 场景下只要双方都遵循 v3 协议即可获得较大的版本组合自由度老后端8.0.1 - 8.3.0约束最多Java/Python/NodeJS 均有限定范围Browser、PHP、Go、Rover、Satellite 尚不可用升级到 8.4.0 能显著放宽限制9.5.0 是新的分水岭Java Agent 出现双线约束Go Agent 正式纳入原生矩阵Rover/Satellite 最低版本要求同步抬升遇到unimplemented先升 OAP这是官方给出的唯一明确指引切忌盲目改动 Agent 配置生态 Agent 咨询各自社区DotNet、cpp2sky 的兼容性由社区保证生产环境选用前应向社区核实。按上述矩阵选型并配合 v3 协议文档阅读即可在升级 OAP、新增语言探针或调整 Agent 版本时快速定位兼容边界避免上报失败与隐性数据丢失。【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址: https://gitcode.com/gh_mirrors/sky/skywalking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考