Ray VM 集群日志持久化完整指南：日志目录、采集工具与日志生命周期管理-平芜编程栈

Ray VM 集群日志持久化完整指南：日志目录、采集工具与日志生命周期管理

【免费下载链接】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

导读

在 VM（虚拟机/物理机）集群上运行 Ray 时，日志是排查应用与集群故障的第一手依据——例如节点异常终止时，你可能需要系统日志来定位根因。但 Ray 本身不提供日志数据的原生存储方案，日志生命周期需要用户自行管理。本指南基于 Ray 官方文档 doc/source/cluster/vms/user-guides/logging.md，系统讲解 Ray 日志在 VM 集群上的落盘目录结构、日志轮转配置、主流日志处理工具选型，以及"采集 → 解析 → 投递"的完整日志收集流水线，帮助你构建一套可落地的 VM 集群日志持久化方案。

为什么 VM 集群上的日志需要持久化

Ray 默认将日志以文件形式写入每个节点文件系统的/tmp/ray/session_*/logs目录，这些日志同时包含应用日志与系统日志。问题的关键在于：

日志目录位于tmp文件系统下，机器一旦重启，临时目录通常会被清理，日志文件可能随之丢失；
当集群或部分节点被停止时，未及时处理的日志将无法再被检索。

因此在 VM 集群场景下，日志持久化不是一个可选项，而是保证可观测性与故障可排查性的必要环节。Kubernetes 场景（KubeRay）下的日志持久化与此类似，但本文聚焦 VM 部署。开始采集前，建议先熟悉 Ray 的日志目录结构与日志文件说明以及日志轮转配置。

Ray 日志目录与日志文件类型

默认情况下，Ray 将日志写入/tmp/ray/session_*/logs。每个新的 Ray session 都会在临时目录下新建一个 session 文件夹，并将最新 session 软链到/tmp/ray/session_latest：

├── tmp/ray │ ├── session_latest │ │ ├── logs │ │ ├── ... │ ├── session_2023-05-14_21-19-58_128000_45083 │ │ ├── logs │ │ ├── ... │ ├── session_2023-05-15_21-54-19_361265_24281 │ ├── ...

需要说明的几点：

在 Linux 与 macOS 上，Ray 默认使用/tmp/ray作为临时目录；如需修改临时目录及日志目录，可在调用ray start或ray.init()时显式指定；
Ray 会在机器重启时清理临时目录，因此 session 停止后日志可能丢失——这正是需要引入采集与持久化的原因；
Ray 官方不保证日志目录的向后兼容性，升级版本后日志文件布局可能变化。

日志文件清单：应用日志与系统日志

Ray 日志目录中的文件大致分为应用日志与系统（组件）日志两大类。注意：.out文件来自 stdout/stderr，.err文件来自 stderr。

应用日志

日志文件	说明
`job-driver-[submission_id].log`	通过 Ray Jobs API 提交的任务（Job）驱动进程的 stdout
`worker-[worker_id]-[job_id]-[pid].[out\\|err]`	Ray 驱动与 worker 的 Python/Java 部分；Task 与 Actor 的所有 stdout/stderr 都会被流式写入这些文件。其中`job_id`是驱动（driver）的 Job ID

系统/组件日志

日志文件	说明
`dashboard.[log\\|out\\|err]`	Ray Dashboard 日志。`.log`来自 dashboard logger；`.out`/`.err`是其 stdout/stderr，通常为空，仅当 dashboard 异常崩溃时才有内容
`dashboard_agent.[log\\|out\\|err]`	每个 Ray 节点都有一个 dashboard agent，含义同上
`dashboard_[module_name].[log\\|out\\|err]`	Dashboard 各子进程（按模块划分）的日志
`gcs_server.[out\\|err]`	GCS Server（管理集群元数据的无状态服务），仅存在于 head 节点
`io-worker-[worker_id]-[pid].[out\\|err]`	IO worker 日志。Ray 1.3+ 默认创建 IO worker 用于将对象溢出（spill）/恢复（restore）到外部存储
`log_monitor.[log\\|out\\|err]`	Log Monitor 负责将日志流式传输到 driver
`monitor.[log\\|out\\|err]`	Autoscaler 的日志
`python-core-driver-[worker_id]_[pid].log`	Ray 驱动由 C++ core 与 Python/Java 前端组成，此文件来自 C++ 部分
`python-core-worker-[worker_id]_[pid].log`	Ray worker 的 C++ core 部分日志
`raylet.[out\\|err]`	Raylet 的日志
`runtime_env_agent.[log\\|out\\|err]`	每个节点上管理 Runtime Environment 创建、删除与缓存的 agent 日志。实际`pip install`的安装日志见下方`runtime_env_setup-[job_id].log`
`runtime_env_setup-ray_client_server_[port].log`	通过 Ray Client 连接时安装 Runtime Environment 的日志
`runtime_env_setup-[job_id].log`	为 Task、Actor 或 Job 安装 Runtime Environment 的日志（仅在安装了 runtime env 时出现）

值得注意：系统日志中也可能包含应用相关信息，例如runtime_env_setup-[job_id].log可能包含应用环境与依赖的信息。

日志轮转配置

为避免日志文件无限增长耗尽磁盘，Ray 支持日志轮转（log rotation）。需要注意：并非所有组件都支持轮转——Raylet、Python worker 与 Java worker 的日志不参与轮转。

默认轮转参数

