收集和查看 Google Kubernetes Engine (GKE) 上的 Ray 集群的日志和指标

本页面介绍如何配置 Google Kubernetes Engine (GKE) 以收集在 Google Kubernetes Engine (GKE) 上运行的 Ray 集群的日志和指标，以及如何在 Cloud Logging 和 Cloud Monitoring 中查看 Ray 日志和指标。

如需详细了解 Ray 和 KubeRay，请参阅 Ray on Google Kubernetes Engine (GKE) 概览。

准备工作

在开始之前，请确保您已执行以下任务：

• 启用 Google Kubernetes Engine API。
启用 Google Kubernetes Engine API
• 如果您要使用 Google Cloud CLI 执行此任务，请安装并初始化 gcloud CLI。 如果您之前安装了 gcloud CLI，请通过运行 gcloud components update 命令来获取最新版本。较早版本的 gcloud CLI 可能不支持运行本文档中的命令。

• 为 Google Kubernetes Engine (GKE) 启用 Ray Operator。

要求和限制

• 您必须先在现有 GKE 集群上启用系统和工作负载日志记录，然后才能对 Ray 集群启用日志收集。
• 如果您对现有 GKE 集群上的 Ray 集群启用日志收集，则 GKE 只会从新创建的 Ray Pod 中收集日志，而不会从现有 Ray Pod 中收集日志。
• 对于标准 GKE 集群，您必须启用 Google Cloud Managed Service for Prometheus，才能对 Ray 集群启用指标收集功能。对于 Autopilot 集群，Google Cloud Managed Service for Prometheus 默认处于启用状态。
• 您不得在 Ray 集群的任何 Ray 容器中指定名为 ray-logs 的卷。否则，GKE 将不会收集日志。
• JSON 日志记录适用于 GKE v1.35.1-gke.1616000 及更高版本。如需启用结构化 JSON 日志记录，请在 Ray 容器规范中配置 特定的环境变量。

对 Ray 集群启用日志收集

您可以在使用新的或现有 Autopilot 或 Standard GKE 集群的情况下，对 Ray 集群启用日志收集。GKE 从 Ray 集群收集的 Ray 日志被归类为容器日志。这包括由 Ray 集群标头和工作器节点生成的所有日志。

您可以使用 Google Cloud 控制台或 gcloud CLI 对 Ray 集群启用日志收集。

gcloud container clusters create CLUSTER_NAME \
    --location=LOCATION \
    --addons=RayOperator \
    --enable-ray-cluster-logging

查看 Ray 日志

您可以使用 Logging 查看从 GKE 上运行的 Ray 集群收集的日志。

1. 前往 Google Cloud 控制台中的 Cloud Logging 页面。

   转到 Cloud Logging

2. 打开查询编辑器并将表达式粘贴到查询编辑器中

3. 点击运行查询

您可以在 Logs Explorer 中使用以下示例查询：

resource.type="k8s_container"
labels."k8s-pod/ray_io/is-ray-node"="yes"

resource.type="k8s_container"
labels."k8s-pod/ray_io/node-type"="head"

resource.type="k8s_container"
labels."k8s-pod/ray_io/cluster"="RAY_CLUSTER_NAME"

resource.type="k8s_container"
jsonPayload.ray_submission_id="RAY_JOB_SUBMISSION_ID"

resource.type="k8s_container"
labels."k8s-pod/ray_io/cluster"="RAY_CLUSTER_NAME"
labels."k8s-pod/ray_io/node-type"="worker"
jsonPayload.filename=~"/tmp/ray/session_latest/logs/worker-(.*).out"

启用增强型结构化日志记录（推荐）

增强型结构化日志记录适用于 GKE v1.35.1-gke.1616000 及更高版本。

默认情况下，Ray 日志在 Cloud Logging 中以非结构化文本字符串的形式捕获在 jsonPayload.log 字段中。为了改进查询、分析和可观测性，您可以将 Ray 集群配置为以结构化 JSON 格式生成日志。这种增强型格式会将日志解析为详细的键值对，从而能够基于 task_id 和 job_id 等属性进行更快的基于字段的查询。增强型结构化日志记录提供正确的严重性标签，防止多行日志拆分，并与 Cloud Logging 功能无缝集成，以改进分析和调试。

