> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuneplane.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 原生日志与遥测网关

> 部署独立 Rust 采集器、经过认证的 gRPC 接收服务及本地持久化交付。

Rust 采集器读取已声明的 TensorBoard 或 JSONL 来源，不导入训练框架。它向独立遥测 gRPC 服务发送有界批次。目前交付的网关是 Python 进程，RPC 容量和数据库连接池独立于 Node 控制通道。它不是 LLM 推理代理。

## 部署监听服务

网关需要已迁移的 PostgreSQL 数据库、与控制面一致的签名配置，以及富记录和产物所使用的对象存储配置。提供受信任的服务端证书，其主机名必须匹配采集器访问的地址。

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
python -m tuneplane_server.services.telemetry.gateway_main \
  --bind 0.0.0.0:8444 \
  --certificate /tls/tls.crt \
  --private-key /tls/tls.key
```

Compose 提供 `telemetry` profile。Helm 提供 `telemetryGateway.enabled`、`telemetryGateway.tlsSecret` 和端口 `8444`，与 `nodeGateway` 及其 `8443` 端口独立。通过保留 TLS 的 TCP 路由暴露 gRPC，并从执行主机验证可达性。

采集器通过校验服务端身份的 TLS，使用绑定 run、attempt、member 的专用工作负载令牌。Node 控制令牌和用户登录令牌不能替代它。平台负责下发和续期，不要把凭据粘贴进训练代码或实验配置。常规部署路径不要求采集器客户端证书。

## 安装采集器产物

使用锁定的 Rust 1.91.0 工具链以及已安装的目标平台和原生工具链，针对执行主机的操作系统与架构构建。Linux 生产产物使用 musl，例如：

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
uv run --no-sync python scripts/build-rust-collector.py /srv/tuneplane/collectors \
  --target x86_64-unknown-linux-musl
```

命令输出一个按内容寻址的目录，包含 `manifest.json` 和 `tuneplane-collector`。将完整目录部署到控制面和启动 worker 可读取的位置，成组配置托管遥测：

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
TUNEPLANE_TELEMETRY_GATEWAY_TARGET=telemetry.tuneplane.corp:8444
TUNEPLANE_TELEMETRY_TRUST_BUNDLE=/srv/tuneplane/certs/telemetry-ca.pem
TUNEPLANE_TELEMETRY_COLLECTOR_ARTIFACT=/srv/tuneplane/collectors/<sha256>
TUNEPLANE_TELEMETRY_SPOOL_ROOT=/var/lib/tuneplane-telemetry
TUNEPLANE_TELEMETRY_SPOOL_BYTES=268435456
TUNEPLANE_TELEMETRY_DRAIN_SECONDS=30
```

ARM 主机使用对应的 ARM 目标。启动路径会校验产物清单及摘要；适用于控制台主机的二进制不一定适用于训练主机。TensorBoard 官方 Python 库用于一致性测试，采集器不会把它安装进训练环境。

## 准备本地持久化存储

每台执行机器上的 spool 根目录都必须是私有、持久的主机本地存储，不能是 NFS 等共享网络文件系统。源日志和输出产物仍可使用共享存储。显式配置后端挂载；缺失或不合适的 spool 授权不能静默回退到共享输出目录。

Local Compose 部署可通过 `deploy/docker/compose.telemetry-local.yml` 将明确配置的主机 spool 根目录挂载到执行服务。Kubernetes 和 Slurm 同样需要各自后端的本地存储授权。对象交付不能让共享文件系统变得适合 SQLite spool。参见[存储](/zh-Hans/ops/storage)和[Node 执行](/zh-Hans/ops/executor-node)。

## 选择来源与查看结果

集成产物声明来源、读取归属和指标映射。每个共享来源只分配一个读取者。不要假设所有框架都由所有 rank 写日志，不要一律丢弃非零 rank，也不要按相同数值对不同成员去重。保留来源身份，由指定的所有者上报聚合值。

TensorBoard 标量和结构化 JSONL 是不同输入。TensorBoard 中体积较大的图片、直方图不会被隐式当作标量流传输。富 JSONL 通道有独立的格式和预算。W\&B 可以同时用于实验跟踪，但启用 TensorBoard 读取不代表支持 W\&B 专有本地历史格式。

打开 Job 的 **Charts** 标签页。标准曲线使用冻结的映射；原始标量检查器支持按 attempt 和来源选择。查询限制返回点数和序列数。降采样图不表示返回了全部原始记录。未知指标语义保持明确，不根据熟悉的 tag 名称猜测。

## 故障与恢复检查

| 现象                 | 检查项                                      |
| ------------------ | ---------------------------------------- |
| Node 已连接但图表为空      | 遥测地址和 CA 独立于 Node 控制地址；单独检查来源声明与采集器      |
| 网关故障时数据停止          | 确认本地 spool 持久且有空间；重启网关后检查重放恢复            |
| 发送成功但数据不完整         | ACK 发生在持久化接收之后；富数据投影及产物完成需要独立证据          |
| 重试后疑似重复点           | 对照 stream、交付序号、attempt 和来源身份；数值相同本身不代表重复 |
| 恢复的训练从 step 0 重新开始 | 选择正确的 attempt，之前的 attempt 历史应独立保留        |
| 准备较慢               | 检查镜像拉取与输入校验；异步准备本身不代表启动失败                |

ACK 丢失时会重放同一持久化批次身份。磁盘丢失、源日志保留耗尽或 spool 被销毁，与进程重启是不同故障，不继承进程重启的恢复保证。声明多机持久性前，应验证实际存储及后端配置。

现有 [HTTP/SDK 上报路径](/zh-Hans/ops/observability)仍用于支持的生命周期、日志和上报场景。只设置 `TUNEPLANE_INGEST_URL` 不会启用原生遥测。