默认单文件最大 512 MB（maxBytes）；
默认最多保留 5 个备份文件（backupCount），备份文件带索引后缀，例如raylet.out.1。

以上默认值可在 python/ray/_common/ray_constants.py 中确认：

LOGGING_ROTATE_BYTES = 512 * 1024 * 1024 # 512MB. LOGGING_ROTATE_BACKUP_COUNT = 5 # 5 Backup files at max.

通过环境变量调整轮转

在启动 Ray 之前设置环境变量即可覆盖默认值：

RAY_ROTATION_MAX_BYTES=1024; ray start --head # 单文件上限 1KB RAY_ROTATION_BACKUP_COUNT=1; ray start --head # 备份数 1

单个日志文件（含其备份）的总大小上界为：RAY_ROTATION_MAX_BYTES * RAY_ROTATION_BACKUP_COUNT + RAY_ROTATION_MAX_BYTES。

源码实现印证

Python 侧：日志轮转参数在 python/ray/_private/node.py 中从环境变量读取，并校验max_bytes >= 0、backup_count >= 0；
C++ 侧：RayLog 的轮转参数解析位于 src/ray/util/logging.cc，其中RAY_ROTATION_MAX_BYTES与RAY_ROTATION_BACKUP_COUNT仅在__APPLE__或__linux__平台生效，backup_count需大于 0 才被接受，否则回退为默认值 1。

日志处理工具选型

Ray 社区常见的做法是选用成熟的开源日志处理工具来完成采集、解析与投递。官方文档明确提及的候选工具包括：

Vector：高性能、统一的日志/指标采集与转发管道，支持丰富的数据源与 sink；
FluentBit：轻量级、插件化的日志采集器，适合在资源受限的节点上作为 agent 运行；
Fluentd：功能全面的日志采集与聚合器，插件生态庞大；
Filebeat：Elastic 官方轻量采集器，天然对接 Elasticsearch/Logstash；
Promtail：Grafana Loki 的官方日志采集客户端，适合与 Loki 检索栈搭配。

选型时可以从以下维度权衡：节点资源占用（sidecar/daemon 形式）、解析能力（是否支持多行、JSON 结构化）、投递目标（Elasticsearch、Loki、S3、Kafka 等）、以及团队已有的可观测性栈。

日志采集三步流程

选定工具后，对 VM 集群上的每个 Ray 节点执行以下三个步骤即可完成日志收集：

Ingest（采集源）：将每个节点上 Ray 集群的日志文件作为采集源。由于日志位于/tmp/ray/session_*/logs（session 目录动态变化），建议以/tmp/ray/session_latest/logs作为稳定入口，或在采集器配置中监听通配符路径并处理目录切换（注意多 session 并存时避免重复采集）。
Parse and transform（解析与转换）：对采集到的原始日志做解析与清洗。Ray 提供结构化日志能力，可以显著简化这一环节：
- 应用侧：通过ray.LoggingConfig(encoding="JSON", ...)或RAY_LOGGING_CONFIG_ENCODING=JSON让应用日志输出 JSON 结构化格式，日志中自动携带job_id、worker_id、node_id、actor_id、task_id等 Ray 特有字段（详见结构化日志配置）；
- 系统侧：设置RAY_BACKEND_LOG_JSON=1可使后端系统日志（如 Job Supervisor、Raylet、GCS）以 JSON 格式输出；
- 若选择从 driver 的 stdout/stderr 集中采集，可配合RAY_DISABLE_WORKER_LOG_PREFIX=1去掉每行日志的前缀，避免破坏 JSON 等结构化格式（如 newline-delimited JSON）。
Ship（投递）：将转换后的日志投递到日志存储或管理系统中，例如 Elasticsearch、Loki、S3、Kafka，或集中式日志平台，从而在集群停止后仍可检索历史日志。

结合 Ray 日志机制设计采集方案

为了让采集方案更贴合 Ray 的实际行为，还需了解以下与日志相关的默认机制：

Worker 日志默认回流 driver：Task 与 Actor 的 stdout/stderr 默认会流式传输到 Ray driver，便于在单点聚合分布式应用日志；大规模场景下可用ray.init(log_to_driver=False)关闭，避免 driver 成为瓶颈。
日志去重：Ray 默认对跨进程重复出现的日志做去重，同一模式的消息会聚合最多 5 秒后批量输出，并以[repeated Nx across cluster]标注；通过RAY_DEDUP_LOGS=0可关闭。若采集端解析的是结构化日志，建议同时关闭前缀与去重，否则去重注解会破坏行式 JSON 格式。
日志文件与流式输出的关系：无论是否回流 driver，Ray 都会将 stdout/stderr 写入 worker 日志文件；采集工具既可以直接以文件为源（推荐，路径稳定且无前缀污染），也可以采集 driver 的 stdout。

小结

VM 集群上的 Ray 日志持久化本质上是"理解默认落盘结构 + 合理轮转 + 工具化采集投递"的组合：日志默认位于/tmp/ray/session_*/logs（临时目录、重启即失），可通过环境变量调整轮转策略，再借助 Vector / FluentBit / Fluentd / Filebeat / Promtail 等开源工具，按"采集 → 解析（优先使用结构化日志）→ 投递"三步把日志送达到集中存储。配合 Ray 日志配置指南中的轮转、结构化日志与去重开关，即可构建一套可持续、可检索的 VM 集群日志持久化方案。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考