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	dev	shanghai
test.abczs.cn	test	shanghai
abcyun.cn	prod	shanghai
region2.abcyun.cn	prod	hangzhou

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