配置和管理 Ray Dashboard#

Ray Dashboard 是监控和调试 Ray 应用和集群最重要的工具之一。本页介绍如何在您的集群上配置 Ray Dashboard。

Dashboard 配置可能因您启动 Ray 集群的方式（例如，本地 Ray 集群 vs. KubeRay）而异。与 Prometheus 和 Grafana 的集成是可选的，可提供更增强的 Dashboard 体验。

注意

Ray Dashboard 对于交互式开发和调试很有用，因为当集群终止时，dashboard UI 和底层数据将不再可访问。对于生产环境的监控和调试，您应该依赖持久化日志、持久化指标、持久化 Ray 状态以及其他可观测性工具。

更改 Ray Dashboard 端口#

Ray Dashboard 在头节点的端口 8265 上运行。如果需要，请按照以下说明自定义端口。

单节点本地集群

使用 CLI 显式启动集群
在命令行中使用 ray start 传递 --dashboard-port 参数。

使用 ray.init 隐式启动集群
在调用 ray.init() 时传递关键字参数 dashboard_port。

VM 集群启动器

在集群启动器 YAML 文件的 head_start_ray_commands 部分包含 --dashboard-port 参数。

head_start_ray_commands:
  - ray stop
  # Replace ${YOUR_PORT} with the port number you need.
  - ulimit -n 65536; ray start --head --dashboard-port=${YOUR_PORT} --port=6379 --object-manager-port=8076 --autoscaling-config=~/ray_bootstrap_config.yaml

KubeRay

有关详细信息，请参阅指定非默认端口页面。

在浏览器中查看 Ray Dashboard#

当您在笔记本电脑上启动单节点 Ray 集群时，可以通过 Ray 初始化时打印的 URL 访问 dashboard（默认 URL 是 http://localhost:8265）。

当您使用VM 集群启动器、KubeRay operator 或手动配置启动远程 Ray 集群时，Ray Dashboard 会在头节点上启动，但 dashboard 端口可能不会公开暴露。您需要进行额外设置才能从头节点外部访问 Ray Dashboard。

警告

出于安全考虑，在没有适当认证的情况下，请勿将 Ray Dashboard 公开暴露。

VM 集群启动器

端口转发
您可以使用 ray dashboard 命令安全地将本地流量端口转发到 dashboard。

$ ray dashboard [-p <port, 8265 by default>] <cluster config file>

现在可以通过 http://localhost:8265 访问 dashboard。

KubeRay

KubeRay operator 通过一个指向 Ray head Pod 的 Service 提供 Dashboard，该 Service 命名为 <RayCluster name>-head-svc。在 Kubernetes 集群内部可以通过 http://<RayCluster name>-head-svc:8265 访问 Dashboard。

有两种方法将 Dashboard 暴露到集群外部

1. 设置 ingress
遵循说明设置 ingress 以访问 Ray Dashboard。Ingress 必须仅允许来自可信源的访问。

2. 端口转发
您也可以通过使用端口转发从 Kubernetes 集群外部查看 dashboard

$ kubectl port-forward service/${RAYCLUSTER_NAME}-head-svc 8265:8265
# Visit ${YOUR_IP}:8265 for the Dashboard (e.g. 127.0.0.1:8265 or ${YOUR_VM_IP}:8265)

注意

不要在生产环境中使用端口转发。按照上述说明使用 Ingress 暴露 Dashboard。

有关配置 Kubernetes 上 Ray 集群网络访问的更多信息，请参阅网络说明。

在反向代理后运行#

通过反向代理访问时，Ray Dashboard 应该可以开箱即用。API 请求无需单独代理。

始终使用 URL 末尾带有斜杠 / 的方式访问 dashboard。例如，如果您的代理设置为处理到 /ray/dashboard 的请求，请在 www.my-website.com/ray/dashboard/ 查看 dashboard。

dashboard 发送带有相对 URL 路径的 HTTP 请求。当 window.location.href 以斜杠 / 结尾时，浏览器会按预期处理这些请求。

尽管 MDN 定义了预期的行为，但这许多浏览器处理带有相对 URL 的请求时的特有现象。

通过在反向代理中包含一条规则，将用户的浏览器重定向到 /，即 /ray/dashboard –> /ray/dashboard/，可以使您的 dashboard 在没有末尾斜杠的情况下可见。

下面是一个使用 traefik TOML 文件实现此目的的示例

