Ray State CLI 实战指南：用 `ray summary`、`ray list`、`ray get` 与 `ray logs` 洞察集群实时状态

• 人工智能
• 分布式训练
• 强化学习
• 任务调度
• 模型推理服务

【免费下载链接】ray

Ray is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.

项目地址：https://gitcode.com/gh_mirrors/ra/ray

点击查看免费下载

本篇指南围绕 Ray 官方文档 State CLI 参考 展开，系统讲解 Ray 观测性（Observability）体系中面向命令行的一组核心工具：用于查看集群中 Task、Actor、Object 等资源实时状态的ray summary、ray list、ray get，以及用于拉取集群日志的ray logs。读完本文，你将掌握每条命令的完整参数、输出格式、过滤语法与使用场景，并能结合源码理解其底层数据采集机制，从而在排查分布式任务卡死、Actor 异常、内存泄漏和节点日志问题时做到快速定位。

1. 前置条件与能力边界

在开始使用之前，需要明确几个前提（官方文档均有明确说明）：

• 完整安装 Ray：State CLI 与 Log CLI 依赖完整安装，安装命令为pip install "ray[default]"，而非精简版pip install ray。
• 需要 Dashboard 组件：State API 的数据由 Dashboard（API Server）代理聚合，因此启动集群时必须包含 dashboard 组件。ray start与ray.init()的默认行为已经包含该组件，一般无需额外配置。
• API 稳定性：文档标注这些 API 属于alpha阶段，接口签名与输出格式未来可能调整；从源码@PublicAPI(stability="stable")标注看，CLI 命令本身已标记为 stable（state_cli.py 中ray_get、ray_list、task_summary、actor_summary、object_summary及各ray logs子命令均标注stability="stable"），但整体仍以官方稳定性声明为准。
• 排错入口：若 State API 行为异常，可查看 Dashboard 日志深入排查，路径为<RAY_LOG_DIR>/dashboard.log，单机默认通常是/tmp/ray/session_latest/logs/dashboard.log。
• 日志时效性：ray logs只能访问**存活节点（alive nodes）**上的日志；已死亡的节点日志无法通过该 API 获取。

2. State 命令族总览

State CLI 由三个主要命令构成，分别对应三种粒度的查询（详见 cli-sdk.rst 用户指南 中的 Key Concepts）：

命令	语义	用途
ray summary <resource>	汇总视图	按某个维度（函数名/类名/callsite）聚合统计，适合先看全局
ray list <resource>	列表视图	列出每个实体的状态记录，适合定位具体异常实体
ray get <resource> <id>	单条详情	按 ID 获取单个实体最详细的信息
ray logs <subcommand>	日志访问	获取 Actor、Task、Worker 及系统日志文件

支持查询的资源类型：从源码StateResource枚举（common.py）可以看到，State API 覆盖 actors、jobs、placement_groups、nodes、workers、tasks、objects、runtime_envs、cluster_events 共九类资源。CLI 参数中下划线会转换为连字符，例如placement_groups对应命令行参数placement-groups。

推荐的排查路径：官方建议先用ray summary观察整体，发现异常（例如 Actor 长时间存活、Task 长时间未调度）后，再用ray list/ray get深入单个实体细节。ray list的 docstring 中也明确写着 "Normally, summary APIs are recommended before listing all resources"。

3.ray summary：资源汇总视图

ray summary提供三个子命令，分别汇总 Task、Actor 与 Object 三种资源（对应源码 state_cli.py 中的task_summary、actor_summary、object_summary，分别调用 SDK 的summarize_tasks、summarize_actors、summarize_objects）。

3.1ray summary tasks

按Task 函数名分组汇总所有 Task 的状态计数：

ray summary tasks

输出示例（来自 cli-sdk.rst）：

======== Tasks Summary: 2022-07-22 08:54:38.332537 ======== Stats: ------------------------------------ total_actor_scheduled: 2 total_actor_tasks: 0 total_tasks: 2 Table (group by func_name): ------------------------------------ FUNC_OR_CLASS_NAME STATE_COUNTS TYPE 0 task_running_300_seconds RUNNING: 2 NORMAL_TASK 1 Actor.__init__ FINISHED: 2 ACTOR_CREATION_TASK

注意其中的TYPE列区分了NORMAL_TASK（普通远程任务）与ACTOR_CREATION_TASK（Actor 构造任务）。Task 的状态值（如 RUNNING、FINISHED、PENDING）由 common_pb2.proto 中的TaskStatus枚举定义，ray summary tasks会把各状态计数聚合在STATE_COUNTS列中。

