log-diagnosis-pd-link-establishment

name: log-diagnosis-pd-link-establishment description: PD实例建链失败的日志诊断。当P节点与D节点之间的KVCache链路建立失败、卡住或反复重试时，通过日志定位根因。触发词：建链失败、建链卡住、link failed、建链超时、Link exception、内存注册失败、PD链路异常。 parent: log-diagnosis-framework

PD实例建链问题日志诊断

问题描述

PD实例建链是指Prefill(P)节点与Decode(D)节点之间建立KVCache传输链路的过程。建链由RouterImpl发起，经Config模块配置，由SeparateDeploymentWorker执行，底层调用LLMDataDist完成。

涉及仓库/组件：

• mindie-llm/RouterImpl: 建链流程编排（销毁旧链→创建新链→状态轮询）
• mindie-llm/SeparateDeploymentWorker: 建链执行（窗口线程+内存注册轮询）
• mindie-llm/SeparateDeploymentEngine: 底层LLMDataDist调用
• mindie-llm/Config: PD链路配置下发
• mindie-server: 角色设置与链路状态汇总

典型异常表现：

• 角色设置后长时间不进入READY状态
• query_link_status显示failed_links>0
• 建链卡在running状态不推进
• 推理请求报Pull KV失败

关联问题：建链是缩P保D的下游环节，缩P保D流程中新D实例加入后需要建链。如果是缩P保D场景触发的建链失败，先查 log-diagnosis-shrink-p-reserve-d。

诊断入口日志

确认问题类型：如果入口日志命中，说明建链阶段出问题，继续诊断。

诊断决策树

[入口] 建链相关错误日志出现
│
├── 阶段A: 配置与角色设置
│   ├── 有 "start to set PD link/unlink info" → 配置下发正常 ✓
│   │   ├── 有 "PD switch is True" → PD开关开启 ✓ → 继续建链流程
│   │   ├── 有 "PD switch is False" → PD开关关闭 → 检查是否本就应该关闭
│   │   └── 有 "Do not need to link and unlink" → 无需建链 → 确认角色和配置
│   └── 无配置下发日志 → 配置阶段异常 ✗ → 故障A1: 配置未下发
│
├── 阶段B: 解链（旧链路清理）
│   ├── 有 "Destroy all clusters kvcache link start" → 开始解链 ✓
│   │   ├── 有 "Destroy all clusters kvcache link finish" → 解链完成 ✓ → 继续建链
│   │   ├── 有 "Batch unlink results" 含失败项 → 批量解链部分失败 → 故障B1: 解链部分失败
│   │   └── 有 "process DMI unlink failed" → DMI解链失败 ✗ → 故障B2: DMI解链失败
│   └── 无解链日志 → 跳过解链（可能无旧链路）→ 继续建链
│
├── 阶段C: 底层建链调用
│   ├── 有 "Link succeeded with status: SUCCESS" → 建链成功 ✓ → 继续内存注册
│   ├── 有 "Link failed, error code is" → 建链失败 ✗ → 故障C1: 底层建链返回错误码
│   ├── 有 "Link exception from" → 建链异常 ✗ → 故障C2: 建链网络异常
│   ├── 有 "Link already exists" → 链路已存在 → 故障C3: 重复建链
│   └── 无任何Link结果日志 → 建链未执行 ✗ → 故障C4: 建链未触发
│
├── 阶段D: 内存注册轮询
│   ├── 有 "Query completed in" → 内存注册成功 ✓ → 继续状态确认
│   ├── 有 "Mem status query failed" → 内存注册失败 ✗ → 故障D1: 内存注册失败
│   ├── 有 "Max query attempts reached" → 轮询超限 → 故障D2: 内存注册超时
│   └── 有 "Querying mem status" 但无完成/失败 → 卡在轮询 ✗ → 故障D3: 内存注册卡住
│
├── 阶段E: 状态确认
│   ├── 有 "add_to_success" → 建链成功 ✓ → 继续角色就绪
│   ├── 有 "add_to_failed" → 建链失败 → 回查阶段C/D
│   ├── 有 "query link status result" 含waitting/running → 链路未完成 → 回查卡在哪
│   └── 有 "query link status failed" → 查询接口异常 ✗ → 故障E1: 状态查询失败
│
└── 阶段F: 角色就绪
    ├── 有 "Setting role status to READY" → 建链全部完成 ✓ → 诊断结束
    ├── 有 "Processing link status" 但无READY → 有链路未完成 → 回查
    └── 无 "Processing link status" → 状态轮询未启动 ✗ → 故障F1: 状态轮询未启动

分阶段诊断流程

阶段A：配置与角色设置

阶段B：解链（旧链路清理）

阶段C：底层建链调用

阶段D：内存注册轮询

阶段E：状态确认

阶段F：角色就绪

快速诊断表

故障清单详解

故障A1: 配置未下发