[http]
  [http.routers]
    [http.routers.to-dashboard]
      rule = "PathPrefix(`/ray/dashboard`)"
      middlewares = ["test-redirectregex", "strip"]
      service = "dashboard"
  [http.middlewares]
    [http.middlewares.test-redirectregex.redirectRegex]
      regex = "^(.*)/ray/dashboard$"
      replacement = "${1}/ray/dashboard/"
    [http.middlewares.strip.stripPrefix]
      prefixes = ["/ray/dashboard"]
  [http.services]
    [http.services.dashboard.loadBalancer]
      [[http.services.dashboard.loadBalancer.servers]]
        url = "http://localhost:8265"

警告

Ray Dashboard 提供对 Ray 集群的读写访问。反向代理必须提供认证或网络 ingress 控制，以防止未经授权访问集群。

禁用 Dashboard#

如果您使用 ray[default] 或其他安装命令，则包含 Dashboard 并自动启动。

要禁用 Dashboard，请使用以下参数 --include-dashboard。

单节点本地集群

使用 CLI 显式启动集群

ray start --include-dashboard=False

使用 ray.init 隐式启动集群

import ray
ray.init(include_dashboard=False)

VM 集群启动器

在集群启动器 YAML 文件的 head_start_ray_commands 部分包含 ray start --head --include-dashboard=False 参数。

KubeRay

警告

不建议禁用 Dashboard，因为 RayJob 和 RayService 等多个 KubeRay 功能依赖于它。

将 spec.headGroupSpec.rayStartParams.include-dashboard 设置为 False。查看此示例 YAML 文件。

将 Grafana 可视化嵌入 Ray Dashboard#

为了获得更增强的 Ray Dashboard 体验，例如与日志、作业信息等一起查看时间序列指标，请设置 Prometheus 和 Grafana 并将其与 Ray Dashboard 集成。

设置 Prometheus#

要渲染 Grafana 可视化，您需要 Prometheus 从 Ray 集群抓取指标。遵循说明设置您的 Prometheus 服务器，并开始从 Ray 集群抓取系统和应用指标。

设置 Grafana#

Grafana 是一个支持 Prometheus 指标高级可视化并允许您使用您喜欢的指标创建自定义 dashboard 的工具。遵循说明设置 Grafana。

将 Grafana 可视化嵌入 Ray Dashboard#

要在 Ray Dashboard 中查看嵌入式时间序列可视化，必须设置以下各项

集群的头节点能够访问 Prometheus 和 Grafana。
dashboard 用户的浏览器能够访问 Grafana。

启动 Ray 集群时，使用 RAY_GRAFANA_HOST、RAY_PROMETHEUS_HOST、RAY_PROMETHEUS_NAME 和 RAY_GRAFANA_IFRAME_HOST 环境变量配置这些设置。

将 RAY_GRAFANA_HOST 设置为头节点可用于访问 Grafana 的地址。头节点在后端对 Grafana 进行健康检查。
将 RAY_PROMETHEUS_HOST 设置为头节点可用于访问 Prometheus 的地址。
设置 RAY_PROMETHEUS_NAME 以选择用于 Grafana dashboard 面板的不同数据源。默认为“Prometheus”。
将 RAY_GRAFANA_IFRAME_HOST 设置为用户浏览器可用于访问 Grafana 并嵌入可视化的地址。如果未设置 RAY_GRAFANA_IFRAME_HOST，Ray Dashboard 将使用 RAY_GRAFANA_HOST 的值。

例如，如果头节点的 IP 是 55.66.77.88，并且 Grafana 托管在端口 3000 上。将值设置为 RAY_GRAFANA_HOST=http://55.66.77.88:3000。

如果您手动启动单节点 Ray 集群，请确保在启动集群之前设置并可访问这些环境变量，或作为 ray start ... 命令的前缀，例如 RAY_GRAFANA_HOST=http://55.66.77.88:3000 ray start ...
如果您使用VM 集群启动器启动 Ray 集群，环境变量应在 head_start_ray_commands 下设置为 ray start ... 命令的前缀。
如果您使用KubeRay 启动 Ray 集群，请参阅此教程。

如果所有环境变量都设置正确，您应该在Ray Dashboard 中看到时间序列指标。

注意

如果您为每个 Ray 集群使用不同的 Prometheus 服务器，并为所有集群使用相同的 Grafana 服务器，请为每个 Ray 集群设置不同的 RAY_PROMETHEUS_NAME 环境变量，并在 Grafana 中添加这些数据源。遵循这些说明设置 Grafana。

备用 Prometheus 主机位置#

默认情况下，Ray Dashboard 假设 Prometheus 托管在 localhost:9090。您可以选择在非默认端口或另一台机器上运行 Prometheus。在这种情况下，请确保 Prometheus 可以按照此处的说明抓取 Ray 节点上的指标。