3.2ray summary actors

按Actor 类名分组汇总 Actor 状态：

ray summary actors

输出示例：

{'cluster': {'summary': {'Actor': {'class_name': 'Actor', 'state_counts': {'ALIVE': 2}}}, 'total_actors': 2, 'summary_by': 'class'}}

（以上为 Python SDK 的原始返回；CLI 会将其格式化为带标题栏的表格。）

3.3ray summary objects

按Object 的 callsite（创建点）分组汇总对象引用，官方特别推荐在排查内存泄漏时使用（其 docstring 说明该命令与ray memory几乎等价，但输出更易读）。

一个关键前提：callsite 默认不采集。若未配置环境变量，所有对象会被聚合到名为disabled的 callsite 下。启用 callsite 采集需要在启动 Ray 时设置：

RAY_record_ref_creation_sites=1 ray start --head

或在运行脚本时：

RAY_record_ref_creation_sites=1 python ray_script.py

启用后，ray summary objects的输出会按每个 callsite 分别展示total_objects、total_size_mb、total_num_workers、total_num_nodes、task_state_counts、ref_type_counts等指标，并显示callsite_enabled: True。

输出内部机制：三个 summary 子命令共用format_summary_output/format_object_summary_output函数（state_cli.py），结构为"Stats 元信息 + 分组表格"，其中summary_by字段标识了分组维度（func_name/class/callsite）。若集群中无对应资源，输出为一行No resource in the cluster。

4.ray list：列出资源状态

ray list返回指定资源下每个实体的状态记录，是定位问题最常用的命令。其完整参数如下（源码定义见 state_cli.py 中的ray_list命令）：

参数	说明	默认值
resource（位置参数）	资源类型，可选actors、tasks、objects、nodes、workers、jobs、placement-groups、runtime-envs、cluster-events	必填
--format	输出格式，可选default、json、yaml、table	default
-f, --filter	过滤表达式，形如key=value或key!=value；可重复指定多个，多个条件按AND组合；字符串值不区分大小写	无
--limit	最大返回条目数	100
--detail	输出更多字段（可能触发查询更多数据源）	False
--timeout	API 请求超时（秒）	30（来自DEFAULT_RPC_TIMEOUT）
--address	Ray API Server 地址；缺省时自动从本地集群/GCS 解析	None

4.1 基本用法

# 列出集群中所有 Actor ray list actors # 只取 50 条（排序顺序不可控） ray list actors --limit 50 # 以 YAML 格式输出 ray list actors --format yaml # 输出更详细字段（可能查询更多数据源） ray list actors --detail

默认表格输出示例：

======== List: 2022-07-23 21:29:39.323925 ======== Stats: ------------------------------ Total: 2 Table: ------------------------------ ACTOR_ID CLASS_NAME NAME PID STATE 0 31405554844820381c2f0f8501000000 Actor 96956 ALIVE 1 f36758a9f8871a9ca993b1d201000000 Actor 96955 ALIVE

4.2 过滤语法详解

--filter是ray list最强大的能力，支持=（等于）与!=（不等于）两种谓词，可组合多个条件实现复杂查询。官方示例（cli-sdk.rst）：

# 列出某个进程创建的所有本地引用对象 ray list objects -f pid=<PID> -f reference_type=LOCAL_REFERENCE # 列出存活 Actor ray list actors -f state=ALIVE # 列出运行中的 Task ray list tasks -f state=RUNNING # 列出非运行状态的 Task（!= 谓词） ray list tasks -f state!=RUNNING # 多条件 AND：运行中且名称为指定函数 ray list tasks -f state=RUNNING -f name="task_running_300_seconds()"

从源码看，过滤表达式的解析逻辑位于_parse_filter（state_cli.py）：它会扫描字符串中第一个=或!=作为谓词分隔符，拆出key、谓词与value，格式非法（如缺少谓词、key 或 value 为空）时直接报错。自 Ray 2.7 起，过滤值大小写不敏感；过滤键（key）也会通过_normalize_filter_keys做大小写归一化——当用户写STATE=RUNNING而非state=RUNNING时，会按 schema 列名大小写不敏感匹配并自动纠正；若 key 完全非法，则直接抛出BadParameter并列出可用过滤键，而不是静默返回空结果。

ListApiOptions（common.py）还实现了冲突过滤检测：多个=过滤器针对同一 key 但值不同（如state=ALIVE -f state=DEAD）时，会发出UserWarning提示将返回空集。

4.3 输出格式与截断行为

四种格式由output_with_format统一处理（state_cli.py）：