如需启用结构化 JSON 输出，请完成以下步骤：

1. 为 Ray 集群启用 日志收集

2. 在 RayCluster YAML 清单中的 Ray 容器规范中设置以下环境变量：

   1. RAY_LOGGING_CONFIG_ENCODING="JSON"：将 Ray 应用日志（Ray Core、参与者和任务）配置为使用结构化 JSON 编码。
   2. RAY_BACKEND_LOG_JSON="1"：将 Ray 系统日志（例如来自 GCS 服务器和 Raylet 的日志）配置为以结构化 JSON 格式生成。

   例如，以下 RayCluster 清单在 headGroupSpec 和 workerGroupSpecs 规范中包含所有 Ray 容器的 env 部分：

   # Example snippet for a RayCluster manifest
   apiVersion: ray.io/v1
   kind: RayCluster
   metadata:
     name: raycluster-structured
   spec:
     headGroupSpec:
       template:
         spec:
           containers:
           - name: ray-head
             image: rayproject/ray:2.54.0 # Replace with your desired Ray image
             # ... other container settings
             env:
             - name: RAY_LOGGING_CONFIG_ENCODING
               value: "JSON"
             - name: RAY_BACKEND_LOG_JSON
               value: "1"
     workerGroupSpecs:
     - groupName: small-group
       replicas: 1
       minReplicas: 1
       maxReplicas: 5
       template:
         spec:
           containers:
           - name: ray-worker
             image: rayproject/ray:2.54.0 # Replace with your desired Ray image
             # ... other container settings
             env:
             - name: RAY_LOGGING_CONFIG_ENCODING
               value: "JSON"
             - name: RAY_BACKEND_LOG_JSON
               value: "1"
   

3. 应用更新后的 RayCluster 清单： kubectl apply -f your-raycluster.yaml

结构化日志的查询

resource.type="k8s_container"
labels."k8s-pod/ray_io/is-ray-node"="yes"
severity=ERROR
jsonPayload.job_id="YOUR_JOB_ID"

resource.type="k8s_container"
labels."k8s-pod/ray_io/is-ray-node"="yes"
jsonPayload.worker_id="YOUR_WORKER_ID"

resource.type="k8s_container"
resource.labels.pod_name="YOUR_WORKER_POD_NAME"
labels."k8s-pod/ray_io/is-ray-node"="yes" 
severity=ERROR
jsonPayload.task_id="YOUR_TASK_ID"

对 Ray 集群启用指标收集

您可以在使用新的或现有 Autopilot 或 Standard GKE 集群的情况下，对 Ray 集群启用指标收集。

对 Ray 集群启用指标收集后，GKE 会从现有 Ray 集群和新的 Ray 集群收集指标。GKE 会以 Prometheus 格式收集 Ray 导出的所有系统指标。

您可以使用Google Cloud 控制台或 gcloud CLI 对 Ray 集群启用指标收集。

gcloud container clusters create CLUSTER_NAME \
    --location=LOCATION \
    --addons=RayOperator \
    --enable-ray-cluster-monitoring

查看 Ray 指标

Google Cloud Managed Service for Prometheus 提供预配置的 GKE 上的 Ray 概览信息中心，可集中查看关键 Ray 指标。建议您使用此方法快速开始监控 GKE 上的 Ray 集群。

前往“GKE 上的 Ray 概览”信息中心

当您为 Ray 集群启用指标收集时，系统会自动填充信息中心。

或者，如果您想探索从 GKE 上运行的 Ray 集群收集的各个指标，请按照以下步骤操作：

1. 前往 Google Cloud 控制台中的 Metrics Explorer 页面。

   进入 Metrics Explorer

2. 在选择指标字段中，您可以搜索 Ray 特定的指标。 这些指标通常以 prometheus/ray_ 为前缀。例如 prometheus/ray_worker_cpu_seconds_total 或 prometheus/ray_memory_bytes_max。

3. 您可以选择相应的资源类型（例如 k8s_pod、k8s_container）并按与 Ray 集群相关的标签（例如 ray.io/cluster）进行过滤，从而进一步细化搜索条件。

后续步骤

• 了解 Ray on Kubernetes。
• 浏览 KubeRay 文档。