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

人工智能分布式训练强化学习任务调度模型推理服务【免费下载链接】rayRay 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. 前置条件与能力边界在开始使用之前需要明确几个前提官方文档均有明确说明完整安装 RayState CLI 与 Log CLI 依赖完整安装安装命令为pip install ray[default]而非精简版pip install ray。需要 Dashboard 组件State API 的数据由 DashboardAPI Server代理聚合因此启动集群时必须包含 dashboard 组件。ray start与ray.init()的默认行为已经包含该组件一般无需额外配置。API 稳定性文档标注这些 API 属于alpha阶段接口签名与输出格式未来可能调整从源码PublicAPI(stabilitystable)标注看CLI 命令本身已标记为 stablestate_cli.py 中ray_get、ray_list、task_summary、actor_summary、object_summary及各ray logs子命令均标注stabilitystable但整体仍以官方稳定性声明为准。排错入口若 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_TASKActor 构造任务。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_sites1 ray start --head或在运行脚本时RAY_record_ref_creation_sites1 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、tabledefault-f, --filter过滤表达式形如keyvalue或key!value可重复指定多个多个条件按AND组合字符串值不区分大小写无--limit最大返回条目数100--detail输出更多字段可能触发查询更多数据源False--timeoutAPI 请求超时秒30来自DEFAULT_RPC_TIMEOUT--addressRay API Server 地址缺省时自动从本地集群/GCS 解析None4.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 ALIVE4.2 过滤语法详解--filter是ray list最强大的能力支持等于与!不等于两种谓词可组合多个条件实现复杂查询。官方示例cli-sdk.rst# 列出某个进程创建的所有本地引用对象 ray list objects -f pidPID -f reference_typeLOCAL_REFERENCE # 列出存活 Actor ray list actors -f stateALIVE # 列出运行中的 Task ray list tasks -f stateRUNNING # 列出非运行状态的 Task! 谓词 ray list tasks -f state!RUNNING # 多条件 AND运行中且名称为指定函数 ray list tasks -f stateRUNNING -f nametask_running_300_seconds()从源码看过滤表达式的解析逻辑位于_parse_filterstate_cli.py它会扫描字符串中第一个或!作为谓词分隔符拆出key、谓词与value格式非法如缺少谓词、key 或 value 为空时直接报错。自 Ray 2.7 起过滤值大小写不敏感过滤键key也会通过_normalize_filter_keys做大小写归一化——当用户写STATERUNNING而非stateRUNNING时会按 schema 列名大小写不敏感匹配并自动纠正若 key 完全非法则直接抛出BadParameter并列出可用过滤键而不是静默返回空结果。ListApiOptionscommon.py还实现了冲突过滤检测多个过滤器针对同一 key 但值不同如stateALIVE -f stateDEAD时会发出UserWarning提示将返回空集。4.3 输出格式与截断行为四种格式由output_with_format统一处理state_cli.pydefault/table带时间戳标题栏、Stats 与表格的终端友好格式default与table等价yaml带---/...显式标记的 YAML 流保持 schema 字段顺序sort_keysFalsejsonJSON 数组适合脚本解析。需要注意当--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-envsresource参数的可选列表在 state_cli.py 中显式排除了StateResource.JOBS与StateResource.RUNTIME_ENVSid是必填位置参数缺省时 CLI 会提示 Missing argument ID. Do you mean ray list {resource}?返回结果已按 schema 做detail 级别的完整输出format_get_api_output固定使用detailTrue与 YAML 格式若集群中找不到该 ID输出Resource with idid 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_ID6.2 通用参数所有ray logs子命令共享一组日志选项源码log_*_option定义参数说明默认值-f, --follow流式跟踪日志文件更新类似tail -f而非仅打印末尾False--tail N从文件末尾取 N 行-1表示取整个文件1000DEFAULT_LOG_LIMIT--timeoutAPI 请求超时秒指定--follow时该参数被忽略30-ip, --node-ip按节点 IP 过滤None-id, --node-id按 NodeID 过滤None--err查询 stderr 文件默认查 stdoutFalse--encoding日志解码编码接受 Pythoncodecs支持的任何编码utf-8--encoding-errors解码错误处理方案接受codecs支持的任何方案strict--interval参数用于控制--follow时的轮询间隔在源码中标记为hiddenTrue为内部参数。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 actorActor 日志# 跟踪指定 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 workerWorker 进程日志# 跟踪 Worker 进程pid123的日志 ray logs worker --pid 123 --follow # 获取 Worker 的 stderr ray logs worker --pid 123 --err--pid为必填源码中requiredTrue。ray logs job提交型 Job 日志# 获取 submission jobID 形如 raysubmit_xxx的日志 ray logs job --id raysubmit_xxx # 实时跟踪 ray logs job --id raysubmit_xxx --followray logs taskTask 日志# 获取 TaskID 形如 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 来自并发 Actorasync 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 调用——followFalse时访问/api/v0/logs/file端点followTrue时访问/api/v0/logs/stream端点media_type对应切换并以流式响应streamTrue逐 chunk 解码输出。日志按suffix参数out/err选择 stdout 或 stderr 文件按encoding/errors控制解码方式encodingNone时直接产出原始字节。7. 与 Python SDK 的对应关系State CLI 的所有能力在 Python SDK 中都有对应函数见 api.py 与 SDK 参考文档两者通过同一个StateApiClient访问后端。常用对应关系CLIPython SDKray summary tasks / actors / objectssummarize_tasks()/summarize_actors()/summarize_objects()ray list actors / tasks / objects / nodes / ...list_actors()/list_tasks()/list_objects()/list_nodes()等ray get actors idget_actor(id...)ray logs cluster/ray logs actor --id Xlist_logs(node_id...)/get_log(actor_id...)ray logs glob --followget_log(filename..., node_id..., followTrue)一个典型对应示例——用 SDK 流式读取节点日志import ray from ray.util.state import get_log node_id ray.nodes()[0][NodeID] for line in get_log(filenameraylet.out, node_idnode_id): print(line)官方建议优先使用CLI标注 stablePython SDK 标注为DeveloperAPI主要用于在代码中编程化集成。8. 失败语义与数据一致性State API 返回的是集群状态的快照snapshot官方明确不保证一致性或完整性详见 cli-sdk.rst 的 Failure Semantics 一节。存在三类数据缺失场景查询失败Query FailuresState API 会查询多个数据源GCS、raylet 等来构建快照。某个数据源不可用宕机或过载时API 返回不完整快照并通过 Pythonwarnings库输出警告可被抑制。CLI 默认返回部分结果并打印警告而 Python SDK 默认在输出缺失时抛出异常可用raise_on_missing_outputFalse关闭。数据截断Data Truncation当返回实体数过大时官方文档指出约 100K 行API 会截断输出以保证系统稳定且截断部分无法选择。源码层面另有硬性上限RAY_MAX_LIMIT_FROM_API_SERVER与RAY_MAX_LIMIT_FROM_DATA_SOURCE默认各为 10Kcommon.py可通过环境变量调整。同时ray list --limit默认上限为 100。资源已被垃圾回收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.rstVM 集群ray exec——通过集群配置文件在集群内执行命令ray exec cluster config file ray statusKubeRaykubectl 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 status10. 源码速览与扩展阅读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 SDKpython/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_LIMIT100、DEFAULT_LOG_LIMIT1000、DEFAULT_RPC_TIMEOUT30及各资源的状态 schemaActorState、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 组件返回的是可能过期的状态快照且日志仅覆盖存活节点——理解这些边界才能在实践中正确解读命令输出。赞分享人工智能分布式训练强化学习任务调度模型推理服务【免费下载链接】rayRay 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常见问题解决方案从环境配置到运行错误的完整排查创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考