• default/table：带时间戳标题栏、Stats 与表格的终端友好格式；default与table等价；
• yaml：带---/...显式标记的 YAML 流，保持 schema 字段顺序（sort_keys=False）；
• json：JSON 数组，适合脚本解析。

需要注意：当--detail与--format default同时使用时，输出会自动切换为 YAML 格式（因为详细字段过多、表格会变得不可读）。另外，若返回结果为空，CLI 输出No resource in the cluster，这表示查询成功但没有匹配数据。

5.ray get：按 ID 获取单实体详情

ray get <resource> <id>用于按 ID 获取单个实体的详细状态：

# 获取指定 Actor 的完整状态（ID 可从 ray list actors 的输出获得） ray get actors <ACTOR_ID> # 获取 Placement Group 信息 ray get placement-groups <PLACEMENT_GROUP_ID>

输出为 YAML 格式，示例：

--- actor_id: 31405554844820381c2f0f8501000000 class_name: Actor death_cause: null is_detached: false name: '' pid: 96956 resource_mapping: [] serialized_runtime_env: '{}' state: ALIVE

关于ray get的几个关键限制（源码ray_getdocstring 与参数定义）：

• 不支持按 ID 查询jobs与runtime-envs：resource参数的可选列表在 state_cli.py 中显式排除了StateResource.JOBS与StateResource.RUNTIME_ENVS；
• id是必填位置参数，缺省时 CLI 会提示 "Missing argument 'ID'. Do you mean 'ray list {resource}'?"；
• 返回结果已按 schema 做detail 级别的完整输出（format_get_api_output固定使用detail=True与 YAML 格式）；
• 若集群中找不到该 ID，输出Resource with id=<id> not found in the cluster.。

6.ray logs：集群日志访问

ray logs是 Log CLI 的入口，用于从集群拉取日志。它与ray status、ray list nodes等命令配合，可以在不登录各节点的情况下集中查看分布式应用的日志。

6.1 子命令结构

ray logs是一个命令组（源码中为LogCommandGroup，见 state_cli.py），包含五个子命令：

子命令	定位方式	说明
ray logs cluster <glob>	日志文件名（glob）	列出/打印节点上的系统日志文件
ray logs actor	--id <ACTOR_ID>或--pid <PID>	获取某个 Actor 的日志
ray logs worker	--pid <PID>（必填）	获取某个 Worker 进程的日志
ray logs job	--id raysubmit_xxx（必填）	获取某个提交型 Job 的日志
ray logs task	--id <TASK_ID>（必填）	获取某个 Task 的日志

便捷别名：LogCommandGroup重写了resolve_command，当用户直接执行ray logs <glob>且第一个参数无法解析为子命令时，会自动转发为ray logs cluster <glob>。因此下面两条命令等价：

ray logs gcs_server.out --node-id <NODE_ID> ray logs cluster gcs_server.out --node-id <NODE_ID>

6.2 通用参数

所有ray logs子命令共享一组日志选项（源码log_*_option定义）：

参数	说明	默认值
-f, --follow	流式跟踪日志文件更新（类似tail -f），而非仅打印末尾	False
--tail <N>	从文件末尾取 N 行；-1表示取整个文件	1000（DEFAULT_LOG_LIMIT）
--timeout	API 请求超时（秒）；指定--follow时该参数被忽略	30
-ip, --node-ip	按节点 IP 过滤	None
-id, --node-id	按 NodeID 过滤	None
--err	查询 stderr 文件（默认查 stdout）	False
--encoding	日志解码编码，接受 Pythoncodecs支持的任何编码	utf-8
--encoding-errors	解码错误处理方案，接受codecs支持的任何方案	strict

（--interval参数用于控制--follow时的轮询间隔，在源码中标记为hidden=True，为内部参数。）

6.3 子命令实战示例

ray logs cluster：系统日志文件

# 列出 head 节点上所有可获取的日志文件 ray logs cluster # 打印 head 节点 raylet.out 的最后 500 行 ray logs cluster raylet.out --tail 500 # 打印 worker 节点（node-id A）的 raylet.out 最后 500 行 ray logs cluster raylet.out --tail 500 --node-id A # 把 gcs_server.out 完整下载到本地文件 ray logs cluster gcs_server.out --tail -1 > gcs_server.txt # 从最后 100 行开始实时跟踪 raylet.out ray logs cluster raylet.out --tail 100 -f

