可观测性：遥测、Dashboard 与 Admin TUI
训练任务上到集群后，"它到底在干什么"就成了最重要的问题。Monarch 提供一套可观测性体系、三个互补的诊断界面：分布式遥测（SQL 分析）、Monarch Dashboard（浏览器可视化）、Mesh Admin TUI（终端实时诊断）。
1. 三个界面怎么选
| 使用场景 | 界面 | 提供什么 |
|---|---|---|
| 查询 actor / mesh / 消息 / 追踪 / 指标历史 | 分布式遥测 | 跨主机的 DataFusion SQL |
| 浏览器里看拓扑、状态、故障、流量 | Monarch Dashboard | 实时摘要、层级视图、作业 DAG |
| 终端里诊断运行中的 mesh | Mesh Admin TUI | 实时拓扑、健康检查、py-spy 栈 |
| 导出指标和日志到外部系统 | OpenTelemetry | OTLP 导出到 Prometheus / Loki |
Dashboard 读取遥测数据，TUI 读取 Mesh Admin API；定期的 mesh-admin 快照也会流入遥测，供 Dashboard 展示实时管理拓扑。OpenTelemetry 负责把指标送往外部后端，与作业内的遥测并行不悖。
2. 启用可观测性
在调用 state() 之前配置遥测：
from monarch.job import ProcessJob, TelemetryConfig
job = ProcessJob({"workers": 2}).enable_telemetry(
TelemetryConfig(
retention_secs=3600, # 保留窗口（秒），0 表示不自动清理
include_dashboard=True, # 启用浏览器 Dashboard
dashboard_port=8265, # Dashboard 端口，0 表示随机端口
snapshot_interval_secs=30, # 拓扑快照间隔，0 表示禁用
)
)
state = job.state(cached_path=None)
print(state.dashboard_url) # 浏览器打开
print(state.admin_url) # 传给 monarch-tui --addrenable_telemetry() 同时会启用 mesh admin 与周期性自省快照。把它套在你现有的 LocalJob / ProcessJob / SlurmJob / KubernetesJob 上即可，不需要创建第二个作业。
只想要 admin 服务（不要遥测与 Dashboard）时，用 job.enable_admin()。
3. 分布式遥测：SQL 查询一切
Monarch 把 actor 系统事件和 OTel 指标收集到每台主机，汇成一个逻辑数据库——底层是 Apache DataFusion（构建于 Apache Arrow 之上）。查询示例：
client = state.query_engine_client
if client is None:
raise RuntimeError("telemetry did not start")
# 最近 50 条 actor 状态变更
result = client.query(
"""
SELECT a.full_name, s.new_status, s.reason, s.timestamp_us
FROM actor_status_events AS s
JOIN actors AS a ON a.id = s.actor_id
ORDER BY s.timestamp_us DESC
LIMIT 50
"""
)
for row in result["rows"]:
print(row)核心表
| 表 | 内容 |
|---|---|
actor_status_events | Actor 状态变迁及原因 |
actors | Actor 身份、rank、mesh、创建时间 |
messages / sent_messages / message_status_events | 消息投递记录 |
meshes | mesh 创建、形状、类别、父子关系 |
metric_gauges / metric_sums / metric_histograms | 三类 OTel 指标点 |
spans / span_events / events | 追踪与结构化日志 |
用 SELECT table_name FROM information_schema.tables 可发现全部表。
常用查询
-- 各状态的 actor 数量分布
SELECT new_status, COUNT(*) AS count
FROM actor_status_events
GROUP BY new_status
ORDER BY count DESC
-- 最近的 actor 失败
SELECT a.full_name, s.reason, s.timestamp_us
FROM actor_status_events AS s
JOIN actors AS a ON a.id = s.actor_id
WHERE s.new_status = 'Failed'
ORDER BY s.timestamp_us DESC
LIMIT 100注意事项：
- 遥测表在内存中，属于当前作业分配——不是持久的事件归档；
- 分布式扫描是 best-effort：某个 worker 收集器失败只会降低查询覆盖，不会拖垮作业；
- 查询结果为空不一定是没数据——摄入是异步的，稍等重试。
4. Mesh Admin TUI：终端里的听诊器
monarch-tui 随 torchmonarch 包一起安装，连接 mesh admin API 后以可导航的树形视图渲染完整拓扑（主机 → 进程 → Actor），右侧是上下文详情面板。
# 终端 1：启动任意会拉起 MeshAdminAgent 的 Monarch 应用
python python/examples/dining_philosophers.py
# 输出: Mesh admin server listening on http://127.0.0.1:1729
# 终端 2：连接 TUI
monarch-tui --addr 127.0.0.1:1729杀手级功能：py-spy 栈追踪。在任意进程或 Actor 上按 p，通过 py-spy 抓取实时 Python 栈——逐线程栈帧、GIL 归属、线程名一目了然，诊断 C 扩展和 CUDA 调用挂死时特别好用。py-spy 不随包附带，需在目标主机上可解析（PATH 或 PYSPY_BIN）。
常用按键：j/k 上下移动，Tab 展开折叠，g/G 跳首跳尾。
5. 指标体系
Monarch 内置指标统一走进程级全局 OpenTelemetry meter provider：库只负责记录 counter/gauge/histogram，不关心目的地。两跳出口：
| 路径 | 启用方式 | 目的地 | 主要用途 |
|---|---|---|---|
| 分布式遥测 | job.enable_telemetry(...) | 作业内 SQL 表 | 当前作业内的调试分析 |
| OTLP | OTEL_EXPORTER_OTLP_ENDPOINT | OTel Collector | 外部聚合、监控、可视化 |
两条路径可同时启用，同一份指标既进作业内遥测，又进外部后端（如 Prometheus + Grafana）。
6. 日志
用户日志路由到对应进程的 stdout/stderr。分布式运行时，可以把所有 worker 日志流式汇总到客户端并聚合降噪：
import asyncio
# stream_to_client=True：转发所有进程日志（best effort），
# 窗口聚合器折叠相似行，输出摘要
asyncio.run(procs.logging_option(stream_to_client=True, aggregate_window_sec=3))Monarch 系统日志位于各主机 /tmp/$USER/monarch*；用 MONARCH_FILE_LOG（stdout）与 MONARCH_STDERR_LOG（stderr）调整级别，可选 TRACE/DEBUG/INFO/WARN/ERROR。
关键点
- 一套配置三个界面：
enable_telemetry()一次打开遥测 + Dashboard + admin； - SQL 查一切：DataFusion 引擎，actor/消息/追踪/指标全是表；
- TUI + py-spy 是挂死类问题的终极速诊工具；
- OTLP 双出口：作业内调试与外部监控两不误。