OpenSkillIndex← back to search
claude-code

Learn-skills.dev sls-trace-analyzer

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

install
source · Clone the upstream repo
git clone https://github.com/NeverSight/learn-skills.dev
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/NeverSight/learn-skills.dev "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/skills-md/abcfed/claude-marketplace/sls-trace-analyzer" ~/.claude/skills/neversight-learn-skills-dev-sls-trace-analyzer && rm -rf "$T"
manifest: data/skills-md/abcfed/claude-marketplace/sls-trace-analyzer/SKILL.md
source content

SLS Trace Analyzer Skill

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

Usage

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

Parameters

  • 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）

LogStore 查询策略

默认行为：同时查询两个 logstore 以获取完整日志

  • 普通存储 (
    prod
    /
    test
    /
    dev
    ): 常规业务日志
  • 长期存储 (
    prod_longtime
    /
    test_longtime
    /
    dev_longtime
    ): 带 
    @LogReqAndRsp(longTimeLog = true)
    注解的接口请求/响应详情

为什么需要同时查询：

  • 普通存储包含 MQ 消息、网关日志等
  • 长期存储包含详细的请求入参和响应数据
  • 只查询单个 logstore 可能遗漏关键信息，导致问题分析不完整

URL 模式说明

当输入为 URL 时，skill 会自动：

  1. 从域名解析环境和地域
  2. 从 
    t
    参数提取时间戳
  3. 先查询 gateway access-log 获取 X-B3-TraceId
  4. 再用 traceId 查询详细日志

Configuration

Python 运行环境（按需自动初始化）

sls-query.py
、
requirements.txt
、
.venv/
均位于本 SKILL.md 同级目录。

调用规则：

  1. 直接用同目录下的 
    .venv/bin/python
    执行 
    sls-query.py
    ，无需前置检查
  2. 仅当执行失败（
    No such file or directory
    、
    ModuleNotFoundError
    ）时，在同目录下执行 
    python3 -m venv .venv && .venv/bin/pip install -q -r requirements.txt
    初始化后重试
  3. 不要使用系统 
    python3
    直接运行 
    sls-query.py
    ，否则缺少依赖

上海 Region (默认)

  • Endpoint: 
    cn-shanghai.log.aliyuncs.com
  • Project: 
    abc-cis-log
  • Credentials: loaded from 
    ~/.config/sls-query/credentials.json

杭州 Region

  • Endpoint: 
    cn-hangzhou.log.aliyuncs.com
  • Project: 
    abc-cis-log-hangzhou
  • Credentials: loaded from 
    ~/.config/sls-query/credentials.json

LogStore 命名规则

  • 开发环境: 
    dev
    或 
    dev_longtime
  • 测试环境: 
    test
    或 
    test_longtime
  • 生产环境: 
    prod
    或 
    prod_longtime

域名到环境映射

域名环境地域
dev.abczs.cn
devshanghai
test.abczs.cn
testshanghai
abcyun.cn
prodshanghai
region2.abcyun.cn
prodhangzhou

Instructions

当用户调用此 skill 时，按以下步骤执行：

Step 0: 判断输入类型（URL 或 TraceId）

首先判断用户输入是 URL 还是直接的 traceId：

if input.startswith('http://') or input.startswith('https://'):
    # URL 模式 - 执行 Step 0.1 ~ 0.3
    pass
else:
    # TraceId 模式 - 跳到 Step 1
    trace_id = input

Step 0.1: 解析 URL

from urllib.parse import urlparse, parse_qs

parsed = urlparse(url)
domain = parsed.netloc  # e.g., "dev.abczs.cn"
path = parsed.path      # e.g., "/api-weapp/pe/registration"
query = parsed.query    # e.g., "t=1769398080665" 或 "1769398080665"

# 提取时间戳（支持两种格式）
if '=' in query:
    params = parse_qs(query)
    timestamp = params.get('t', [None])[0]
else:
    timestamp = query  # 直接是时间戳

Step 0.2: 从域名解析环境和地域

DOMAIN_MAPPING = {
    "dev.abczs.cn": {"env": "dev", "region": "shanghai"},
    "test.abczs.cn": {"env": "test", "region": "shanghai"},
    "abcyun.cn": {"env": "prod", "region": "shanghai"},
    "region2.abcyun.cn": {"env": "prod", "region": "hangzhou"},
}
config = DOMAIN_MAPPING.get(domain, {"env": "prod", "region": "shanghai"})

Step 0.3: 查询 Gateway Access Log 获取 TraceId

使用时间戳和 path 查询 gateway 日志，提取 

X-B3-TraceId
：