其行为逻辑（log_cluster实现）：先用list_logs按 glob 模式匹配节点上的日志文件；若匹配结果恰好只有一个文件则直接打印其内容，否则打印匹配到的文件列表（YAML 格式）。不指定--node-id/--node-ip时，默认查询head 节点（通过_get_head_node_ip从 Ray 地址解析 head 节点 IP）。

ray logs actor：Actor 日志

# 跟踪指定 Actor 的日志 ray logs actor --id <ACTOR_ID> --follow # 按 pid + 节点 IP 获取（与 Driver 打印的 (ip=..., pid=..., class_name) 日志对应） ray logs actor --pid 123 --node-ip x.x.x.x # 获取 Actor 的 stderr 日志 ray logs actor --id <ACTOR_ID> --err

--id与--pid至少需指定其一，否则抛出MissingParameter。Actor ID 可从ray list actors的输出获得。

ray logs worker：Worker 进程日志

# 跟踪 Worker 进程（pid=123）的日志 ray logs worker --pid 123 --follow # 获取 Worker 的 stderr ray logs worker --pid 123 --err

--pid为必填（源码中required=True）。

ray logs job：提交型 Job 日志

# 获取 submission job（ID 形如 raysubmit_xxx）的日志 ray logs job --id raysubmit_xxx # 实时跟踪 ray logs job --id raysubmit_xxx --follow

ray logs task：Task 日志

# 获取 Task（ID 形如 ABCDEFG）的 stderr ray logs task --id <TASK_ID> --err # 获取该 Task 第 1 次重试（attempt 1）的日志 ray logs task --id <TASK_ID> -a 1

-a, --attempt-number默认值为0，用于在 Task 重试时区分不同尝试的日志。一个使用注意：如果 Task 来自并发 Actor（async actor 或 threaded actor），其日志会与 Actor 的其他日志交错，此时应改用ray logs actor --id <ACTOR_ID>获取整个 Actor 的日志。

6.4 日志输出的底层行为

_print_log在tail > 0时会在日志内容前打印一段提示：--- Log has been truncated to last N lines. Use --tail flag to toggle. Set to -1 for getting the entire file. ---。随后它通过 SDK 的get_log以流式方式逐块打印日志（api.py）。底层原理：get_log将请求封装为对 Dashboard API Server 的 HTTP 调用——follow=False时访问/api/v0/logs/file端点，follow=True时访问/api/v0/logs/stream端点（media_type对应切换），并以流式响应（stream=True）逐 chunk 解码输出。日志按suffix参数（out/err）选择 stdout 或 stderr 文件，按encoding/errors控制解码方式（encoding=None时直接产出原始字节）。

7. 与 Python SDK 的对应关系

State CLI 的所有能力在 Python SDK 中都有对应函数（见 api.py 与 SDK 参考文档），两者通过同一个StateApiClient访问后端。常用对应关系：

CLI	Python SDK
ray summary tasks / actors / objects	summarize_tasks()/summarize_actors()/summarize_objects()
ray list actors / tasks / objects / nodes / ...	list_actors()/list_tasks()/list_objects()/list_nodes()等
ray get actors <id>	get_actor(id=...)
ray logs cluster/ray logs actor --id X	list_logs(node_id=...)/get_log(actor_id=...)
ray logs <glob> --follow	get_log(filename=..., node_id=..., follow=True)

一个典型对应示例——用 SDK 流式读取节点日志：

import ray from ray.util.state import get_log node_id = ray.nodes()[0]["NodeID"] for line in get_log(filename="raylet.out", node_id=node_id): print(line)

官方建议优先使用CLI（标注 stable），Python SDK 标注为DeveloperAPI，主要用于在代码中编程化集成。

8. 失败语义与数据一致性

State API 返回的是集群状态的快照（snapshot），官方明确不保证一致性或完整性（详见 cli-sdk.rst 的 Failure Semantics 一节）。存在三类数据缺失场景：

1. 查询失败（Query Failures）：State API 会查询多个"数据源"（GCS、raylet 等）来构建快照。某个数据源不可用（宕机或过载）时，API 返回不完整快照并通过 Pythonwarnings库输出警告（可被抑制）。CLI 默认返回部分结果并打印警告，而 Python SDK 默认在输出缺失时抛出异常（可用raise_on_missing_output=False关闭）。
2. 数据截断（Data Truncation）：当返回实体数过大时（官方文档指出约 >100K 行），API 会截断输出以保证系统稳定，且截断部分无法选择。源码层面另有硬性上限：RAY_MAX_LIMIT_FROM_API_SERVER与RAY_MAX_LIMIT_FROM_DATA_SOURCE默认各为 10K（common.py），可通过环境变量调整。同时ray list --limit默认上限为 100。
3. 资源已被垃圾回收（Garbage Collected Resources）：依赖资源生命周期，"已完成"的资源可能已无法访问。例如 Ray 会周期性回收 DEAD 状态的 Actor 数据以降低内存占用，也会在 lineage 超出作用域后清理 FINISHED 状态的 Task。不要依赖该 API 获取已结束资源的准确信息。

