下一篇【第74篇】SkyWalking 9.x新特性——K8s原生集成、Continuous Profiling与Layer概念上一篇【第76篇】SkyWalking完整技术栈选型决策树——从Agent到OAP到存储的企业级选型指南一、开篇 —— 每个SkyWalking用户的必修课在SkyWalking社区有一个流传很久的笑话“安装SkyWalking只需要5分钟排查SkyWalking为什么没数据需要5小时。”这不是玩笑。SkyWalking作为一个分布式系统涉及Agent、网络、OAP、存储四个环节任何一个环节出问题都会导致看起来一切正常但就是没数据。本文是我在生产环境中填坑多年的经验总结用最直白的话讲最实战的排查思路。每一个坑背后都有一个深夜排查的血泪故事。二、第一大坑Agent不上报数据这是最高频的问题没有之一。2.1 从外到内的六步排查法------------------------------------------------------------------ | Agent不上报数据的六步排查法 | ------------------------------------------------------------------ | | | Step 1: Agent启动了吗 | | ┌────────────────────────────────────────────────────┐ │ | │ 检查: 启动日志中有没有SkyWalking的日志 │ │ | │ 命令: grep SkyWalking app.log │ │ | │ 正常: SkyWalking Agent 9.7.0 initialized │ │ | │ 异常: 没有 → 检查 -javaagent: 参数是否正确配置 │ │ | └────────────────────────────────────────────────────┘ │ | │ │ | 没有日志? ↓ │ | │ │ | Step 2: Agent加载了你的插件吗 | | ┌────────────────────────────────────────────────────┐ │ | │ 检查: plugins/ 目录下的Jar是否正确 │ │ | │ 注意: 有些Jar需要放 optional-plugins/ │ │ | │ 有些Jar需要放 bootstrap-plugins/ │ │ | │ 命令: ls skywalking-agent/plugins/ │ │ | └────────────────────────────────────────────────────┘ │ | │ │ | 插件没问题? ↓ │ | │ │ | Step 3: 网络通吗 | | ┌────────────────────────────────────────────────────┐ │ | │ 检查: Agent能否连接到OAP │ │ | │ 命令: telnet oap-server 11800 │ │ | │ 正常: Connected to oap-server │ │ | │ 异常: Connection refused / timeout │ │ | │ → 检查防火墙/安全组/网络策略 │ │ | └────────────────────────────────────────────────────┘ │ | │ │ | 网络通的? ↓ │ | │ │ | Step 4: 注册成功了吗 | | ┌────────────────────────────────────────────────────┐ │ | │ 检查: OAP日志中是否有注册记录 │ │ | │ 命令: grep register oap.log │ │ | │ 正常: register service [order-service] success │ │ | │ 异常: 没有注册日志 → 检查service_name配置 │ │ | │ agent.service_name${SW_AGENT_NAME:YourName} │ │ | └────────────────────────────────────────────────────┘ │ | │ │ | 注册成功? ↓ │ | │ │ | Step 5: 数据真的发了吗 | | ┌────────────────────────────────────────────────────┐ │ | │ 检查: Agent的GRPCChannel状态 │ │ | │ 日志: Report trace segment to collector │ │ | │ 如果没有 → Trace没有被创建 → 检查插件是否拦截 │ │ | └────────────────────────────────────────────────────┘ │ | │ │ | 数据发了? ↓ │ | │ │ | Step 6: OAP处理了吗 | | ┌────────────────────────────────────────────────────┐ │ | │ 检查: OAP日志中是否有数据处理记录 │ │ | │ 检查: ES中是否有新数据 │ │ | │ curl localhost:9200/segment*/_count │ │ | │ → 如果ES有数据但UI看不到 → 可能是时间范围问题 │ │ | └────────────────────────────────────────────────────┘ │ | | ------------------------------------------------------------------2.2 一个经典案例案例Agent启动正常、网络通、注册成功但UI上就是没数据。排查过程# 1. Agent日志里搜索reportgrepreportagent.log# 结果: (空) → Trace根本没产生# 2. 检查应用代码# 发现应用是一个纯定时任务没有任何HTTP请求或RPC调用# 定时任务里直接操作数据库 → 没有创建EntrySpan# 3. 解决方案# 为定时任务添加手动追踪Scheduled(fixedDelay60000)public voidmyTask(){AbstractSpan spanContextManager.createEntrySpan(/scheduled/myTask, null);try{// 定时任务逻辑}finally{ContextManager.stopSpan();}}教训纯批处理/定时任务应用需要手动创建EntrySpan因为SkyWalking不会自动拦截main方法或 Scheduled方法。三、第二大坑Trace数据不完整3.1 截断的Trace是运营的噩梦------------------------------------------------------------------ Trace不完整的几种典型症状 ------------------------------------------------------------------ | | | 症状1: 只有入站没有出站 | | ┌────────────────────────────────────────────────────┐ │ | │ Agent A (order-service) Agent B (user-svc) │ │ | │ ┌─────────┐ ┌─────────┐ │ │ | │ │EntrySpan│ ── OKHttp调用 ──→ │ ??? │ │ │ | │ │ │ │ 没数据! │ │ │ | │ └─────────┘ └─────────┘ │ │ | │ │ │ | │ 原因: Agent B的插件没拦截到请求 │ │ | │ → 检查user-svc的skywalking-agent配置 │ │ | │ → OKHttp插件是否启用: plugin.okhttp.trace true │ │ | └────────────────────────────────────────────────────┘ │ | | | 症状2: 方法调用丢失 | | ┌────────────────────────────────────────────────────┐ │ | │ Trace中看到: │ │ | │ EntrySpan → ExitSpan(DB) │ │ | │ 但中间应该还有一个LocalSpan(缓存查询)不见了! │ │ | │ │ │ | │ 原因: 缓存客户端(Redis/Caffeine)插件未加载 │ │ | │ → 检查对应插件Jar是否在plugins/目录下 │ │ | └────────────────────────────────────────────────────┘ │ | | | 症状3: Span有但没有父子关系 | | ┌────────────────────────────────────────────────────┐ │ | │ 两个Span显示为独立的Trace而非父子关系 │ │ | │ │ │ | │ 原因: sw8 header丢失 │ │ | │ → 检查HTTP Client是否过滤了Header │ │ | │ → 检查Nginx/网关是否透传自定义Header │ │ | │ → 检查Dubbo Filter是否有自定义逻辑 │ │ | └────────────────────────────────────────────────────┘ │ | | ------------------------------------------------------------------3.2 Trace不完整排查清单# Trace完整性排查# 1. 检查sw8 header是否被传播# 在服务端打印所有HeaderGetMapping(/test)public String test(HttpServletRequest request){EnumerationStringheadersrequest.getHeaderNames();while(headers.hasMoreElements()){String nameheaders.nextElement();System.out.println(name : request.getHeader(name));}returnok;}# 如果sw8 header缺失# - 检查网关/LoadBalancer是否过滤了自定义Header# - Nginx: proxy_pass_request_headers on;# - Spring Cloud Gateway: 检查Filter顺序# 2. 检查异步调用# Async方法中的Trace是否连续# → 确保使用了ContextSnapshot四、第三大坑告警不触发4.1 告警规则的调试# 告警调试配置rules:# 调试用的小阈值规则test_alert:metrics-name:service_cpmthreshold:1# 只要有一次调用就告警op:period:1# 只检查1分钟count:1# 出现1次就告警message:TEST: service {name} has traffic# 如果这个告警都不触发说明# 1. OAP没收到Metrics数据# 2. 告警规则格式有问题# 3. 告警配置没有被OAP加载4.2 告警不触发的常见原因原因1: 告警规则文件位置不对 - 检查: oap-server/config/alarm-settings.yml 是否存在 - 如果通过ConfigMap挂载确认挂载路径正确 原因2: 指标名拼写错误 - service_resp_time ✓ - service_response_time ✗ 原因3: OAP没有重启加载新规则 - 需要重启OAP或使用动态配置 原因4: 告警通知渠道配置错误 - 检查webhook URL是否可达 - 检查钉钉/企业微信的token是否正确 原因5: 静默期未过 - silence-period: 10 → 告警后10分钟内不再发送 - 调整silence-period或等静默期过去五、第四大坑Elasticsearch存储问题5.1 ES集群变红# 症状SkyWalking UI打开很慢或报错# 排查# 1. 检查ES集群健康curlhttp://es-node:9200/_cluster/health# {status:red,...} ← 危险# 2. 检查磁盘curlhttp://es-node:9200/_cat/allocation?v# 如果磁盘使用率 85% → ES会拒绝写入# 3. 紧急处理# 删除旧索引释放空间curl-XDELETEhttp://es-node:9200/sw_segment-20260701# 或调高磁盘水位线临时方案curl-XPUThttp://es-node:9200/_cluster/settings-HContent-Type: application/json-d { transient: { cluster.routing.allocation.disk.watermark.low: 90%, cluster.routing.allocation.disk.watermark.high: 95% } }5.2 索引爆炸# 问题: 每天产生几百个索引ES性能急剧下降# 原因分析:# SkyWalking为每种指标类型创建按天分片的索引# 如果指标类型很多自定义了很多OAL指标索引数量会爆炸# 解决方案:# 1. 限制索引保留天数storage:elasticsearch:traceDataTTL:7# Trace保留7天metricDataTTL:7# 指标保留7天recordDataTTL:7# 记录保留7天# 2. 定时清理旧索引# 创建ES ILM策略Index Lifecycle Management# 或者使用CronJob定时删除0 2 * * * curl-X DELETE http://es:9200/sw_*-$(date-d 8 days ago %Y%m%d)六、第五大坑UI展示异常# 症状1: 拓扑图显示白屏# 排查:# 1. 浏览器F12 → Console → 看JS报错# 2. 检查OAP的GraphQL接口是否正常curlhttp://oap-server:12800/graphql# 3. 清除浏览器缓存# 4. 升级UI版本可能和OAP版本不匹配# 症状2: Trace详情页加载超时# 排查:# 1. 检查ES查询速度# 2. 检查网络UI→OAP→ES# 3. Trace数据量太大超过ES默认限制# 设置 OAP 参数# SW_CORE_GRPC_MAX_MESSAGE_SIZE104857600# 症状3: Dashboard加载不出来# 排查:# 检查GraphQL查询是否正确# 有可能是OAP版本和UI版本不一致# 查看UI容器的日志: kubectl logs deployment/skywalking-ui七、第六大坑升级SkyWalking版本7.1 升级惨案与正确姿势------------------------------------------------------------------ | 升级SkyWalking的正确姿势 | ------------------------------------------------------------------ | | | ❌ 错误做法: | | ┌────────────────────────────────────────────────────┐ │ | │ 1. 周五下午直接升 │ │ | │ 2. 不备份就升 │ │ | │ 3. 跨多个大版本升 │ │ | │ 4. 全量切换不留灰度 │ │ | └────────────────────────────────────────────────────┘ │ | | | ✓ 正确做法: | | ┌────────────────────────────────────────────────────┐ │ | │ 1. 周二/周三升级留足修复时间 │ │ | │ 2. 先搭验证环境用生产数据量压测 │ │ | │ 3. 确认Agent和OAP版本兼容 │ │ | │ 4. 逐步灰度先升20% Agent → 观察 → 全部升Agent │ │ | │ 5. 升OAP先启一个新版本OAP集群 → 切换流量 → 停旧 │ │ | │ 6. 保留旧版本环境一周快速回退能力 │ │ | └────────────────────────────────────────────────────┘ │ | | ------------------------------------------------------------------# 升级检查清单# # 1.0 升级前echo 升级前检查 echo1. 确认当前版本:grepversionskywalking-agent/config/agent.configecho2. 确认目标版本Release Notesecho3. 备份OAP配置和ES数据echo4. 确认新版本Agent兼容旧版本OAP滚动升级的关键# 2.0 升级步骤echo Agent灰度升级 # 先升级1个Pod的Agent观察15分钟kubectlsetimage deployment/order-service\apporder-service:v2-with-new-agent# 检查# - UI上是否有新数据# - 告警是否正常# - Agent日志有没有异常# 3.0 OAP升级echo OAP升级 # 使用新namespace部署新版本OAPhelminstallskywalking-v2 skywalking/skywalking\--namespacemonitoring-v2\--valuesnew-values.yaml\--setoap.image.tag9.3.0# 将Agent流量逐步切到新OAP# 观察数据完整性# 确认无误后停止旧OAP八、总结防坑口诀------------------------------------------------------------------ | SkyWalking生产防坑口诀 | ------------------------------------------------------------------ | | | Agent不上报 → 六步排查 (启动→插件→网络→注册→发送→处理) | | Trace断了 → 找sw8 header (网关/代理/Filter 没透传?) | | 告警不触发 → 调试规则 (先验证最简单的告警能否触发) | | ES红了 → 马上看磁盘 删旧索引 | | UI白屏 → F12看Console 清缓存 | | 要升级 → 选周二 先灰度Agent 再升OAP | | | ------------------------------------------------------------------下一篇【第74篇】SkyWalking 9.x新特性——K8s原生集成、Continuous Profiling与Layer概念上一篇【第76篇】SkyWalking完整技术栈选型决策树——从Agent到OAP到存储的企业级选型指南