使用 Prometheus 和 Grafana#

本节将描述如何使用 Prometheus 和 Grafana 监控 Kubernetes 中的 Ray 集群。

如果你对 Kubernetes 上的 Prometheus 和 Grafana 没有任何经验，请观看这个 YouTube 播放列表。

准备#

克隆 KubeRay 仓库并检出 master 分支。本教程需要仓库中的几个文件。

步骤 1：使用 Kind 创建一个 Kubernetes 集群#

kind create cluster

步骤 2：通过 Helm chart 安装 Kubernetes Prometheus Stack#

# Path: kuberay/
./install/prometheus/install.sh

# Check the installation
kubectl get all -n prometheus-system

# (part of the output)
# NAME                                                  READY   UP-TO-DATE   AVAILABLE   AGE
# deployment.apps/prometheus-grafana                    1/1     1            1           46s
# deployment.apps/prometheus-kube-prometheus-operator   1/1     1            1           46s
# deployment.apps/prometheus-kube-state-metrics         1/1     1            1           46s

KubeRay 提供了一个 install.sh 脚本来安装 kube-prometheus-stack v48.2.1 图表及相关自定义资源，包括 ServiceMonitor、PodMonitor 和 PrometheusRule，在 prometheus-system 命名空间中自动安装。
我们对 kube-prometheus-stack 图表中的原始 values.yaml 进行了一些修改，以允许在 Ray Dashboard 中嵌入 Grafana 面板。更多详情请参见 overrides.yaml。
```
grafana:
  grafana.ini:
    security:
      allow_embedding: true
    auth.anonymous:
      enabled: true
      org_role: Viewer
```

步骤 3：安装 KubeRay 操作员#

按照此文档通过 Helm 仓库安装最新稳定版本的 KubeRay 操作员。

步骤 4：安装 Ray 集群#

# path: ray-operator/config/samples/
kubectl apply -f ray-cluster.embed-grafana.yaml

# Check ${RAYCLUSTER_HEAD_POD}
kubectl get pod -l ray.io/node-type=head

# Example output:
# NAME                            READY   STATUS    RESTARTS   AGE
# raycluster-kuberay-head-btwc2   1/1     Running   0          63s

# Wait until all Ray Pods are running and forward the port of the Prometheus metrics endpoint in a new terminal.
kubectl port-forward ${RAYCLUSTER_HEAD_POD} 8080:8080
curl localhost:8080

# Example output (Prometheus metrics format):
# # HELP ray_spill_manager_request_total Number of {spill, restore} requests.
# # TYPE ray_spill_manager_request_total gauge
# ray_spill_manager_request_total{Component="raylet",NodeAddress="10.244.0.13",Type="Restored",Version="2.0.0"} 0.0

# Ensure that the port (8080) for the metrics endpoint is also defined in the head's Kubernetes service.
kubectl get service

# NAME                          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                                         AGE
# raycluster-kuberay-head-svc   ClusterIP   10.96.201.142   <none>        6379/TCP,8265/TCP,8080/TCP,8000/TCP,10001/TCP   106m

KubeRay 默认通过内置的导出器在端口 8080 暴露一个 Prometheus 指标端点。因此，我们不需要安装任何外部导出器。
如果你想将指标端点配置到不同的端口，请参阅 kuberay/#954 了解更多详情。
Prometheus 指标格式：
- # HELP: 描述此指标的含义。
- # TYPE: 更多详情请参见此文档。
在 ray-cluster.embed-grafana.yaml 中定义了三个必需的环境变量。有关这些环境变量的更多详细信息，请参阅配置和管理 Ray 仪表板。
```
env:
  - name: RAY_GRAFANA_IFRAME_HOST
    value: http://127.0.0.1:3000
  - name: RAY_GRAFANA_HOST
    value: http://prometheus-grafana.prometheus-system.svc:80
  - name: RAY_PROMETHEUS_HOST
    value: http://prometheus-kube-prometheus-prometheus.prometheus-system.svc:9090
```
- 请注意，我们不在 head Pod 中部署 Grafana，因此我们需要设置 RAY_GRAFANA_IFRAME_HOST 和 RAY_GRAFANA_HOST。RAY_GRAFANA_HOST 由 head Pod 用于向 Grafana 的后端发送健康检查请求。RAY_GRAFANA_IFRAME_HOST 由您的浏览器用于从 Grafana 服务器获取 Grafana 面板，而不是从 head Pod 获取。因为在这个例子中我们将 Grafana 的端口转发到 127.0.0.1:3000，所以我们设置 RAY_GRAFANA_IFRAME_HOST 为 http://127.0.0.1:3000。
- http:// 是必需的。

