Queries Alibaba Cloud SLS logs by traceId or timestamped URL, fetches from regular and longtime logstores across envs/regions, analyzes to pinpoint code issues.
From abc-development-pluginnpx claudepluginhub abcfed/claude-marketplace --plugin abc-development-pluginThis skill uses the workspace's default tool permissions.
credentials.json.bakrequirements.txtsls-query.pySearches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Guides implementation of event-driven hooks in Claude Code plugins using prompt-based validation and bash commands for PreToolUse, Stop, and session events.
根据 traceId 或 URL(带时间戳)查询阿里云日志服务 (SLS) 获取日志,分析日志内容,定位代码中的问题。
/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)默认行为:同时查询两个 logstore 以获取完整日志
prod/test/dev): 常规业务日志prod_longtime/test_longtime/dev_longtime): 带 @LogReqAndRsp(longTimeLog = true) 注解的接口请求/响应详情为什么需要同时查询:
当输入为 URL 时,skill 会自动:
t 参数提取时间戳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,否则缺少依赖cn-shanghai.log.aliyuncs.comabc-cis-log~/.config/sls-query/credentials.jsoncn-hangzhou.log.aliyuncs.comabc-cis-log-hangzhou~/.config/sls-query/credentials.jsondev 或 dev_longtimetest 或 test_longtimeprod 或 prod_longtime| 域名 | 环境 | 地域 |
|---|---|---|
dev.abczs.cn | dev | shanghai |
test.abczs.cn | test | shanghai |
abcyun.cn | prod | shanghai |
region2.abcyun.cn | prod | hangzhou |
当用户调用此 skill 时,按以下步骤执行:
首先判断用户输入是 URL 还是直接的 traceId:
if input.startswith('http://') or input.startswith('https://'):
# URL 模式 - 执行 Step 0.1 ~ 0.3
pass
else:
# TraceId 模式 - 跳到 Step 1
trace_id = input
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 # 直接是时间戳
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"})
使用时间戳和 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 获取 TraceIdabc-invoke-gateway-service: 跨 region 调用网关入口,用于判断是否需要跨 region 查询【查询技巧】
registration 而非 /api-weapp/pe/registration# 备用查询方式:直接查 gateway 日志
query = '__topic__: abc-cis-gateway-service and <path关键词>'
从返回日志中提取 X-B3-TraceId 字段,然后继续 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
使用 Python 脚本查询日志:
.venv/bin/python sls-query.py \
--trace-id "<traceId>" \
--region "<region>" \
--env "<env>" \
--from "<from_time>" \
--to "<to_time>"
如果使用 longtime logstore,添加 --longtime 参数。
首次查询默认使用上海 region,需判断是否需要查询其他 region。
【判断逻辑】
先检查上海日志是否已包含完整错误信息
abc-his-xxx-service)的 ERROR 日志和异常堆栈 → 无需跨 region 查询abc-cis-monitor-service 或 abc-cis-gateway-service 的日志 → 继续下一步检查 region 字段确定请求实际路由
his-region1 / region1 → 上海 (已查询,无需再查)
his-region2 / region2 → 杭州 (需要查询)
需要跨 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 请求概要拿到日志后,进行以下分析:
识别错误和异常
追踪请求链路
提取关键信息
基于日志分析结果:
从 URL Path 定位服务
/api/v2/healthlink/xxx)/Users/wxd/IdeaProjects/AbcCisConfigroutes:
- 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【重要】确保代码分支与线上环境一致
按以下优先级从多个来源提取环境信息:
来源 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 环境
--env 参数推断| 环境 (env) | Git 分支 |
|---|---|
| dev | dev-joint |
| test | test-joint |
| pre | rc |
| gray | gray |
| prod | master |
场景 A:当前工作目录已在目标服务工程内
场景 B:当前工作目录不在目标服务工程内
# 场景 B 或场景 A 回退时的切换流程:
cd ~/IdeaProjects/<ServiceProject>
git fetch origin <target_branch>
git checkout <target_branch>
git pull origin <target_branch>
【注意事项】
git status),如有未提交的修改需要先 git stashmaster 分支git pull 拉取最新代码即可从异常堆栈定位
cn.abcyun 包下的代码从错误消息定位
检查相关依赖代码
/Users/wxd/IdeaProjects/AbcCisCore/Users/wxd/IdeaProjects/AbcCisCommons/Users/wxd/IdeaProjects/AbcBisRpcSDK【重要】下游服务代码分析
当日志显示错误来自 RPC/Feign 调用的下游服务时,必须查看下游服务的具体实现:
识别下游服务: 从 FeignClient 类名识别目标服务
| FeignClient 类名 | 对应服务 | 代码位置 |
|---|---|---|
AbcCisCrmFeignClient | CRM 服务 | ~/IdeaProjects/AbcCisCrmService |
AbcCisGoodsFeignClient | ScGoods 服务 | ~/IdeaProjects/AbcCisScGoodsService |
AbcCis{Xxx}FeignClient | 对应 Xxx 服务 | ~/IdeaProjects/AbcCis{Xxx}Service |
定位接口实现:
tryLockingGoodsStockBatch)~/IdeaProjects/AbcBisRpcSDK@PostMapping/@GetMapping 注解找到 URL path分析实现逻辑:
【关键】 仅看异常堆栈不足以定位根因,必须结合上下游日志和代码逻辑综合分析:
识别调用链中的所有服务
__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 |
按服务分组分析日志
__topic__ 分组分析上游服务(调用方)
分析下游服务(被调用方)
特定问题类型的深度分析
死锁问题 (Deadlock):
超时问题 (Timeout):
空指针问题 (NullPointer):
综合分析输出
生成结构化的分析报告:
## 日志分析报告
### 基本信息
- 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
// 关键代码片段
文件路径:行号
// 关键代码片段
结合代码逻辑,解释为什么会出现这个错误:
## 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