SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场sls-trace-analyzer

sls-trace-analyzer

部署与运维

查看项目

更新于 10-15 12:13

技能介绍

用途

SLS Trace Analyzer 用于根据 traceId 或带时间戳的 URL 查询阿里云日志服务（SLS）获取日志，分析日志内容，定位代码中的问题。

主要能力

  • 支持两种输入：直接传入 traceId，或传入带时间戳的 URL。
  • URL 模式下自动解析域名得到环境与地域，从 t 参数提取时间戳，先查询 gateway access-log 获取 X-B3-TraceId，再用该 traceId 查询详细日志。
  • 支持指定环境（dev/test/prod）、地域（shanghai/hangzhou）、时间范围（--from/--to）。
  • 默认同时查询普通 logstore 与 longtime logstore：普通存储包含 MQ 消息、网关日志等常规业务日志；长期存储包含带 @LogReqAndRsp(longTimeLog = true) 注解的接口请求/响应详情。
  • 支持跨 Region 日志追踪：当上海日志缺少目标服务详细错误堆栈且日志显示 region 为 his-region2/region2 时，自动执行杭州查询。
  • 分析日志内容：识别 ERROR/WARN 级别日志、Java 异常堆栈（Exception、Caused by）、错误消息与错误码；按时间排序追踪请求链路；提取请求 URL、方法、参数、响应结果、耗时与服务调用链。
  • 定位代码问题：从 URL Path 结合 Gateway 路由配置定位服务，按环境映射 Git 分支，从异常堆栈或错误消息定位代码，并分析下游服务实现。
  • 输出结构化分析报告，包含基本信息、错误摘要、调用链路、上下游日志分析、根因分析与修复建议。

使用方式

命令格式：

/sls-trace <traceId | URL> [--env <environment>] [--region <region>] [--from <date>] [--to <date>]

参数说明：

  • traceId：要查询的 traceId，或带时间戳的 URL（如 https://dev.abczs.cn/api-weapp/pe/registration?t=1769398080665）。
  • --env：可选，环境名称：dev/test/prod（默认 prod，URL 模式下自动从域名解析）。
  • --region：可选，地域：shanghai/hangzhou（默认 shanghai，URL 模式下自动从域名解析）。
  • --from：可选，开始日期，格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss（默认 3 天前）。
  • --to：可选，结束日期，格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss（默认当前时间）。
  • --longtime：可选，仅查询 longtime logstore（默认同时查询普通和 longtime 两个 logstore）。

示例：

/sls-trace abc123def456
/sls-trace abc123def456 --env test
/sls-trace abc123def456 --region hangzhou
/sls-trace abc123def456 --from 2025-01-20 --to 2025-01-24
/sls-trace abc123def456 --from "2025-01-20 10:00:00" --to "2025-01-20 12:00:00"
/sls-trace abc123def456 --env prod --longtime
/sls-trace abc123def456 --env test --region hangzhou --from 2025-01-20
/sls-trace https://dev.abczs.cn/api-weapp/pe/registration?t=1769398080665
/sls-trace https://test.abczs.cn/api/v2/charge/sheets?1769398080665
/sls-trace https://abcyun.cn/api/v2/crm/patients?t=1769398080665
/sls-trace https://region2.abcyun.cn/api/v2/his/emr?t=1769398080665

配置与运行环境

  • Python 运行环境按需自动初始化。sls-query.py、requirements.txt、.venv/ 均位于 SKILL.md 同级目录。
  • 调用规则：直接用同目录下的 .venv/bin/python 执行 sls-query.py，无需前置检查；仅当执行失败（No such file or directory、ModuleNotFoundError）时，在同目录下执行 python3 -m venv .venv && .venv/bin/pip install -q -r requirements.txt 初始化后重试。不要使用系统 python3 直接运行 sls-query.py，否则缺少依赖。
  • 上海 Region（默认）：Endpoint 为 cn-shanghai.log.aliyuncs.com，Project 为 abc-cis-log。
  • 杭州 Region：Endpoint 为 cn-hangzhou.log.aliyuncs.com，Project 为 abc-cis-log-hangzhou。
  • 凭证从 ~/.config/sls-query/credentials.json 加载（或使用 SLS_ACCESS_KEY_ID / SLS_ACCESS_KEY_SECRET 环境变量）。
  • LogStore 命名规则：开发环境 dev 或 dev_longtime；测试环境 test 或 test_longtime；生产环境 prod 或 prod_longtime。
  • 域名到环境映射：dev.abczs.cn → dev/shanghai；test.abczs.cn → test/shanghai；abcyun.cn → prod/shanghai；region2.abcyun.cn → prod/hangzhou。

执行流程

  1. 判断输入类型（URL 或 TraceId）。
  2. URL 模式：解析 URL，从域名解析环境和地域，查询 Gateway Access Log 获取 TraceId。
  3. 解析参数并确定配置（endpoint、project、logstore、时间范围）。
  4. 查询 SLS 日志。
  5. 跨 Region 日志追踪（按条件自动执行杭州查询）。
  6. 分析日志内容（识别错误与异常、追踪请求链路、识别数据库操作、提取关键信息）。
  7. 定位代码问题（从 URL Path 定位服务、确保代码分支与线上环境一致、从异常堆栈或错误消息定位、分析下游服务代码）。
  8. 上下游日志综合分析（深度根因定位）。
  9. 输出分析报告。

适用场景

  • 线上问题排查：根据 traceId 或 URL 快速拉取日志并定位错误。
  • 跨 Region 问题追踪：结合上海与杭州日志定位业务服务详细错误堆栈。
  • 结合代码的根因分析：从异常堆栈、错误消息、上下游日志与代码逻辑综合分析死锁、超时、空指针等问题。

限制

  • 依赖阿里云日志服务（SLS）及对应 Project、LogStore 与凭证配置。
  • 需要本地存在对应服务代码工程（如 ~/IdeaProjects/ 下的服务）才能进行代码定位与分支切换。
  • 环境到分支映射：dev→dev-joint；test→test-joint；pre→rc；gray→gray；prod→master。
  • 依赖库（abc-cis-core、abc-cis-commons、abc-bis-rpc-sdk）不需要切换分支，只需在当前分支上 git pull 拉取最新代码。
  • 其他未在资料中说明的功能、收费、价格、平台或效果暂未提供。