收集及查看 Google Kubernetes Engine (GKE) 上 Ray 叢集的記錄和指標

本頁說明如何設定 Google Kubernetes Engine (GKE)，收集在 Google Kubernetes Engine (GKE) 上執行的 Ray 叢集記錄和指標，以及如何在 Cloud Logging 和 Cloud Monitoring 中查看 Ray 記錄和指標。

如要進一步瞭解 Ray 和 KubeRay，請參閱 Google Kubernetes Engine (GKE) 上的 Ray 總覽。

事前準備

開始之前，請務必先完成下列工作：

• 啟用 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 運算子。

需求條件和限制

• 您必須先在現有 GKE 叢集上啟用系統和工作負載記錄功能，才能為 Ray 叢集啟用記錄收集功能。
• 如果您在現有 GKE 叢集上啟用 Ray 叢集的記錄收集功能，GKE 只會收集新建立的 Ray Pod 記錄，不會收集現有 Ray Pod 的記錄。
• 如果是 Standard GKE 叢集，您必須啟用 Google Cloud Managed Service for Prometheus，才能啟用 Ray 叢集的指標收集功能。對於 Autopilot 叢集，Google Cloud Managed Service for Prometheus 預設為啟用。
• 在 Ray 叢集中的任何 Ray 容器中，不得指定名為 ray-logs 的磁碟區。否則 GKE 不會收集記錄。
• GKE 版本 v1.35.1-gke.1616000 以上版本支援 JSON 記錄。如要啟用結構化 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

在 GKE 1.35.1-gke.1616000 以上版本中，GKE 支援將 Ray 叢集發出的結構化 JSON 記錄檔，以強化剖析方式匯入 Cloud Logging。詳情請參閱「啟用強化結構化記錄」。在舊版 GKE 中，Ray 記錄會以非結構化文字字串的形式，擷取至 Cloud Logging 的 jsonPayload.log 欄位。

查看 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 1.35.1-gke.1616000 以上版本中，Ray 運算子可以剖析結構化 JSON 格式的 Ray 記錄。這項強化剖析功能可讓您根據 task_id 和 job_id 等屬性進行查詢、提供正確的嚴重程度標籤、防止多行記錄分割，並與 Cloud Logging 功能整合，以利進行更完善的分析和偵錯。

啟用加強型結構化記錄

本節說明如何在 GKE 1.35.1-gke.1616000 至 1.37.1-gke.1442000 版本中啟用這些結構化記錄。

在 GKE 1.37.1-gke.1442000 以上版本中，啟用記錄功能的 Ray 叢集預設會啟用強化結構化記錄功能，因此您可以略過這些步驟。

預設啟用強化結構化記錄功能後，系統會將 RAY_LOGGING_CONFIG_ENCODING="JSON" 和 RAY_BACKEND_LOG_JSON="1" 環境變數插入 RayCluster YAML 資訊清單中的 Ray 容器規格，將 Ray 叢集設定為以結構化 JSON 格式產生記錄。如果已設定其中一個環境變數，系統會略過該變數的插入作業，並保留現有設定。

如要在 GKE 版本 1.35.1-gke.1616000 和 1.37.1-gke.1442000 之間啟用結構化 JSON 輸出，請完成下列步驟：

1. 為 Ray 叢集啟用記錄收集功能

2. 在 RayCluster YAML 資訊清單的 Ray 容器規格中，設定下列環境變數：

   1. RAY_LOGGING_CONFIG_ENCODING="JSON"：設定 Ray 應用程式記錄 (Ray Core、執行者和工作)，以使用結構化 JSON 編碼。
   2. RAY_BACKEND_LOG_JSON="1"：設定以結構化 JSON 格式產生 Ray 系統記錄 (例如來自 GCS 伺服器和 Raylet 的記錄)。

   舉例來說，下列 RayCluster 資訊清單包含所有 Ray 容器的 env 區段，包括 headGroupSpec 和 workerGroupSpecs 規格：

   # 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

停用加強型結構化記錄

在 GKE 1.37.1-gke.1442000 以上版本中，為 Ray 叢集啟用記錄收集功能時，系統會預設啟用強化結構化記錄。

停用強化結構化記錄後，Ray 運算子會在 Cloud Logging 的 jsonPayload.log 欄位中，以非結構化文字字串的形式擷取記錄。轉換期間不會捨棄或遺失任何記錄項目。

如要停用加強型結構化記錄，請採取下列任一做法：

• 在父項 RayCluster 自訂資源或 Pod 範本中新增註解。

  • 將註解新增至 RayCluster：

    metadata:
      annotations:
        ray.gke.io/structured-logging: "disabled"
    

  • 將註解新增至 Pod 範本：

    workerGroupSpecs:
    - groupName: small-group
      template:
        metadata:
          annotations:
            ray.gke.io/structured-logging: "disabled"
    

• 在 YAML 資訊清單的 Ray 容器規格中，設定下列環境變數：RayCluster

  env:
  - name: `RAY_LOGGING_CONFIG_ENCODING`
    value: `"TEXT"`
  - name: `RAY_BACKEND_LOG_JSON`
    value: `"0"`
  

結構化記錄的查詢

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 叢集收集指標。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 提供預先設定的「Ray on GKE 總覽」資訊主頁，集中顯示重要的 Ray 指標。建議您使用這種方式，快速開始監控 GKE 上的 Ray 叢集。

前往 Ray on GKE 總覽資訊主頁

為 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) 篩選，進一步縮小搜尋範圍。

後續步驟

• 瞭解 Kubernetes 上的 Ray。
• 參閱 KubeRay 說明文件。