用 ray status 与 Ray State CLI/SDK 监控集群与应用状态【免费下载链接】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 为监控和调试集群与应用状态提供了两条路径一条是运行在 head 节点上的ray status命令用于快速查看节点状态与资源使用另一条是更强大的 Ray State API通过 CLI 命令ray summary、ray list、ray get、ray logs或 Python SDK 访问集群当前状态的快照覆盖 Actors、Tasks、Objects、Nodes、Jobs、Placement Groups、Workers、Runtime Envs 等全部资源类型。读完本文你将掌握如何使用这些命令定位节点无法缩容、任务长期未调度、Actor 异常等典型问题并能从集群外部VM 集群或 KubeRay远程执行这些诊断命令。一、ray status集群节点与资源的一线观测ray status需要在 head 节点上执行它从 GCSGlobal Control Service中读取自动扩缩容器autoscaler维护的状态并打印出来。其底层实现在 python/ray/scripts/scripts.py 的status(address, verbose)函数中通过gcs_client.internal_kv_get(ray_constants.DEBUG_AUTOSCALING_STATUS.encode())读取内部 KV 存储中由 autoscaler 周期性写入的状态字符串再交给debug_status格式化输出见 python/ray/scripts/scripts.py。因此ray status反映的是 autoscaler 视角的集群状态。它的输出分为两大块Node Status节点状态正在运行并参与扩缩容的节点、各节点的地址、Pending等待中节点和最近失败的节点。Resource Usage资源使用整个集群的 Ray 资源用量例如所有 Ray Task 与 Actor 请求的 CPU 数、已使用的 GPU 数、内存与 object store 内存占用。典型输出如下$ ray status Autoscaler status: 2021-10-12 13:10:21.035674 Node status --------------------------------------------------------------- Healthy: 1 ray.head.default 2 ray.worker.cpu Pending: (no pending nodes) Recent failures: (no failures) Resources --------------------------------------------------------------- Usage: 0.0/10.0 CPU 0.00/70.437 GiB memory 0.00/10.306 GiB object_store_memory Demands: (no resource demands)解读要点Healthy列出健康节点及其数量本例为 1 个 head 节点和 2 个 CPU worker 节点Pending列出正被云供应商创建、尚未注册到集群的节点Recent failures给出最近创建/启动失败的节点及其原因。Usage中已用/总量的形式展示各类资源Demands展示当前存在资源需求的 Task/Actor 请求可用于判断集群是否需要扩容。当需要更详细的逐节点信息时使用ray status -v$ ray status -v-vverbose模式会输出每个节点的详细信息包括节点 IP、资源总量与可用量、标签等。文档特别指出当你要排查为什么某些节点没有自动缩容这类问题时-v模式非常有用——比如某个节点上有长时间存活的对象引用或未释放的资源仅看汇总信息难以定位。二、Ray State API 概览CLI 与 Python SDK 的两种用法除了ray statusRay 还提供了一组 State API用于访问集群当前状态快照。其中CLI 命令被标记为 stable稳定而 Python SDK 属于 Developer API开发者 API文档明确建议优先使用 CLI两者底层走同一条 HTTP 通道——StateApiClient向 dashboard 的 API server 发起 REST GET 请求见 python/ray/util/state/api.py。前置条件原文档明确说明需要完整安装 Raypip install ray[default]需要 dashboard 组件可用即启动集群时包含 dashboardray start与ray.init()的默认行为就是如此。若 API server 不可达客户端会提示检查 dashboard 是否可用并确认依赖是否安装完整见 python/ray/util/state/api.py。快速上手准备一个示例应用以下脚本会运行 2 个 Task 并创建 2 个 Actor每个 Task 睡 300 秒便于观察运行中状态import ray import time ray.init(num_cpus4) ray.remote def task_running_300_seconds(): time.sleep(300) ray.remote class Actor: def __init__(self): pass # Create 2 tasks tasks [task_running_300_seconds.remote() for _ in range(2)] # Create 2 actors actors [Actor.remote() for _ in range(2)]运行后稍等片刻让 Task 完成提交即可用下面的命令观察状态。如果命令没有立刻返回输出重试一次即可。查看 Task 汇总ray summary tasks输出示例 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_TASKPython SDK 等价写法from ray.util.state import summarize_tasks print(summarize_tasks())返回的字典中cluster.summary按func_or_class_name分组state_counts统计各状态下的数量同时给出total_tasks、total_actor_tasks、total_actor_scheduled等全局统计。列出所有 Actorray list actors输出示例 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 ALIVEPython SDK 等价写法from ray.util.state import list_actors print(list_actors())返回的是ActorState对象列表包含actor_id、class_name、state、job_id、name、node_id、pid、ray_namespace、serialized_runtime_env、required_resources、death_cause、is_detached、placement_group_id、repr_name等字段。获取单个 Actor 的详细状态# 在本例中ACTOR_ID 为 31405554844820381c2f0f8501000000 ray get actors ACTOR_ID输出示例YAML 格式--- actor_id: 31405554844820381c2f0f8501000000 class_name: Actor death_cause: null is_detached: false name: pid: 96956 resource_mapping: [] serialized_runtime_env: {} state: ALIVEPython SDK 等价写法from ray.util.state import get_actor print(get_actor(idACTOR_ID))读取 Actor 日志ray list actors # 在本例中ACTOR_ID 为 31405554844820381c2f0f8501000000 ray logs actor --id ACTOR_ID输出示例--- Log has been truncated to last 1000 lines. Use --tail flag to toggle. --- :actor_name:Actor Actor createdPython SDK 等价写法from ray.util.state import get_log for line in get_log(actor_idACTOR_ID): print(line)注意输出顶部提示日志默认截断为最后 1000 行可通过--tail标志调整对应 SDK 参数tail-1表示获取完整日志默认常量DEFAULT_LOG_LIMIT 1000见 python/ray/util/state/common.py。三、核心概念states、resources 与四类 API理解 Ray State API先掌握三组名词states状态对应资源的集群状态。状态由不可变元数据如 Actor 的 name和可变状态如 Actor 的调度状态或 pid组成。resources资源由 Ray 创建的对象例如 actors、tasks、objects、placement groups 等。四类 APIsummary返回资源的汇总视图例如按函数名分组的任务数量list返回资源的每一个实体逐条列出支持过滤get返回单个实体的详细信息按 ID 查询logs访问 Actor、Task、Worker 或系统日志文件的日志。从实现看StateResource枚举定义了全部可用资源类型ACTORS、JOBS、PLACEMENT_GROUPS、NODES、WORKERS、TASKS、OBJECTS、RUNTIME_ENVS、CLUSTER_EVENTS其中SummaryResource仅支持 actors、tasks、objects 三类见 python/ray/util/state/common.py。这也是为什么ray summary只有这三个子命令而ray list/ray get覆盖更多资源。CLI 与 SDK 的对应关系如下操作CLI 命令Python SDK汇总ray summary actors/tasks/objectssummarize_actors()/summarize_tasks()/summarize_objects()列出ray list resourcelist_actors()/list_tasks()/list_nodes()等单个查询ray get resource IDget_actor(id...)/get_task(id...)等日志ray logs ...get_log(...)/list_logs(...)完整导出清单见 python/ray/util/state/init.py。CLI 的过滤、分页、输出格式等公共选项定义在 python/ray/util/state/state_cli.py 起的 click 选项中。四、summary按类型汇总资源状态官方建议的监控起点是 summary API先用它发现异常例如长时间运行的 Actor、长时间未调度的 Task再用list或get深入定位某个异常的实体。汇总所有 Actorray summary actorsfrom ray.util.state import summarize_actors print(summarize_actors())输出示例{cluster: {summary: {Actor: {class_name: Actor, state_counts: {ALIVE: 2}}}, total_actors: 2, summary_by: class}}汇总所有 Taskray summary tasksfrom ray.util.state import summarize_tasks print(summarize_tasks())输出示例与第一节示例一致按func_name分组{cluster: {summary: {task_running_300_seconds: {func_or_class_name: task_running_300_seconds, type: NORMAL_TASK, state_counts: {RUNNING: 2}}, Actor.__init__: {func_or_class_name: Actor.__init__, type: ACTOR_CREATION_TASK, state_counts: {FINISHED: 2}}}, total_tasks: 2, total_actor_tasks: 0, total_actor_scheduled: 2, summary_by: func_name}}汇总所有 Objectray summary objectsfrom ray.util.state import summarize_objects print(summarize_objects())注意默认情况下 Object 按 callsite调用点汇总但 Ray 默认并不记录 callsite。要获得调用点信息需要在启动集群时设置环境变量RAY_record_ref_creation_sites1RAY_record_ref_creation_sites1 ray start --head未开启 callsite 时的输出中会出现callsite_enabled: False与按disabled归组的统计total_objects、total_size_mb、total_num_workers、total_num_nodes、task_state_counts、ref_type_counts。五、list按类型列出所有实体支持过滤ray list返回某类资源的完整列表。可列出的资源包括ActorsActor ID、State、PID、death_cause输出 schema 为ActorStateTasks名称、调度状态、类型、runtime env 信息TaskStateObjectsobject ID、callsite、引用类型ObjectStateJobs开始/结束时间、entrypoint、状态JobStatePlacement Groups名称、bundles、统计PlacementGroupStateNodesRay worker 节点node ID、node IP、节点状态NodeStateWorkersRay worker 进程worker ID、类型、退出类型与详情WorkerStateRuntime environmentsruntime env、创建时间、所在节点RuntimeEnvState。这些数据类 schema 统一定义在 python/ray/util/state/common.py 中CLI 的表格列即按这些 dataclass 字段顺序生成见 python/ray/util/state/state_cli.py。列出所有节点ray list nodesfrom ray.util.state import list_nodes list_nodes()列出所有 Placement Groupray list placement-groupsfrom ray.util.state import list_placement_groups list_placement_groups()注意 CLI 中资源名使用连字符placement-groups而 SDK 中为下划线placement_groups这是_get_available_resources中做_→-替换的结果见 python/ray/util/state/state_cli.py。按条件过滤--filter/-flistAPI 支持一个或多个过滤条件CLI 使用-f/--filterSDK 使用filters参数元素为(key, predicate, value)三元组predicate 支持与!。列出某进程创建的本地引用对象ray list objects -f pidPID -f reference_typeLOCAL_REFERENCEfrom ray.util.state import list_objects list_objects(filters[(pid, , 1234), (reference_type, , LOCAL_REFERENCE)])列出存活 Actorray list actors -f stateALIVEfrom ray.util.state import list_actors list_actors(filters[(state, , ALIVE)])列出运行中的 Taskray list tasks -f stateRUNNINGfrom ray.util.state import list_tasks list_tasks(filters[(state, , RUNNING)])列出非运行状态的 Task不等于ray list tasks -f state!RUNNINGfrom ray.util.state import list_tasks list_tasks(filters[(state, !, RUNNING)])组合条件列出名为指定函数名、且正在运行的 Taskray list tasks -f stateRUNNING -f nametask_running_300_seconds()from ray.util.state import list_tasks list_tasks(filters[(state, , RUNNING), (name, , task_running_300_seconds())])从源码看CLI 的_parse_filter会解析keyval与key!val两种形式!后必须紧跟否则报格式错误并在过滤前对 key 做大小写归一化STATERUNNING也会被归一化为stateRUNNING若 key 不在该资源的 schema 列中会直接报错提示可用列名而不是返回空结果见 python/ray/util/state/state_cli.py。SDK 侧filters会被转换为filter_keys、filter_predicates、filter_values三个查询参数见 python/ray/util/state/api.py。列出更详细的 Task 信息--detail指定--detail时API 会查询更多的数据源以获取详细的状态信息ray list tasks --detailfrom ray.util.state import list_tasks list_tasks(detailTrue)六、get查询单个实体的详细状态get按 ID 精确查询单个实体。获取某个 Task 的状态ray get tasks TASK_IDfrom ray.util.state import get_task get_task(idTASK_ID)获取某个节点的状态ray get nodes NODE_IDfrom ray.util.state import get_node get_node(idNODE_ID)实现细节上get并不是单独的查询通道客户端会把id转换成对应的过滤条件如 nodes 用node_id、actors 用actor_id、tasks 用task_id并强制detailTrue后走 list 接口见 python/ray/util/state/api.py。注意并非所有资源都支持按 ID 查询——jobs与runtime-envs目前不支持get代码中RESOURCE_ID_KEY_NAME未包含这两者时会抛出ValueError。此外一个 task_id 可能对应多次重试产生的多个 attempt此时get会返回列表而非单个对象。七、logs获取与流式跟踪日志State API 还允许访问 Ray 日志。使用约束如下无法从已死亡的节点读取日志默认从head 节点打印日志CLI 与 SDK 行为一致。列出 head 节点上所有可获取的日志文件名ray logs clusterfrom ray.util.state import list_logs # 与 CLI 的默认行为对齐需要显式传入 head 节点 ID list_logs(node_idHEAD_NODE_ID)head 节点 ID 可从ray list nodes的输出中获得。获取某个节点上的特定日志文件# 先从 ray list nodes 获取节点 ID / 节点 IP ray logs cluster gcs_server.out --node-id NODE_ID # ray logs cluster 在使用 glob 查询时是 ray logs 的别名 ray logs gcs_server.out --node-id NODE_IDfrom ray.util.state import get_log # Node IP 可从 list_nodes() 或 ray.nodes() 获取 for line in get_log(filenamegcs_server.out, node_idNODE_ID): print(line)流式跟踪某个日志文件# 先从 ray list nodes 获取节点 ID / 节点 IP ray logs raylet.out --node-ip NODE_IP --follow # 或者 ray logs cluster raylet.out --node-ip NODE_IP --followfrom ray.util.state import get_log # Node IP 可从 list_nodes() 或 ray.nodes() 获取 # 循环在 followTrue 时会阻塞并持续输出新日志 for line in get_log(filenameraylet.out, node_ipNODE_IP, followTrue): print(line)按 Actor ID 流式跟踪 Actor 日志ray logs actor --idACTOR_ID --followfrom ray.util.state import get_log # Actor ID 可从 ray list actors 的输出获取 # 循环在 followTrue 时会阻塞并持续输出新日志 for line in get_log(actor_idACTOR_ID, followTrue): print(line)按 PID 流式跟踪 Worker 日志ray logs worker --pidPID --followfrom ray.util.state import get_log # Node IP 可从 list_nodes() 或 ray.nodes() 获取 # 当 worker 的输出被定向到 driver默认行为时很容易从中拿到运行 Actor 的 PID # 循环在 followTrue 时会阻塞并持续输出新日志 for line in get_log(pidPID, node_ipNODE_IP, followTrue): print(line)从 SDK 签名可以看到get_log支持的全部查询维度与选项node_id/node_ip/filename相对 Ray 日志目录的文件名/actor_id/task_id/pid按 pid 查询时必须同时提供 node_id 或 node_ip/follow流式/tail-1 表示全部/timeout/suffix按 ID 查询时默认 out/encoding/errors/submission_id/attempt_number按 task 查询时指定尝试次数/filter_ansi_code是否过滤 ANSI 转义码等见 python/ray/util/state/api.py。需要留意对于 concurrent actor应按actor_id查询日志而非task_id。八、失败语义State API 的可靠性边界State API不保证任何时候都返回一致、完整的集群快照。默认情况下所有 Python SDK 在输出缺失时会抛出异常而 CLI 返回部分结果并给出警告信息。以下三类情况可能造成输出缺失查询失败Query FailuresState API 会查询多个数据源如 GCS、raylet 等来构建集群快照。当某个数据源不可用宕机或过载时API 返回部分不完整快照并通过警告消息告知输出不完整。所有警告通过 Python 的warnings库打印可以被抑制。在 SDK 侧raise_on_missing_outputTrue默认时遇到部分失败会抛出RayStateApiException可显式设为False允许缺失输出见 python/ray/util/state/api.py。数据截断Data Truncation当返回的实体数量过大超过约 10 万条时API 会截断输出数据以保障系统稳定性截断发生时用户无法选择保留哪些数据。触发截断时会通过 Python 的warnings模块提示。截断与限流的默认阈值由环境变量控制RAY_MAX_LIMIT_FROM_API_SOURCEAPI server 到客户端的最大条目数默认 10000与RAY_MAX_LIMIT_FROM_DATA_SOURCE数据源如 raylet 处的截断阈值默认 10000相关常量定义见 python/ray/util/state/common.py。此外客户端默认limit为 100DEFAULT_LIMIT返回条目数超限时同样会给出使用--filter缩小范围或调高--limit的提示。已垃圾回收的资源Garbage Collected Resources取决于资源生命周期部分已结束finished的资源因为已被垃圾回收而无法通过 API 访问。不要依赖该 API 获取已结束资源的准确信息。例如 Ray 会周期性垃圾回收 DEAD 状态 Actor 的数据以降低内存占用当 Task 的血缘lineage超出作用域时也会清理其 FINISHED 状态。九、在集群外部使用 Ray CLI 工具上述 CLI 命令必须在 Ray 集群内的节点上执行。若需要从集群外部的机器执行可按部署方式选择以下方案。VM 集群Cluster Launcher使用ray exec在集群上执行命令$ ray exec cluster config file ray statusKubeRay使用kubectl exec与配置的 RayCluster 名称执行命令。Ray 使用指向 Ray head pod 的 Service 在集群上执行 CLI 命令# 首先找到 Ray head service 的名称。 $ kubectl get pod | grep RayCluster name-head # NAME READY STATUS RESTARTS AGE # RayCluster name-head-xxxxx 2/2 Running 0 XXs # 然后使用 Ray head service 的名称执行 ray status。 $ kubectl exec RayCluster name-head-xxxxx -- ray status同理ray summary、ray list、ray get、ray logs等命令也可以这样在集群外部执行——这为把监控诊断能力集成到 CI、运维脚本或远程排障流程中提供了标准通道。十、进一步参考State CLI 命令完整参考ray summary/ray list/ray get的所有参数与输出格式doc/source/ray-observability/reference/cli.rstState SDKPython API完整参考ray.util.state模块下各函数文档与StateApiClient见 doc/source/ray-observability/reference/api.rstLog CLI 参考ray logs子命令参数见 doc/source/ray-observability/reference/cli.rstSDK 核心实现客户端与查询逻辑在 python/ray/util/state/api.pyCLI 命令定义与输出格式化在 python/ray/util/state/state_cli.py资源枚举、schema 与默认阈值常量在 python/ray/util/state/common.py输出格式支持default表格、json、yaml、table四种可通过 CLI 的--format选项指定见 python/ray/util/state/state_cli.py便于在脚本中做程序化解析小结推荐的问题排查路径把本节内容串成一条可落地的排障流程先在 head 节点执行ray status观察集群整体健康度与资源水位发现异常后用ray summary actors/tasks/objects定位是哪一类资源、哪个函数/类出了问题再用带-f过滤条件的ray list缩小到具体实体例如-f stateRUNNING、-f state!RUNNING接着用ray get resource ID查看单个实体的完整字段如 Actor 的death_cause、Task 的状态与尝试信息最后用ray logs拉取或--follow流式跟踪相关 Actor/Worker/系统日志。整个过程既可以在集群内直接执行也可以通过ray exec或kubectl exec从集群外部发起。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考