另外，ray get/ray list的 docstring 均注明："The returned state snapshot could be stale, and it is not guaranteed to return the live data"——即快照可能过期，不能当作实时数据使用。

9. 在集群外使用这些命令

State CLI 命令本质上需要通过 Ray 地址连接集群，因此默认需在集群节点上运行。若在集群外部的机器上执行，官方给出两种方式（cli-sdk.rst）：

VM 集群（ray exec）——通过集群配置文件在集群内执行命令：

ray exec <cluster config file> "ray status"

KubeRay（kubectl exec）——先找到 Ray head pod，再进入容器执行：

# 找到 Ray head pod 名称 kubectl get pod | grep <RayCluster name>-head # 输出示例：<RayCluster name>-head-xxxxx 2/2 Running 0 XXs # 在 head pod 内执行 ray 命令 kubectl exec <RayCluster name>-head-xxxxx -- ray status

10. 源码速览与扩展阅读

• CLI 实现：python/ray/util/state/state_cli.py ——ray summary/ray list/ray get/ray logs全部命令的参数定义、过滤解析（_parse_filter、_normalize_filter_keys）、输出格式化（output_with_format、format_summary_output、format_object_summary_output）与LogCommandGroup别名机制。
• Python SDK：python/ray/util/state/api.py ——get_*、list_*、summarize_*、get_log、list_logs等函数的实现，以及get_log对/api/v0/logs/file|stream端点的流式请求。
• schema 与默认值：python/ray/util/state/common.py ——StateResource资源枚举、ListApiOptions/GetApiOptions选项结构、DEFAULT_LIMIT=100、DEFAULT_LOG_LIMIT=1000、DEFAULT_RPC_TIMEOUT=30及各资源的状态 schema（ActorState、TaskState等）。
• 用户指南：doc/source/ray-observability/user-guides/cli-sdk.rst —— 完整的命令示例、输出样例与失败语义说明。
• SDK 参考：doc/source/ray-observability/reference/api.rst —— 所有 SDK 函数与 schema 类的索引。
• 观测性概念：doc/source/ray-observability/key-concepts.rst —— Ray States、Dashboard、日志目录结构等背景知识。

总结

ray summary、ray list、ray get与ray logs构成了 Ray 命令行观测的四件套：汇总看趋势、列表找异常、get 看细节、logs 查日志。结合本文介绍的过滤语法、输出格式、默认值与失败语义，你可以在集群出现 Task 卡死、Actor 异常退出、对象内存泄漏或日志排查需求时，快速定位问题实体并获取诊断信息。需要留意的是，这些命令依赖完整安装（ray[default]）与 Dashboard 组件，返回的是可能过期的状态快照，且日志仅覆盖存活节点——理解这些边界，才能在实践中正确解读命令输出。

赞分享

• 人工智能
• 分布式训练
• 强化学习
• 任务调度
• 模型推理服务

【免费下载链接】ray

Ray is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.

项目地址：https://gitcode.com/gh_mirrors/ra/ray

点击查看免费下载

相关推荐

• 用 ray status 与 Ray State CLI/SDK 监控集群与应用状态

  用 ray status 与 Ray State CLI/SDK 监控集群与应用状态 导读 Ray 为监控和调试集群与应用状态提供了两条路径：一条是运行在 he

  人工智能分布式训练强化学习任务调度模型推理服务

• Ray Jobs CLI 命令参考：ray job submit / status / stop / logs / list / delete 全量实战指南

  Ray Jobs CLI 命令参考：ray job submit / status / stop / logs / list / delete 全量实战指南 R

  人工智能分布式训练强化学习任务调度模型推理服务

• Ray Client 指南：用 `ray.init("ray://...")` 将交互式 Python 会话接入远程 Ray 集群

  Ray Client 指南：用 ray.init "ray://..." 将交互式 Python 会话接入远程 Ray 集群 导读 Ray Client 是 R

  人工智能分布式训练强化学习任务调度模型推理服务

上一篇：IndexTTS2训练数据构建指南：情感语音语料采集与标注规范

下一篇：TEngine常见问题解决方案：从环境配置到运行错误的完整排查