.venv/bin/python sls-query.py \
  --mode access-log \
  --timestamp "<timestamp>" \
  --path "<path>" \
  --region "<region>" \
  --env "<env>"

【重要】Gateway 日志 Topic 说明

  • abc-cis-gateway-service
    : 业务请求 API 网关入口，用于查询 access-log 获取 TraceId
  • abc-invoke-gateway-service
    : 跨 region 调用网关入口，用于判断是否需要跨 region 查询

【查询技巧】

  1. 时间范围：默认查询时间戳前后 10 分钟（不是 30 秒，太窄容易漏掉）
  2. 路径匹配：使用路径的关键词而非完整路径，例如用 
    registration
    而非 
    /api-weapp/pe/registration
  3. 如果 access-log 模式查不到，可以直接用 gateway topic 查询： 
    # 备用查询方式：直接查 gateway 日志
query = '__topic__: abc-cis-gateway-service and <path关键词>'

从返回日志中提取 

X-B3-TraceId
字段，然后继续 Step 1。

Step 1: 解析参数并确定配置

从用户输入中解析 traceId 和可选参数，确定：

# 根据 region 选择配置
if region == "hangzhou":
    endpoint = "cn-hangzhou.log.aliyuncs.com"
    project = "abc-cis-log-hangzhou"
else:  # 默认上海
    endpoint = "cn-shanghai.log.aliyuncs.com"
    project = "abc-cis-log"

# 根据 env 和 longtime 确定 logstore
logstore = env  # dev/test/prod
if longtime:
    logstore = f"{env}_longtime"

# Credentials loaded from ~/.config/sls-query/credentials.json
# (or SLS_ACCESS_KEY_ID / SLS_ACCESS_KEY_SECRET env vars)

# 时间范围（默认最近 3 天）
from_time = from_date or (now - 3 days)
to_time = to_date or now

Step 2: 查询 SLS 日志

使用 Python 脚本查询日志：

.venv/bin/python sls-query.py \
  --trace-id "<traceId>" \
  --region "<region>" \
  --env "<env>" \
  --from "<from_time>" \
  --to "<to_time>"

如果使用 longtime logstore，添加 

--longtime
参数。

Step 2.5: 跨 Region 日志追踪

首次查询默认使用上海 region，需判断是否需要查询其他 region。

【判断逻辑】

  1. 先检查上海日志是否已包含完整错误信息

    • 如果已有目标服务（如 
      abc-his-xxx-service
      ）的 ERROR 日志和异常堆栈 → 无需跨 region 查询
    • 如果只有 
      abc-cis-monitor-service
      或 
      abc-cis-gateway-service
      的日志 → 继续下一步

  2. 检查 region 字段确定请求实际路由

    his-region1 / region1 → 上海 (已查询，无需再查)
his-region2 / region2 → 杭州 (需要查询)

  3. 需要跨 Region 查询的条件（同时满足）

    • 日志显示 
      region: his-region2
      或 
      region2
    • 上海日志中缺少目标服务的详细错误堆栈

【执行跨 Region 查询】

满足上述条件时，立即执行杭州查询（无需询问用户）：

.venv/bin/python sls-query.py \
  --trace-id "<traceId>" \
  --region "hangzhou" \
  --env "<env>"

【架构说明】

  • abc-cis-monitor-service
    全局只部署在上海，记录所有 region 的 HTTP 请求概要
  • 上海日志：monitor 层（请求/响应概要）
  • 杭州日志：业务服务详细日志、ERROR 堆栈

Step 3: 分析日志内容

拿到日志后，进行以下分析：

  1. 识别错误和异常

    • 查找 ERROR、WARN 级别的日志
    • 识别 Java 异常堆栈（Exception、Caused by）
    • 提取错误消息和错误码

  2. 追踪请求链路

    • 按时间排序日志条目
    • 识别请求入口（Controller）和出口
    • 标记 RPC/Feign 调用和响应
    • 识别数据库操作

  3. 提取关键信息

    • 请求 URL 和方法
    • 请求参数
    • 响应结果
    • 耗时信息
    • 服务调用链

Step 4: 定位代码问题