然后，按照上述说明正确配置 RAY_PROMETHEUS_HOST 环境变量。例如，如果 Prometheus 托管在 IP 为 55.66.77.88 的节点上端口 9000，请将 RAY_PROMETHEUS_HOST=http://55.66.77.88:9000。

自定义 Ray dashboard 到 Prometheus 请求的 header#

如果 Prometheus 需要额外的 header 进行认证，请使用以下 JSON 格式之一设置 RAY_PROMETHEUS_HEADERS，以便 Ray dashboard 将其发送给 Prometheus

{"Header1": "Value1", "Header2": "Value2"}
[["Header1", "Value1"], ["Header2", "Value2"], ["Header2", "Value3"]]

备用 Grafana 主机位置#

默认情况下，Ray Dashboard 假设 Grafana 托管在 localhost:3000。您可以选择在非默认端口或另一台机器上运行 Grafana，只要头节点和 dashboard 浏览器能够访问它即可。

如果在 Kubernetes 集群上使用 NGINX ingress 暴露 Grafana，Grafana ingress annotation 中应包含以下行

nginx.ingress.kubernetes.io/configuration-snippet: |
    add_header X-Frame-Options SAMEORIGIN always;

当 Grafana 和 Ray 集群都在同一个 Kubernetes 集群上时，将 RAY_GRAFANA_HOST 设置为 Grafana ingress 的外部 URL。

Grafana 用户认证#

当 Grafana 实例需要用户认证时，其配置文件中必须包含以下设置，以便在 Ray Dashboard 中正确嵌入

  [security]
  allow_embedding = true
  cookie_secure = true
  cookie_samesite = none

故障排除#

Dashboard 消息：未检测到 Prometheus 或 Grafana 服务器#

如果您已按照上述说明完成所有设置，请在浏览器中运行以下连接检查

检查头节点与 Prometheus 服务器的连接：在 Ray Dashboard URL 末尾添加 api/prometheus_health（例如：http://127.0.0.1:8265/api/prometheus_health）并访问它。
检查头节点与 Grafana 服务器的连接：在 Ray Dashboard URL 末尾添加 api/grafana_health（例如：http://127.0.0.1:8265/api/grafana_health）并访问它。
检查浏览器与 Grafana 服务器的连接：访问 RAY_GRAFANA_IFRAME_HOST 中使用的 URL。

遇到错误提示 `RAY_GRAFANA_HOST` 未设置#

如果您已经设置了 Grafana，请检查

您已在 URL 中包含协议（例如 http://your-grafana-url.com，而不是 your-grafana-url.com）。
URL 没有末尾的斜杠（例如 http://your-grafana-url.com，而不是 http://your-grafana-url.com/）。

证书颁发机构 (CA 错误)#

如果您的 Grafana 实例托管在 HTTPS 后面，您可能会看到 CA 错误。请联系 Grafana 服务所有者以正确启用 HTTPS 流量。

查看内置 Dashboard API 指标#

Dashboard 由一个服务器提供支持，该服务器通过 API 端点提供 UI 代码和集群数据。Ray 为每个 API 端点发出基本的 Prometheus 指标

ray_dashboard_api_requests_count_requests_total：收集请求总数。按端点、方法和 http_status 进行标记。

ray_dashboard_api_requests_duration_seconds_bucket：收集请求的持续时间。按端点和方法进行标记。

例如，您可以使用此查询查看所有请求的 p95 持续时间

histogram_quantile(0.95, sum(rate(ray_dashboard_api_requests_duration_seconds_bucket[5m])) by (le))

您可以从 Prometheus 或 Grafana UI 查询这些指标。请参阅上面的说明了解如何设置这些工具。

配置和管理 Ray Dashboard#

更改 Ray Dashboard 端口#

在浏览器中查看 Ray Dashboard#

在反向代理后运行#

禁用 Dashboard#

将 Grafana 可视化嵌入 Ray Dashboard#

设置 Prometheus#

设置 Grafana#

将 Grafana 可视化嵌入 Ray Dashboard#

备用 Prometheus 主机位置#

自定义 Ray dashboard 到 Prometheus 请求的 header#

备用 Grafana 主机位置#

Grafana 用户认证#

故障排除#

Dashboard 消息：未检测到 Prometheus 或 Grafana 服务器#

遇到错误提示 RAY_GRAFANA_HOST 未设置#

证书颁发机构 (CA 错误)#

查看内置 Dashboard API 指标#

遇到错误提示 `RAY_GRAFANA_HOST` 未设置#