链路追踪/性能分析

Pod 状态和 Kubernetes 事件解释不了问题时，有三个工具可以往下查：组件日志能看到 TensorFusion 注入的库在工作负载内部做了什么；hypervisor 的 API 和终端界面能看到单个节点上的设备、worker 和限额；NVIDIA Nsight Compute 用来分析 CUDA kernel 本身的性能。常见现象请先查问题处理手册，手册让你看日志或 hypervisor 时再来这里。

打开工作负载里的 TensorFusion 日志

TensorFusion 注入到工作负载里的库以及 worker，默认不输出日志。由三个环境变量控制：

1. 给工作负载里使用 GPU 的容器加上这些变量，等 Pod 重启：

   env:
     - name: TF_ENABLE_LOG
       value: "1"
     - name: TF_LOG_LEVEL
       value: "debug"

   远程 GPU 工作负载的 GPU 调用发生在 worker Pod 里，要把同样的变量加到 worker 容器上，位置是资源池的 componentConfig.worker.podTemplate。Helm chart 创建的集群已经在那里设置了 TF_ENABLE_LOG=1。

2. 查看输出：

   kubectl logs <pod> -n <namespace> -c <container>

   一行日志的格式如下：

   [2026-01-01 12:00:00.000] [147] [152] [TF] Error Func:Consume Line:80 call api=cuMemAddressReserve failed

   各字段依次是时间、进程 ID、线程 ID、级别、源码中的函数和行号，最后是日志内容。

3. 排查结束后去掉这些变量。debug 和 trace 级别日志量很大，会拖慢工作负载。

注入的库遇到致命错误时，即使没有打开日志，也会往 stderr 输出一行以 [TF panic] 开头的信息。

打开 hypervisor 的 vector sidecar 之后，带 tensor-fusion.ai/component=hypervisor 或 worker 标签的 Pod 的日志还会存进 tf_system_log 表，见查询指标和日志。

查看节点上的 hypervisor

每个 GPU 节点上有一个名为 hypervisor-<node> 的 hypervisor Pod。它在 8001 端口提供 HTTP API，资源池设置了 componentConfig.hypervisor.portNumber 时以该值为准。先把端口转发到本机：

kubectl -n tensor-fusion-sys port-forward pod/hypervisor-<node> 8001:8001

用 curl

curl -s http://localhost:8001/healthz
curl -s http://localhost:8001/api/v1/devices
curl -s http://localhost:8001/api/v1/workers

/api/v1/devices 列出 hypervisor 在这个节点上发现的 GPU，/api/v1/workers 列出它正在管理的 worker 及其分配情况。设备列表为空说明设备发现失败，见没有发现 GPU。

用终端界面

终端界面展示的是同一份数据，但会实时刷新，并带用量曲线。它是一个独立的二进制，不在 hypervisor 镜像里，需要从源码编译，本机要有 Go 环境：

git clone https://github.com/NexusGPU/tensor-fusion.git
cd tensor-fusion
make build-hypervisor-tui
./bin/hypervisor-tui -host localhost -port 8001

用 Nsight Compute 分析 CUDA kernel

想知道应用内部的 GPU 时间花在哪里，用 NVIDIA Nsight Compute（ncu）。它随 CUDA Toolkit 提供，不是 TensorFusion 的一部分。

建议在 tensor-fusion.ai/isolation: shared 的 Pod 里做分析。这种模式下 TensorFusion 分配整张 GPU，不往容器里注入任何东西，分析结果里只有应用自身。

ncu --config-file off \
    --export profile-$(date +%Y%m%d-%H%M%S) \
    --call-stack \
    --force-overwrite \
    python3 main.py

运行结束后会生成一个 .ncu-rep 报告文件，用 Nsight Compute 的界面打开。

下一步

• 问题处理手册：按现象排查问题。
• 查询指标和日志：查看历史用量和组件日志。