现象：无"start to set PD link/unlink info" 根因：postRole请求未到达Config模块，或Config模块未解析 排查：

1. grep "enter process pdRole" $LOG_DIR/*.log — 确认pdRole入口是否到达
2. grep "POST /v2/role" $LOG_DIR/*.log — 确认HTTP请求是否到达
3. 检查mindie-llm进程是否正常运行

故障C1: 底层建链返回错误码

现象：Link failed, error code is {code} 根因：LLMDataDist底层建链失败，具体原因看错误码 排查：

1. 记录error code，查阅LLMDataDist错误码表
2. 检查rank_table配置：cat /path/to/rank_table.json
3. 检查cluster_rank_info参数是否与实际拓扑一致
4. 检查对端节点：ps aux | grep mindie，npu-smi info
5. 检查/etc/hosts中IP映射是否正确
6. 检查LLMDataDist日志：/var/log/llmdatadist/*.log

故障C2: 建链网络异常

现象：Link exception from {local_ip} to {remote_ip}: {exception} 根因：网络连接中断、超时或RDMA异常 排查：

1. 确认异常IP对：local_ip → remote_ip
2. 检查网络连通性：ping {remote_ip}、traceroute {remote_ip}
3. 检查RDMA状态：ibv_devinfo、rdma link show
4. 检查防火墙：iptables -L -n
5. 检查网络带宽：iperf3 -c {remote_ip}
6. 检查系统日志：dmesg | grep -i network

故障C3: 重复建链

现象：Link already exists with status: ALREADY_LINK 根因：链路已存在，可能是上次建链未解链 排查：

1. 检查是否有对应的解链操作
2. 确认是否需要先解链再建链
3. 检查cluster_comm_map中是否已有该链路记录

故障C4: 建链未触发

现象：有"Create all clusters kvcache links start"但无Link相关日志 根因：SeparateDeploymentWorker未执行建链，或队列未处理 排查：

1. 检查add_to_waitting是否有记录
2. 检查_fill_window_worker线程是否存活
3. 检查link_queue是否有积压

故障D1: 内存注册失败

现象：Mem status query failed for {remote_ip}, no retry. 根因：对端NPU内存状态异常，无法完成内存注册 排查：

1. 登录对端节点：npu-smi info
2. 检查NPU内存使用：npu-smi det -t usages -i 0
3. 检查是否有OOM：dmesg | grep "Out of memory"
4. 检查NPU驱动状态：cat /proc/driver/npu/info
5. 检查内存注册日志：dmesg | grep -i "memory\|register"

故障D2: 内存注册超时

现象：Max query attempts reached for {remote_ip}, requeueing 根因：对端响应慢，内存注册未在预期时间内完成 排查：

1. 检查对端节点负载：top、iostat -x 1
2. 检查网络延迟：ping -c 10 {remote_ip}
3. 检查kv_link_timeout配置是否合理
4. 检查内存注册进度：grep "Querying mem status" $LOG_DIR/*.log

故障D3: 内存注册卡住

现象：有"Querying mem status"持续输出但无完成/失败 根因：_process_window_worker卡在轮询循环 排查：

1. 统计"Querying mem status"出现次数
2. 检查是否一直返回PENDING状态
3. 检查_process_window_worker线程状态

故障E1: 状态查询失败

现象：query link status failed 根因：QueryPDLinkStatus接口异常 排查：

1. grep "QueryPDLinkStatus" $LOG_DIR/*.log — 检查查询接口
2. 检查LLMManager状态
3. 检查底层资源：lsof | grep mindie

故障F1: 状态轮询未启动

现象：建链成功后无"Processing link status"汇总 根因：RouterImpl的定时查询未启动 排查：

1. grep "global rank.*enter query link status" $LOG_DIR/*.log
2. 检查RouterImpl是否正常运行
3. 检查10秒定时查询是否被启动

常用检查命令汇总

# 变量设置
LOG_DIR=/var/log/mindie    # 根据实际环境修改

# 1. 建链整体状态
grep -E "Link (succeeded|failed|exception|already exists)|add_to_(success|failed|running|waitting)" $LOG_DIR/*.log

# 2. 内存注册状态
grep -E "Querying mem status|Query completed|Mem status query failed|Max query attempts" $LOG_DIR/*.log

# 3. 链路状态查询
grep -E "query link status|Processing link status|QueryPDLinkStatus" $LOG_DIR/*.log

# 4. 解链状态
grep -E "Destroy all clusters|Batch (destroy|unlink)|process DMI unlink" $LOG_DIR/*.log

# 5. PD配置
grep -E "PD (switch|remote|link/unlink)|start to set PD" $LOG_DIR/*.log

# 6. 角色就绪
grep -E "Setting role status to READY|Engine started and ready" $LOG_DIR/*.log

# 7. 快速统计建链成功/失败数
grep -c "add_to_success" $LOG_DIR/*.log
grep -c "add_to_failed" $LOG_DIR/*.log

关联问题