Ray 开发人员调试指南#

本调试指南适用于 Ray 项目的贡献者。

在调试器中启动进程#

当进程崩溃时，通常需要在调试器中启动它们。Ray 目前允许使用以下工具启动进程：

  • valgrind

  • valgrind 性能分析器

  • perftools 性能分析器

  • gdb

  • tmux

要使用这些工具中的任何一个，请确保您已在本地安装它们（gdb 和 valgrind 在 MacOS 上已知存在问题）。然后，您可以通过添加环境变量 RAY_{PROCESS_NAME}_{DEBUGGER}=1 来启动部分 Ray 进程。例如，如果您想在 valgrind 中启动 raylet，只需设置环境变量 RAY_RAYLET_VALGRIND=1。

要在 gdb 中启动进程，该进程还必须在 tmux 中启动。因此，如果您想在 gdb 中启动 raylet，您需要使用以下方式启动您的 Python 脚本：

RAY_RAYLET_GDB=1 RAY_RAYLET_TMUX=1 python

然后，您可以使用 tmux ls 列出 tmux 会话，并连接到相应的会话。

您还可以获取 raylet 进程的核心转储，这在提交 问题 时特别有用。获取核心转储的过程是操作系统特定的，但通常需要先运行 ulimit -c unlimited 来启动 Ray，以允许写入核心转储文件。

后端日志记录#

raylet 进程会记录有关任务执行和节点间对象传输等事件的详细信息。要在运行时设置日志级别，您可以在启动 Ray 之前设置 RAY_BACKEND_LOG_LEVEL 环境变量。例如，您可以这样做：

export RAY_BACKEND_LOG_LEVEL=debug
ray start

这将把源代码中的任何 RAY_LOG(DEBUG) 行打印到 raylet.err 文件中，您可以在 日志记录和调试 中找到它。如果一切正常，您应该在 raylet.err 的第一行看到：

logging.cc:270: Set ray log level from environment variable RAY_BACKEND_LOG_LEVEL to -1

(-1 在 logging.h 中定义为 RayLogLevel::DEBUG)。

  TRACE = -2,

后端事件统计#

如果设置了 RAY_event_stats=1 环境变量，raylet 进程还会定期将事件统计信息转储到 debug_state.txt 及其日志文件中。要更改 Ray 将统计信息写入日志文件的间隔，您可以设置 RAY_event_stats_print_interval_ms。

事件统计信息包括 ASIO 事件处理程序、周期性计时器和 RPC 处理程序。以下是事件统计信息示例：

Event stats:
Global stats: 739128 total (27 active)
Queueing time: mean = 47.402 ms, max = 1372.219 s, min = -0.000 s, total = 35035.892 s
Execution time:  mean = 36.943 us, total = 27.306 s
Handler stats:
  ClientConnection.async_read.ReadBufferAsync - 241173 total (19 active), CPU time: mean = 9.999 us, total = 2.411 s
  ObjectManager.ObjectAdded - 61215 total (0 active), CPU time: mean = 43.953 us, total = 2.691 s
  CoreWorkerService.grpc_client.AddObjectLocationOwner - 61204 total (0 active), CPU time: mean = 3.860 us, total = 236.231 ms
  CoreWorkerService.grpc_client.GetObjectLocationsOwner - 51333 total (0 active), CPU time: mean = 25.166 us, total = 1.292 s
  ObjectManager.ObjectDeleted - 43188 total (0 active), CPU time: mean = 26.017 us, total = 1.124 s
  CoreWorkerService.grpc_client.RemoveObjectLocationOwner - 43177 total (0 active), CPU time: mean = 2.368 us, total = 102.252 ms
  NodeManagerService.grpc_server.PinObjectIDs - 40000 total (0 active), CPU time: mean = 194.860 us, total = 7.794 s

回调延迟注入#

有时，bug 是由 RPC 问题引起的，例如，由于某些请求的延迟，系统会进入死锁状态。为了调试和重现这类问题，我们需要一种方法来注入 RPC 请求的延迟。为了实现这一点，引入了 RAY_testing_asio_delay_us。如果您想让某些 RPC 请求的回调在一段时间后执行，可以使用此变量。例如：

RAY_testing_asio_delay_us="NodeManagerService.grpc_client.PrepareBundleResources=2000000:2000000" ray start --head

其语法是 RAY_testing_asio_delay_us="method1=min_us:max_us,method2=min_us:max_us"。条目用逗号分隔。有一个特殊的 * 方法，表示所有方法。它的优先级低于其他条目。