使用SPL快速诊断问题根因 -- 错误分析指南

使用SPL进行诊断前请阅读下面的数据获取文档，确保拥有数据访问权限。

2025 AI 原生编程挑战赛 数据获取文档

本指南介绍如何诊断系统错误问题的根因，通过分析分布式链路追踪数据中的错误模式来定位故障服务。

适用范围：本分析方法专门针对服务调用失败导致的错误问题。

对于其他类型的系统故障（如资源瓶颈、网络问题等），需要使用相应的专门分析方法。

本文提到的相关代码保存在下面的链接中，选手可以通过教程运行notebook中的STS_Root_Cause_Analysis_Error.ipynb实现根因诊断。

https://github.com/alibabacloud-observability/tianchi-2025

1. 准备开发环境

1.1 安装基础环境

# 安装Python虚拟环境
python3 -m venv venv
source venv/bin/activate
# 安装依赖项  
pip install -r requirements.txt

1.2 配置访问凭证

设置环境变量：

export ALIBABA_CLOUD_ACCESS_KEY_ID="你的AccessKey ID"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="你的AccessKey Secret"

2025.09.22之前上传个人账号的选手，获取的STS角色名为tianchi-user-a。需要设置变量：

export ALIBABA_CLOUD_ROLE_ARN="acs:ram::1672753017899339:role/tianchi-user-a"

2025.09.22到2025.10.09期间，参加比赛并上传个人账号的选手，获取的STS角色名为tianchi-2025-role-1。需要设置变量：

export ALIBABA_CLOUD_ROLE_ARN="acs:ram::1672753017899339:role/tianchi-2025-role-1"

从2025.10.10开始，参加比赛并上传个人账号的选手，获取的STS角色名为tianchi-2025-role-2。需要设置变量：

export ALIBABA_CLOUD_ROLE_ARN="acs:ram::1672753017899339:role/tianchi-2025-role-2"

1.3 启动分析环境

cd notebook
jupyter notebook STS_Root_Cause_Analysis_Error.ipynb

2. 分析流程详解

2.1 环境配置

目标: 设置故障时间段和SLS访问参数

关键参数说明:

• FAULT_START_TIME/FAULT_END_TIME: 故障时间段，系统出现错误的时间范围
  
• PROJECT_NAME: SLS项目名，存储链路追踪数据的项目
  
• LOGSTORE_NAME: 日志库名，存储调用段数据的日志库
  
• REGION: 地域，SLS服务所在区域
  

操作步骤:

1. 根据故障情况修改FAULT_START_TIME和FAULT_END_TIME
   
2. 确保时间格式为"YYYY-MM-DD HH:MM:SS"
   
3. 验证环境变量配置正确性
   

输出示例:

FAULT_START_TIME = "2025-08-28 14:20:10"
FAULT_END_TIME = "2025-08-28 14:25:10"

2.2 筛选报错调用段

目标: 创建SLS客户端，找出故障时间段内的根因调用段

操作步骤:

1. 执行STS凭证获取，确保返回成功
   
2. 创建SLS客户端连接
   
3. 初始化FindRootCauseSpans分析器
   
4. 运行错误调用段筛选，获取错误调用段列表
   

查询输出示例:

--- 开始执行根因SPAN查找任务 ---
✅ 成功获取访问权限！
✅ SLS客户端已使用临时凭证创建。
[FindRootCauseSpans] 初始化完成。
  开始时间: 2025-08-28 14:20:10 (时间戳: 1756362010)
  结束时间: 2025-08-28 14:25:10 (时间戳: 1756362310)
开始查找根因spans...
proj-xtrace-a46b97cfdc1332238f714864c014a1b-cn-qingdao logstore-tracing cn-qingdao
[FindRootCauseSpans] 查询时间范围: 2025-08-28 14:20:10 ~ 2025-08-28 14:25:10. 查询条件: statusCode>1
总共查询到的span数量: 279
涉及的trace数量: 140
找到 140 个根因span:
1. 9a0e43619466da2b
2. 66d8bb155e71a468
3. ef74d4ca5a57236a
4. 9f56e3bd7373156d
5. 1128ce53854dbaf6
... 还有 135 个
✅ 查询条件已保存，包含 140 个spanId

结果验证: 140个错误调用段数量足够进行有效的模式分析（建议≥20个）

2.3 寻找报错特征 (get_patterns)

目标: 使用get_patterns算子分析错误调用段的共同特征

模式类型分析:

1. serviceName模式: 直接指向出错的服务

• 例如: "serviceName"='cart' → cart服务出错
  
• 这是最直接和可靠的证据
  

2. spanName模式: 指向出错的操作

• 例如: "spanName"='POST /oteldemo.CartService/GetCart' → cart服务的GetCart操作出错
  
