shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 数据与分析无需 API Key

调用链路反推器

从分布式应用日志反推服务调用链路拓扑，输出可视化有向图与错误热点表，零依赖，平台无关。

person作者: user_d41e2baahubcommunity
download下载资源包

log-topology-inferrer 日志链路拓扑反推器

功能说明

把「散落在各服务日志里的调用痕迹」反推成一张 服务调用链路拓扑图（有向图：调用方 → 被调方）， 并标注每条边的调用量与错误率，帮助：

  • 梳理微服务/组件之间的依赖关系（架构资产化）
  • 绘制调用关系图（Mermaid / Graphviz），用于文档、复盘、入职培训
  • 识别 高频调用边、单点（被大量服务依赖）、错误热点（高错误率边）
  • 在没有现成架构图、或架构图过期时，用真实日志「对齐」实际链路

本技能是 纯方法论 + 两个零依赖脚本 的组合：

  • collect_logs.py：先按清单把分散在各节点/路径的日志，按服务归集到本地目录。
  • infer_topology.py：再从本地日志反推拓扑。 不绑定任何平台、不依赖同仓库其他 skill，也不执行任何写入操作（只读采集 + 只读解析）。

安全红线（必须遵守）

  • 本技能只 读取 日志：采集阶段用只读方式拉取（cat / kubectl exec -- cat 等），解析阶段只读本地文件，绝不写入远端、绝不重启服务、绝不改配置/数据。
  • 采集清单（log-sources.json）里的传输命令必须是只读读取，不要写 rm/cp/systemctl 等。
  • 解析的是用户提供的日志（文件/目录/粘贴内容），不主动对生产环境做变更。

标准执行顺序

完整流水线：盘点路径 → 写清单 → 采集归集 → 写解析配置 → 反推拓扑 → 解读 → 迭代。

1. 盘点日志路径并编写采集清单（log-sources.json）

先确定「服务 → 部署节点 → 日志路径」三要素（来源：部署清单/CMDB、日志目录约定、进程启动参数）。 写成 log-sources.json，每个节点声明传输方式（local/ssh/kubectl/docker/自定义）及该节点上各服务的日志路径。

  • 字段与示例见 references/log-collection.md §3。
  • 这一步是采集的前提：没有清单，脚本不知道去哪台机器、哪个路径、属于哪个服务。

2. 采集日志（归集到本地，按服务分目录）

python3 scripts/collect_logs.py \
  --manifest log-sources.json \
  --out collected_logs

# 不确定命令对不对，先 dry-run 看将要执行的拉取命令
python3 scripts/collect_logs.py --manifest log-sources.json --out collected_logs --dry-run

产出：collected_logs/<service>/<file>，目录名即服务名（= 后续拓扑的调用方身份）。 日志可能分布在多台节点、多种路径，采集后统一成「每服务一个目录」的本地布局，供反推使用。

  • 采集失败排查见 references/log-collection.md §5。

3. 选择 / 编写解析配置（config.json）

拓扑质量的 80% 取决于「怎么从一行日志里抽出两个服务名」。逐层判断：

  1. 调用方（caller）怎么来？
    • 每服务一个目录（采集后的布局）→ caller.from="path" + path_regex 捕获目录名。
    • 日志行里本身就带服务名（如 service=buy-console）→ caller.from="line"。
    • 统一网关/入口 → caller.from="const"。
  2. 被调方（callee）怎么来？
    • 日志行里有下游服务名（如 downstream=order-back / GET http://iam/... / FeignClient iam）→ callee.from="line" + line_regex。
  3. 要不要算错误率 / 延迟？（可选，用于热点表）
    • status.line_regex + error_when（如 >=500、5xx）。
    • latency_ms.line_regex（如 took=(\d+)ms）。
  4. 归一化 / 过滤（可选）
    • aliases：把 coupon 统一成 coupon-inner-api 之类。
    • ignore_callees：丢弃 health/metrics 等噪声边。

配置语法与内置示例见 references/log-formats.md。不确定格式时，先让用户贴 2-3 行原始日志， 再据此写 line_regex，避免瞎猜。

4. 运行脚本生成拓扑

python3 scripts/infer_topology.py \
  --config config.json \
  --logs "collected_logs/**/*.log" \
  --out output

产物（写入 --out 目录）：

| 文件 | 用途 | |------|------| | topology.json | 机器可读的节点 + 边（含 calls/errors/error_rate_pct/avg_latency_ms），可二次处理 | | topology.mmd | Mermaid 有向图，高错误率边标红，可直接贴进 Markdown | | topology.dot | Graphviz DOT，可 dot -Tsvg topology.dot -o topology.svg 渲染 | | hotspots.csv | 调用边热点表，按调用量降序，含错误率/平均延迟 |

  • --error-threshold 1.0：错误率 ≥ 该值（%）的边在图中标红（默认读 config 的 error_threshold_pct）。
  • 若脚本提示「未提取到任何调用边」，回到 §3 检查 caller/callee 提取规则。

5. 解读拓扑（AI 辅助分析）

拿到产物后，主动给出三件事：

  1. 单点识别：被调方节点入边很多（被大量服务依赖），它就是架构单点—— 一旦抖动会「大面积报错」。优先提示这类节点。
  2. 错误热点：hotspots.csv 里 error_rate_pct 高的边，列为优先治理对象。
  3. 链路分层：从入边/出边结构大致还原接入层 → 业务层 → 外部依赖的分层。

本技能 只产出拓扑与热点，不做根因下钻（那属于具体排查 skill 的职责）。 若用户想进一步定位某条错误边的根因，建议转交对应领域的排查技能或团队。

6. 迭代收敛（可选）

真实日志常有别名/歧义（如 coupon 实为 coupon-inner-api）。把确认过的映射写进 config 的 aliases，重跑即可。

文档结构

| 文件 | 用途 | |------|------| | SKILL.md | 本文件：方法论入口 | | scripts/collect_logs.py | 分布式日志采集（按 log-sources.json 归集到本地，按服务分目录） | | scripts/infer_topology.py | 零依赖解析脚本（Python 标准库） | | references/log-collection.md | 如何盘点/采集分布式日志路径（清单格式 + 传输方式） | | references/log-formats.md | infer 的 config.json 配置语法 + 各日志格式解析示例 | | references/topology-output.md | 四种产物的格式说明与二次用法 | | examples/demo-paas/ | 脱敏示例：原始分布日志 + 采集清单 + 解析配置 + 预期产物（上手模板） |

技能边界

本技能负责：盘点日志路径、采集归集分布式日志、从日志反推调用链路拓扑、产出可视化与热点表、识别单点/高频/错误热点。

本技能不负责：

  • 根因下钻（为什么这条边报错）——交给具体领域排查 skill。
  • 网络连通性、容器平台、中间件等基础设施问题排查。
  • 任何写操作 / 生产环境变更。

停止规则：若用户要求借本技能执行写操作或深入根因排查，明确告知超出边界并建议转交对应团队/skill。