SLS Trace Analyzer Skill

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

Usage

code

/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 会自动：

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

Configuration

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

python

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

python

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: 从域名解析环境和地域

python

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：

bash

.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 查询

【查询技巧】

•时间范围：默认查询时间戳前后 10 分钟（不是 30 秒，太窄容易漏掉）
•路径匹配：使用路径的关键词而非完整路径，例如用 registration 而非 /api-weapp/pe/registration

•如果 access-log 模式查不到，可以直接用 gateway topic 查询：

bash

# 备用查询方式：直接查 gateway 日志
query = '__topic__: abc-cis-gateway-service and <path关键词>'

从返回日志中提取 X-B3-TraceId 字段，然后继续 Step 1。

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

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

python

# 根据 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 脚本查询日志：

bash

.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。

【判断逻辑】

•
先检查上海日志是否已包含完整错误信息
- •如果已有目标服务（如 abc-his-xxx-service）的 ERROR 日志和异常堆栈 → 无需跨 region 查询
- •如果只有 abc-cis-monitor-service 或 abc-cis-gateway-service 的日志 → 继续下一步

•

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

code

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

•
需要跨 Region 查询的条件（同时满足）
- •日志显示 region: his-region2 或 region2
- •上海日志中缺少目标服务的详细错误堆栈

【执行跨 Region 查询】

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

bash

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

【架构说明】

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

Step 3: 分析日志内容

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

•
识别错误和异常
- •查找 ERROR、WARN 级别的日志
- •识别 Java 异常堆栈（Exception、Caused by）
- •提取错误消息和错误码
•
追踪请求链路
- •按时间排序日志条目
- •识别请求入口（Controller）和出口
- •标记 RPC/Feign 调用和响应
- •识别数据库操作
•
提取关键信息
- •请求 URL 和方法
- •请求参数
- •响应结果
- •耗时信息
- •服务调用链

Step 4: 定位代码问题

基于日志分析结果：

•
从 URL Path 定位服务
- •从日志中提取请求的 URL path（如 /api/v2/healthlink/xxx）
- •查看 Config 工程中的 Gateway 路由配置：/Users/wxd/IdeaProjects/AbcCisConfig
- •
  路由配置格式示例：
  yaml
  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.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：当前工作目录不在目标服务工程内
- •进入目标服务代码目录后，直接切换到环境对应的目标分支
bash
```
# 场景 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 拉取最新代码即可
•
从异常堆栈定位
- •提取堆栈中的类名和行号
- •优先关注 cn.abcyun 包下的代码
- •使用 codebase-retrieval 或 Grep 工具查找对应代码
- •分析代码逻辑找出可能的问题原因
•
从错误消息定位
- •搜索错误消息在代码中的位置
- •分析错误抛出的条件
- •追踪调用链
•
检查相关依赖代码
- •如果涉及 abc-cis-core，查看 /Users/wxd/IdeaProjects/AbcCisCore
- •如果涉及 abc-cis-commons，查看 /Users/wxd/IdeaProjects/AbcCisCommons
- •如果涉及 abc-bis-rpc-sdk，查看 /Users/wxd/IdeaProjects/AbcBisRpcSDK

•

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

当日志显示错误来自 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: 上下游日志综合分析（深度根因定位）

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

•

识别调用链中的所有服务

•从日志的 __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`

•
按服务分组分析日志
- •将同一 TraceId 的日志按 __topic__ 分组
- •每个服务单独分析其内部流程
- •重点关注 ERROR 级别日志和异常堆栈
•
分析上游服务（调用方）
- •查看调用参数是否正确
- •检查调用时机和并发情况
- •分析重试逻辑是否合理
•
分析下游服务（被调用方）
- •必须阅读下游服务的代码实现
- •查看接口入参处理逻辑
- •分析业务处理流程
- •检查事务和锁的使用方式
•
特定问题类型的深度分析

死锁问题 (Deadlock):
- •查看下游服务的 SQL 执行顺序
- •分析是否存在锁顺序不一致
- •检查事务范围是否过大
- •查看是否有并发请求操作相同数据
超时问题 (Timeout):
- •分析各阶段耗时
- •检查是否有慢 SQL
- •查看是否有外部依赖阻塞
空指针问题 (NullPointer):
- •定位具体代码行
- •分析数据来源
- •检查上游传参是否完整
•
综合分析输出
- •结合代码逻辑解释为什么会出现这个错误
- •给出具体的代码修复位置和方案

Step 5: 输出分析报告

生成结构化的分析报告：

markdown

## 日志分析报告

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

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

调用链路

markdown

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

上下游日志分析

markdown

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

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

根因分析（重点）

markdown

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

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

•
下游实现代码: 文件路径:行号
java
```
// 关键代码片段
```

根本原因

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

•xxx
•xxx

修复建议

•具体修复方案
•代码修改位置

code


## 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

关键词	环境
`灰度环境`	gray
`预发布环境`	pre
`正式环境`	prod
`测试环境`	test
`开发环境`	dev

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

SLS Trace Analyzer Skill

Usage

Parameters

LogStore 查询策略

URL 模式说明

Configuration

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

上海 Region (默认)

杭州 Region

LogStore 命名规则

域名到环境映射

Instructions

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

Step 0.1: 解析 URL

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

Step 0.3: 查询 Gateway Access Log 获取 TraceId

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

Step 2: 查询 SLS 日志

Step 2.5: 跨 Region 日志追踪

Step 3: 分析日志内容

Step 4: 定位代码问题

2.1 确定目标环境

2.2 环境到分支映射

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

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

Step 5: 输出分析报告

调用链路

上下游日志分析

根因分析（重点）

根本原因

修复建议