基于日志分析结果：

  1. 从 URL Path 定位服务

    • 从日志中提取请求的 URL path（如 
      /api/v2/healthlink/xxx
      ）
    • 查看 Config 工程中的 Gateway 路由配置：
      /Users/wxd/IdeaProjects/AbcCisConfig
    • 路由配置格式示例： 
      routes:
  - id: abc-cis-healthlink-service
    uri: http://abc-cis-healthlink-service
    predicates:
      - Path=/api/v2/healthlink/**

    • id
      字段即为服务名称
    • 根据服务名称在 
      ~/IdeaProjects/
      目录下找到对应的服务代码
    • 例如：
      /api/v2/healthlink/**
      对应服务 
      abc-cis-healthlink-service
      ，代码位于 
      ~/IdeaProjects/AbcCisHealthlinkService

  2. 【重要】确保代码分支与线上环境一致

    2.1 确定目标环境

    按以下优先级从多个来源提取环境信息：

    来源 A：用户输入的描述文本

    • 格式示例：
      【重要】[region1][灰度环境][primary]异常请求
    • 关键词映射：
      关键词环境
      灰度环境
      		gray
      预发布环境
      		pre
      正式环境
      		prod
      测试环境
      		test
      开发环境
      		dev

    来源 B：Gateway access-log 的 

    env
    字段

    • 从 
      __topic__: abc-cis-gateway-service
      的日志中提取 
      env
      字段
    • 示例：
      env: gray
      、
      env: pre
      、
      env: prod
      、
      env: dev
      、
      env: test

    来源 C：SLS 查询使用的 logstore 环境

    • 如果以上来源都没有，则根据 Step 1 中确定的 
      --env
      参数推断

    2.2 环境到分支映射

    环境 (env)Git 分支
    dev
    dev-joint
    test
    test-joint
    pre
    rc
    gray
    gray
    prod
    master

    2.3 分支使用策略（分场景）

    场景 A：当前工作目录已在目标服务工程内

    • 优先使用当前分支，直接在当前分支上查找代码、定位问题
    • 只有当在当前分支上找不到对应的类/方法，或者代码行号与堆栈不匹配时，才切换到环境对应的目标分支

    场景 B：当前工作目录不在目标服务工程内

    • 进入目标服务代码目录后，直接切换到环境对应的目标分支
    # 场景 B 或场景 A 回退时的切换流程：
cd ~/IdeaProjects/<ServiceProject>
git fetch origin <target_branch>
git checkout <target_branch>
git pull origin <target_branch>

    【注意事项】

    • 切换分支前先检查工作区是否干净（
      git status
      ），如有未提交的修改需要先 
      git stash
    • 如果目标分支不存在，回退使用 
      master
      分支
    • 对于依赖库（abc-cis-core、abc-cis-commons、abc-bis-rpc-sdk）不需要切换分支，只需在当前分支上 
      git pull
      拉取最新代码即可

  3. 从异常堆栈定位

    • 提取堆栈中的类名和行号
    • 优先关注 
      cn.abcyun
      包下的代码
    • 使用 codebase-retrieval 或 Grep 工具查找对应代码
    • 分析代码逻辑找出可能的问题原因

  4. 从错误消息定位

    • 搜索错误消息在代码中的位置
    • 分析错误抛出的条件
    • 追踪调用链

  5. 检查相关依赖代码

    • 如果涉及 abc-cis-core，查看 
      /Users/wxd/IdeaProjects/AbcCisCore
    • 如果涉及 abc-cis-commons，查看 
      /Users/wxd/IdeaProjects/AbcCisCommons
    • 如果涉及 abc-bis-rpc-sdk，查看 
      /Users/wxd/IdeaProjects/AbcBisRpcSDK

  6. 【重要】下游服务代码分析

    当日志显示错误来自 RPC/Feign 调用的下游服务时，必须查看下游服务的具体实现：

    • 识别下游服务: 从 FeignClient 类名识别目标服务

      FeignClient 类名对应服务代码位置
      AbcCisCrmFeignClient
      		CRM 服务
      ~/IdeaProjects/AbcCisCrmService
      AbcCisGoodsFeignClient
      		ScGoods 服务
      ~/IdeaProjects/AbcCisScGoodsService
      AbcCis{Xxx}FeignClient
      		对应 Xxx 服务
      ~/IdeaProjects/AbcCis{Xxx}Service

    • 定位接口实现:

      1. 从堆栈中找到 FeignClient 调用的方法名（如 
        tryLockingGoodsStockBatch
        ）
      2. 在 RPC SDK 中找到 FeignClient 接口定义：
        ~/IdeaProjects/AbcBisRpcSDK
      3. 根据 
        @PostMapping
        /
        @GetMapping
        注解找到 URL path
      4. 在下游服务中搜索对应的 Controller 和 Service 实现

    • 分析实现逻辑:

      1. 阅读 Controller 层代码，理解入参处理
      2. 阅读 Service 层代码，理解业务逻辑
      3. 特别关注：事务边界、锁机制、数据库操作顺序
      4. 对于死锁问题：分析 SQL 执行顺序和锁获取顺序

Step 4.5: 上下游日志综合分析（深度根因定位）

【关键】 仅看异常堆栈不足以定位根因，必须结合上下游日志和代码逻辑综合分析：

  1. 识别调用链中的所有服务

    • 从日志的 
      __topic__
      字段识别涉及的服务
    • 常见服务对应关系：
      topic服务名代码位置
      abc-cis-dispensing-service
      		发药服务
      ~/IdeaProjects/AbcCisDispensingService
      abc-cis-sc-goods-service
      		商品库存服务
      ~/IdeaProjects/AbcCisScGoodsService
      abc-cis-charge-service
      		收费服务
      ~/IdeaProjects/AbcCisChargeService
      abc-cis-crm-service
      		CRM服务
      ~/IdeaProjects/AbcCisCrmService

  2. 按服务分组分析日志

    • 将同一 TraceId 的日志按 
      __topic__
      分组
    • 每个服务单独分析其内部流程
    • 重点关注 ERROR 级别日志和异常堆栈

  3. 分析上游服务（调用方）

    • 查看调用参数是否正确
    • 检查调用时机和并发情况
    • 分析重试逻辑是否合理

  4. 分析下游服务（被调用方）

    • 必须阅读下游服务的代码实现
    • 查看接口入参处理逻辑
    • 分析业务处理流程
    • 检查事务和锁的使用方式

  5. 特定问题类型的深度分析

    死锁问题 (Deadlock):

    • 查看下游服务的 SQL 执行顺序
    • 分析是否存在锁顺序不一致
    • 检查事务范围是否过大
    • 查看是否有并发请求操作相同数据

    超时问题 (Timeout):

    • 分析各阶段耗时
    • 检查是否有慢 SQL
    • 查看是否有外部依赖阻塞

    空指针问题 (NullPointer):

    • 定位具体代码行
    • 分析数据来源
    • 检查上游传参是否完整

  6. 综合分析输出

    • 结合代码逻辑解释为什么会出现这个错误
    • 给出具体的代码修复位置和方案

Step 5: 输出分析报告

生成结构化的分析报告：

## 日志分析报告

### 基本信息
- TraceId: xxx
- 环境: prod/test/dev
- 地域: shanghai/hangzhou
- 时间范围: xxx ~ xxx
- 日志条目数: xxx
- 涉及服务: xxx, xxx

### 错误摘要
- 错误类型: xxx
- 错误消息: xxx
- 发生时间: xxx
- 发生服务: xxx

调用链路

1. [入口] POST /api/xxx → DispensingService
2. [Service] DispensingService.dispense()
3. [RPC] → ScGoodsService.lockingGoodsStock()
4. [DB] SQL 执行
5. [Error] Deadlock / NullPointer / Timeout

上下游日志分析

#### 上游服务 (xxx-service)
- 调用参数: ...
- 调用时间: ...
- 关键日志: ...

#### 下游服务 (xxx-service)
- 接收参数: ...
- 处理流程: ...
- 错误日志: ...
- 异常堆栈: ...

根因分析（重点）

#### 问题现象
简述观察到的错误现象

#### 代码分析
- **上游调用代码**: `文件路径:行号`
  ```java
  // 关键代码片段
  • 下游实现代码: 
    文件路径:行号
    // 关键代码片段

根本原因

结合代码逻辑，解释为什么会出现这个错误：

  1. xxx
  2. xxx

修复建议

  1. 具体修复方案
  2. 代码修改位置

## Examples

```bash
# 查询生产环境上海 region 的日志（默认最近 3 天）
/sls-trace abc123def456

# 查询测试环境的日志
/sls-trace abc123def456 --env test

# 查询杭州 region 生产环境的日志
/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"

# 查询 longtime logstore（历史日志）
/sls-trace abc123def456 --env prod --longtime

# 组合使用
/sls-trace abc123def456 --env test --region hangzhou --from 2025-01-20

# ========== URL 模式示例 ==========

# 通过 URL 自动查询（带 t= 参数）
/sls-trace https://dev.abczs.cn/api-weapp/pe/registration?t=1769398080665
# 自动解析: env=dev, region=shanghai, timestamp=1769398080665

# 通过 URL 自动查询（时间戳直接作为参数）
/sls-trace https://test.abczs.cn/api/v2/charge/sheets?1769398080665
# 自动解析: env=test, region=shanghai, timestamp=1769398080665

# 生产环境 URL
/sls-trace https://abcyun.cn/api/v2/crm/patients?t=1769398080665
# 自动解析: env=prod, region=shanghai

# 杭州 region 生产环境 URL
/sls-trace https://region2.abcyun.cn/api/v2/his/emr?t=1769398080665
# 自动解析: env=prod, region=hangzhou