步骤 5：使用 ServiceMonitor 收集头节点指标#

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: ray-head-monitor
  namespace: prometheus-system
  labels:
    # `release: $HELM_RELEASE`: Prometheus can only detect ServiceMonitor with this label.
    release: prometheus
spec:
  jobLabel: ray-head
  # Only select Kubernetes Services in the "default" namespace.
  namespaceSelector:
    matchNames:
      - default
  # Only select Kubernetes Services with "matchLabels".
  selector:
    matchLabels:
      ray.io/node-type: head
  # A list of endpoints allowed as part of this ServiceMonitor.
  endpoints:
    - port: metrics
  targetLabels:
  - ray.io/cluster

上面的 YAML 示例是 serviceMonitor.yaml，它是由 install.sh 创建的。因此，这里不需要创建任何东西。
有关配置的更多详细信息，请参阅 ServiceMonitor 官方文档。
release: $HELM_RELEASE: Prometheus 只能检测带有此标签的 ServiceMonitor。

helm ls -n prometheus-system
# ($HELM_RELEASE is "prometheus".)
# NAME            NAMESPACE               REVISION        UPDATED                                 STATUS          CHART                           APP VERSION
# prometheus      prometheus-system       1               2023-02-06 06:27:05.530950815 +0000 UTC deployed        kube-prometheus-stack-44.3.1    v0.62.0

kubectl get prometheuses.monitoring.coreos.com -n prometheus-system -oyaml
# serviceMonitorSelector:
#   matchLabels:
#     release: prometheus
# podMonitorSelector:
#   matchLabels:
#     release: prometheus
# ruleSelector:
#   matchLabels:
#     release: prometheus

namespaceSelector 和 seletor 用于选择导出器的 Kubernetes 服务。由于 Ray 使用内置的导出器，ServiceMonitor 会选择 Ray 的头服务，该服务暴露了指标端点（即这里的端口 8080）。

kubectl get service -n default -l ray.io/node-type=head
# NAME                          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                                         AGE
# raycluster-kuberay-head-svc   ClusterIP   10.96.201.142   <none>        6379/TCP,8265/TCP,8080/TCP,8000/TCP,10001/TCP   153m

targetLabels: 我们添加了 spec.targetLabels[0].ray.io/cluster，因为我们希望在由这个 ServiceMonitor 生成的指标中包含 RayCluster 的名称。ray.io/cluster 标签是 Ray 头节点服务的一部分，它将被转换为 ray_io_cluster 指标标签。也就是说，任何将被导入的指标，都将包含以下标签 ray_io_cluster=<ray-cluster-name>。这看起来可能是可选的，但如果您部署了多个 RayClusters，它就变得强制性了。

步骤 6：使用 PodMonitors 收集工作节点指标#

KubeRay 操作器不会为 Ray 工作 Pod 创建 Kubernetes 服务，因此我们无法使用 Prometheus ServiceMonitor 从工作 Pod 中抓取指标。要收集工作指标，我们可以使用 Prometheus PodMonitors CRD 代替。

注意: 我们可以创建一个带有选择器的 Kubernetes 服务，从我们的工作 Pod 中选择一个公共标签子集，然而，这不是理想的做法，因为我们的工作 Pod 是相互独立的，也就是说，它们不是由副本集控制器生成的副本集合。因此，我们应该避免使用 Kubernetes 服务将它们分组在一起。

apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: ray-workers-monitor
  namespace: prometheus-system
  labels:
    # `release: $HELM_RELEASE`: Prometheus can only detect PodMonitor with this label.
    release: prometheus
    ray.io/cluster: raycluster-kuberay # $RAY_CLUSTER_NAME: "kubectl get rayclusters.ray.io"
spec:
  jobLabel: ray-workers
  # Only select Kubernetes Pods in the "default" namespace.
  namespaceSelector:
    matchNames:
      - default
  # Only select Kubernetes Pods with "matchLabels".
  selector:
    matchLabels:
      ray.io/node-type: worker
  # A list of endpoints allowed as part of this PodMonitor.
  podMetricsEndpoints:
  - port: metrics

release: $HELM_RELEASE: Prometheus 只能检测带有此标签的 PodMonitor。更多详情请参见这里。

PodMonitor 在 namespaceSelector 和 selector 中用于选择 Kubernetes Pod。

kubectl get pod -n default -l ray.io/node-type=worker
# NAME                                          READY   STATUS    RESTARTS   AGE
# raycluster-kuberay-worker-workergroup-5stpm   1/1     Running   0          3h16m

ray.io/cluster: $RAY_CLUSTER_NAME: 我们还通过手动添加 ray.io/cluster: <ray-cluster-name> 来定义 metadata.labels，然后指示 PodMonitors 资源通过 spec.podTargetLabels[0].ray.io/cluster 在抓取的指标中添加该标签。

步骤 7：使用记录规则收集自定义指标#

记录规则允许我们预计算频繁需要或计算量大的 PromQL 表达式，并将结果保存为自定义指标。注意这与旨在提高 ray 应用程序可见性的自定义应用级指标不同。

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: ray-cluster-gcs-rules
  namespace: prometheus-system
  labels:
    # `release: $HELM_RELEASE`: Prometheus can only detect Recording Rules with this label.
    release: prometheus
spec:
  groups:
- #  Rules within a group are run periodically with the same evaluation interval(30s in this example).
    name: ray-cluster-main-staging-gcs.rules
    # How often rules in the group are evaluated.
    interval: 30s
    rules:
    - # The name of the custom metric.
      # Also see best practices for naming metrics created by recording rules:
      # https://prometheus.io/docs/practices/rules/#recording-rules
      record: ray_gcs_availability_30d
      # PromQL expression.
      expr: |
      (
        100 * (
          sum(rate(ray_gcs_update_resource_usage_time_bucket{container="ray-head", le="20.0"}[30d]))
          /
          sum(rate(ray_gcs_update_resource_usage_time_count{container="ray-head"}[30d]))
        )
      )

上面的PromQL表达式是：$$\frac{ 过去30天内RTT小于20毫秒的更新资源使用RPC数量\ }{过去30天内更新资源使用RPC总数\ } \times 100 $$
上述记录规则是定义在 prometheusRules.yaml 中的规则之一，并且它是由 install.sh 创建的。因此，这里不需要创建任何东西。
有关配置的更多详细信息，请参阅 PrometheusRule 官方文档。
release: $HELM_RELEASE: Prometheus 只能检测带有此标签的 PrometheusRule。更多详情请参见这里。
PrometheusRule 可以在运行时重新加载。如果需要重新配置规则，请使用 kubectl apply {modified prometheusRules.yaml}。

步骤 8：使用告警规则定义告警条件#

告警规则允许我们基于 PromQL 表达式定义告警条件，并将触发的告警通知发送给 Alertmanager，后者在简单的告警定义基础上增加了汇总、通知速率限制、静默和告警依赖关系处理。

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: ray-cluster-gcs-rules
  namespace: prometheus-system
  labels:
    # `release: $HELM_RELEASE`: Prometheus can only detect Alerting Rules with this label.
    release: prometheus