• 需要从操作名推理出对应的服务
  

操作步骤:

1. 系统自动构建包含所有错误spanID的查询条件
   
2. 执行get_patterns查询分析错误特征
   
3. 解析查询结果，提取最频繁的错误模式
   
4. 按频率排序，识别主要错误特征
   

输出示例:

执行错误特征分析查询...
错误特征分析结果 (1 条记录):
ret: [["serviceName=cart","serviceName=frontend-proxy"],[139,1],null,null]
执行diff_patterns差异模式分析查询...
\n差异模式分析结果 (1 条记录):
ret: [["\"serviceName\"='cart'","\"serviceName\"='frontend-proxy'"],[139,1],[0,0],[0.9928571428571429,0.007142857142857143],[0.0,0.0],[0.9928571428571429,0.007142857142857143],[1.0,1.0],[0.0,0.0],null]
   ✅ get_patterns发现主要错误服务: cart (错误数: 139)
   ✅ diff_patterns确认异常服务: cart
   ✅ 多重证据确认: cart 是主要根因服务

2.4 交叉验证日志特征 (diff_patterns)

目标: 使用diff_patterns算子验证错误特征的区分性

操作步骤:

1. 执行diff_patterns交叉验证查询
   
2. 对比验证结果与get_patterns结果
   
3. 确认错误模式的区分性和可靠性
   

2.5 根因分析总结

目标: 综合所有证据，确定最终的根因服务和置信度

证据权重评估:

1. 错误span证据: 是否成功收集到足够数量的错误span
   
2. 模式分析证据: get_patterns是否识别出清晰的服务模式
   
3. 交叉验证证据: diff_patterns是否确认了模式的区分性
   
4. 服务识别证据: 是否成功从模式中提取出具体服务名
   

置信度评级标准:

• 高置信度:

• 错误span数量 ≥ 50
  
• 成功识别出serviceName模式
  
• diff_patterns验证通过
  
• 模式支持度 ≥ 0.3
  

• 中置信度:

• 错误span数量 20-50
  
• 从spanName模式推理出服务
  
• 模式支持度 0.1-0.3
  

• 低置信度:

• 错误span数量 < 20
  
• 无法明确识别服务
  
• 模式不够清晰
  

根因候选格式: 直接输出服务名 (如: cart, product-catalog, payment)

输出示例:

🔍 Step 5: Root Cause Analysis Summary
============================================================
📊 分析总结：
   异常时间段：2025-08-28 14:20:10 ~ 2025-08-28 14:25:10
   分析的SLS项目：proj-xtrace-a46b97cfdc1332238f714864c014a1b-cn-qingdao
   发现错误span数量：140
🎯 根因发现：
   ✅ 已找到 140 个错误span
   ✅ get_patterns发现主要错误服务: cart (错误数: 139)
   ✅ diff_patterns确认异常服务: cart
   ✅ 多重证据确认: cart 是主要根因服务
   ✅ 根据运行时证据确定目标服务: cart
🏆 根因候选：
   🎯 cart
   📈 置信度：高
   ✅ 证据：TRUE（已检测到异常）
   📝 支持证据：
      - 发现 140 个错误span
      - diff_patterns分析表明 cart 服务异常
      - 日志模式分析验证了服务问题
      - 错误特征分析确认了根因位置
💡 建议：
   - 检查 cart 服务的健康状态
   - 查看 cart 的错误日志和异常
   - 验证 cart 的部署和配置
   - 考虑重启或修复 cart 服务
============================================================
🎯 最终答复：cart
📈 置信度：高
🔍 证据：TRUE
============================================================

3. 可能出现报错的情况

如果在运行代码时报错如下：

大概率是系统的后台没有及时获取到选手的账号ID，这时候可以去比赛界面的【数据获取】入口重新上传账号ID。

4. 代码中的默认参数介绍

代码中涉及到的参数介绍：

• PROJECT_NAME：日志服务项目名称，默认为proj-xtrace-a46b97cfdc1332238f714864c014a1b-cn-qingdao
• LOGSTORE_NAME：日志库名称，默认为logstore-tracing
• REGION：地域，默认为cn-qingdao
• CMS_WORKSPACE：云监控工作区间，这是您进行宏观监控和发现异常的主要入口。默认为quanxi-tianchi-test
• CMS_ENDPOINT：云监控API接入地址，这是云监控服务的API终端地址，所有通过程序（如SDK、命令行工具）对云监控指标数据的请求，都需要发送到这个地址。默认为cms.cn-qingdao.aliyuncs.com

参考文档

• SPL语法文档
  
• 日志服务 SLS 文档
  
• 云监控 CloudMonitor 文档