spec:
  groups:
  - name: ray-cluster-main-staging-gcs.rules
    # How often rules in the group are evaluated.
    interval: 30s
    rules:
    - alert: MissingMetricRayGlobalControlStore
      # A set of informational labels. Annotations can be used to store longer additional information compared to rules.0.labels.
      annotations:
        description: Ray GCS is not emitting any metrics for Resource Update requests
        summary: Ray GCS is not emitting metrics anymore
      # PromQL expression.
      expr: |
                      (
                       absent(ray_gcs_update_resource_usage_time_bucket) == 1
                      )
      # Time that Prometheus will wait and check if the alert continues to be active during each evaluation before firing the alert.
      # firing alerts may be due to false positives or noise if the setting value is too small.
      # On the other hand, if the value is too big, the alerts may not be handled in time.
      for: 5m
      # A set of additional labels to be attached to the alert.
      # It is possible to overwrite the labels in metadata.labels, so make sure one of the labels match the label in ruleSelector.matchLabels.
      labels:
        severity: critical

上述 PromQL 表达式检查是否不存在 ray_gcs_update_resource_usage_time_bucket 指标的时间序列。更多详情请参见 absent()。
上述告警规则是定义在 prometheusRules.yaml 中的规则之一，并且它是由 install.sh 创建的。因此，这里不需要创建任何东西。
报警规则的配置方式与记录规则相同。

步骤 9：访问 Prometheus Web UI#

# Forward the port of Prometheus Web UI in the Prometheus server Pod.
kubectl port-forward prometheus-prometheus-kube-prometheus-prometheus-0 -n prometheus-system 9090:9090

访问 ${YOUR_IP}:9090/targets (例如 127.0.0.1:9090/targets)。你应该能够看到：
- podMonitor/prometheus-system/ray-workers-monitor/0 (1/1 运行中)
- serviceMonitor/prometheus-system/ray-head-monitor/0 (1/1 运行中)

Prometheus Web UI

前往 ${YOUR_IP}:9090/graph。你应该能够查询：
- 系统指标
- 应用层指标
- 在记录规则中定义的自定义指标（例如 ray_gcs_availability_30d）
前往 ${YOUR_IP}:9090/alerts。你应该能够看到：
- 告警规则 (例如 MissingMetricRayGlobalControlStore)。

步骤 10：访问 Grafana#

# Forward the port of Grafana
kubectl port-forward deployment/prometheus-grafana -n prometheus-system 3000:3000
# Note: You need to update `RAY_GRAFANA_IFRAME_HOST` if you expose Grafana to a different port.

# Check ${YOUR_IP}:3000/login for the Grafana login page (e.g. 127.0.0.1:3000/login).
# The default username is "admin" and the password is "prom-operator".

注意：kubectl port-forward 不推荐用于生产环境。请参考这份 Grafana 文档了解如何在反向代理后暴露 Grafana。

默认密码由 kube-prometheus-stack 图表的 values.yaml 中的 grafana.adminPassword 定义。
成功登录Grafana后，我们可以通过 dashboard_default.json 将Ray Dashboard导入Grafana。
- 点击左侧面板中的“仪表板”图标。
- 点击“新建”。
- 点击“导入”。
- 点击“上传 JSON 文件”。
- 选择一个 JSON 文件。
  - 如果你使用的是 Ray 2.9.0，你可以使用 GitHub 仓库中的示例配置文件。文件名遵循 xxx_grafana_dashboard.json 的模式。
  - 案例 2：否则，你应该从 head Pod 中的 /tmp/ray/session_latest/metrics/grafana/dashboards/ 导入 JSON 文件。你可以使用 kubectl cp 将文件从 head Pod 复制到你的本地机器。
- 点击“导入”。
TODO: 请注意，手动导入仪表板不是理想的做法。我们应该找到一种自动导入仪表板的方法。

Grafana Ray 仪表盘

步骤 11：在 Ray 仪表盘中嵌入 Grafana 面板#

kubectl port-forward svc/raycluster-embed-grafana-head-svc 8265:8265
# Visit http://127.0.0.1:8265/#/metrics in your browser.

带有 Grafana 面板的 Ray 仪表板