旧版 Prometheus 辅助信息文件

Prometheus 公开格式是许多应用（尤其是 Kubernetes 上的应用）用于导出指标的惯例格式。Prometheus 是一种开源监控工具，广泛用于收集、存储和查询此类指标。我们提供了多种将 Prometheus 样式的指标与 Cloud Monitoring 集成的方法。

方法	支持情况	备注
Google Cloud Managed Service for Prometheus（推荐）	自行部署的版本适用于所有环境代管式集合适用于所有 Kubernetes 环境。通过 `gcloud` 实现的代管式集合适用于 GKE 1.22 版及更高版本	通过 PromQL 提供与开源生态系统的完全兼容性价格低于外部指标
带有 Stackdriver 收集器的 Prometheus 服务器	已弃用支持取决于 Prometheus 服务器版本	Prometheus 样式的指标会作为外部指标注入
GKE 工作负载指标	已弃用在 GKE 1.20.8-gke.2100 版到 1.23 版中受支持，但从 1.24 版开始停止支持	弃用期间免费

本页面的其余部分介绍了如何使用 Stackdriver 收集器配置 Prometheus 并将其与 Cloud Operations for GKE 结合使用。

集成的源代码已公开发布。

准备工作

确保您已创建启用了 Cloud Operations for GKE 的 GKE 集群，并已安装 Prometheus 服务器。

Prometheus 不提供对 Windows Server 的内置支持。如需解决此问题，您可以在其他 Linux 节点池中部署 Prometheus 服务器来捕获 Windows 指标，并将指标发送回 Linux 节点池中的 Stackdriver 收集器。

在安装 Stackdriver 收集器之前，请仔细查看以下要求：

您必须运行兼容的 Prometheus 服务器并将其配置为监控集群中的应用。如需了解如何在集群上安装 Prometheus，请参阅 Prometheus 入门指南。
您必须将集群配置为使用 Cloud Operations for GKE。如需查看相关说明，请参阅安装 Cloud Operations for GKE。
您必须具有集群的 Kubernetes Engine Cluster Admin 角色。如需了解详情，请参阅 GKE 角色。
您必须确保您的服务帐号具有适当的权限。如需了解详情，请参阅为节点使用最小权限服务帐号。

安装收集器

如需部署 Stackdriver 收集器，请执行以下操作：

根据名称和控制器类型确定要更新的对象。仅支持 deployment 和 statefulset 控制器类型。
设置以下环境变量：
- KUBE_NAMESPACE：运行脚本的命名空间
- KUBE_CLUSTER：辅助信息文件的集群名称参数。
- GCP_REGION：辅助信息文件的 Google Cloud 区域参数。
- GCP_PROJECT：辅助信息文件的 Google Cloud 项目参数。
- DATA_DIR：辅助信息文件的数据目录。该目录包含您的 Prometheus 服务器写入的共享卷。在后续说明中，此变量设置为值 /data。
- DATA_VOLUME：包含 Prometheus 数据的 DATA_DIR 中的共享卷的名称。在后续说明中，此变量设置为 data-volume。
- SIDECAR_IMAGE_TAG：Prometheus Sidecar 的 Docker 映像版本。您可以在 Container Registry 中找到最新版本。

执行以下脚本，并提供在此过程的初始步骤中指定的两个参数：

kube/patch.sh

在 GitHub 上查看

#!/bin/sh

set -e
set -u

CLEAN_UP_ORPHANED_REPLICA_SETS='--clean-up-orphaned-replica-sets'
usage() {
  echo -e "Usage: $0 <deployment|statefulset> <name> [${CLEAN_UP_ORPHANED_REPLICA_SETS}]\n"
}

if [  $# -le 1 ]; then
  usage
  exit 1
fi

SHOULD_CLEAN_UP=${3:-}

# Override to use a different Docker image name for the sidecar.
export SIDECAR_IMAGE_NAME=${SIDECAR_IMAGE_NAME:-'gcr.io/stackdriver-prometheus/stackdriver-prometheus-sidecar'}

kubectl -n "${KUBE_NAMESPACE}" patch "$1" "$2" --type strategic --patch "
spec:
  template:
    spec:
      containers:
      - name: sidecar
        image: ${SIDECAR_IMAGE_NAME}:${SIDECAR_IMAGE_TAG}
        imagePullPolicy: Always
        args:
        - \"--stackdriver.project-id=${GCP_PROJECT}\"
        - \"--prometheus.wal-directory=${DATA_DIR}/wal\"
        - \"--stackdriver.kubernetes.location=${GCP_REGION}\"
        - \"--stackdriver.kubernetes.cluster-name=${KUBE_CLUSTER}\"
        #- \"--stackdriver.generic.location=${GCP_REGION}\"
        #- \"--stackdriver.generic.namespace=${KUBE_CLUSTER}\"
        ports:
        - name: sidecar
          containerPort: 9091
        volumeMounts:
        - name: ${DATA_VOLUME}
          mountPath: ${DATA_DIR}
"
if [[ "${SHOULD_CLEAN_UP}" == "${CLEAN_UP_ORPHANED_REPLICA_SETS}" ]]; then
  # Delete the replica sets from the old deployment. If the Prometheus Server is
  # a deployment that does not have `revisionHistoryLimit` set to 0, this is
  # useful to avoid PVC conflicts between the old replica set and the new one
  # that prevents the pod from entering a RUNNING state.
  kubectl -n "${KUBE_NAMESPACE}" get rs | grep "$2-" | awk '{print $1}' | xargs kubectl delete -n "${KUBE_NAMESPACE}" rs
fi

脚本成功执行后，Stackdriver 收集器将作为 sidecar 添加到在第 1 步中找到的对象的 pod。脚本中被注释掉的两行与从 GKE 集群收集指标数据无关。但是，若您要填充通用 MonitoredResource，这两行是相关的。

您必须执行其他步骤才能永久更改配置。后续部分将介绍这些步骤。

验证安装

如需验证 Stackdriver 收集器是否安装，请运行以下命令：

kubectl -n "${KUBE_NAMESPACE}" get <deployment|statefulset> <name> -o=go-template='{{$output := "stackdriver-prometheus-sidecar does not exist."}}{{range .spec.template.spec.containers}}{{if eq .name "sidecar"}}{{$output = (print "stackdriver-prometheus-sidecar exists. Image: " .image)}}{{end}}{{end}}{{printf $output}}{{"\n"}}'

成功安装 Prometheus Sidecar 后，脚本输出会列出容器注册表中使用的映像。在以下示例中，映像版本为 0.4.3。在安装过程中，版本可能会有所不同：
```
stackdriver-prometheus-sidecar exists. Image: gcr.io/stackdriver-prometheus/stackdriver-prometheus-sidecar:0.4.3
```

否则，脚本的输出会显示以下内容：

stackdriver-prometheus-sidecar does not exist.

如需确定工作负载是否最新并且可用，请运行以下命令：

kubectl -n "${KUBE_NAMESPACE}" get <deployment|statefulset> <name>

将配置更改永久化

验证收集器已成功安装后，更新集群配置使更改永久化：

将 Prometheus 服务器配置为写入共享卷。在以下示例步骤中，假设 DATA_DIR 设置为 /data，DATA_VOLUME 设置为 data-volume：
1. 确保 Prometheus Pod 中有一个共享卷：
```
volumes:
  - name: data-volume
    emptyDir: {}
```
2. 让 Prometheus 将卷装载到 /data 下：
```
volumeMounts:
- name: data-volume
  mountPath: /data
```
3. 通过将以下内容添加到其容器 args 中，指示 Prometheus 服务器向 /data 中的共享卷写入数据：
```
--storage.tsdb.path=/data
```

使用您用于管理工作负载配置的工具，将配置重新应用到集群，并将 Stackdriver 收集器容器作为 sidecar 添加到新配置中：

- name: sidecar
  image: gcr.io/stackdriver-prometheus/stackdriver-prometheus-sidecar:[SIDECAR_IMAGE_TAG]
  args:
  - "--stackdriver.project-id=[GCP_PROJECT]"
  - "--prometheus.wal-directory=/data/wal"
  - "--prometheus.api-address=[API_ADDRESS]"
  - "--stackdriver.kubernetes.location=[GCP_REGION]"
  - "--stackdriver.kubernetes.cluster-name=[KUBE_CLUSTER]"
  ports:
  - name: sidecar
    containerPort: 9091
  volumeMounts:
  - name: data-volume
    mountPath: /data

在上面的表达式中，[API_ADDRESS] 是指 Prometheus 的 API 地址，通常为 http://127.0.0.1:9090。

如需了解收集器的其他配置详情，请参阅 Stackdriver Prometheus Sidecar 文档。

查看指标

Prometheus 配置为将指标作为外部指标导出到 Google Cloud 的运维套件。

要查看这些指标：

在控制台中，选择 Monitoring：

转到 Monitoring
在 Monitoring 导航窗格中，点击 Metrics Explorer。
在“查找资源类型和指标”菜单中：
- 选择 Kubernetes 容器（k8s_container）作为资源类型。
- 对于指标字段，请选择带有前缀 external/prometheus/ 的指标。例如，您可以选择 external/prometheus/go_memstats_alloc_bytes。
在以下示例中，添加了一个过滤条件以显示特定集群的指标。如果您有多个集群，则按集群名称过滤非常有用：

管理由 Prometheus 派生的指标所产生的费用

通常，Prometheus 会收集应用导出的所有指标，并且默认情况下，Stackdriver 收集器会将这些指标发送到 Cloud Monitoring。此集合包含由您的应用所依赖的库导出的指标。例如，Prometheus 客户端库会导出许多关于应用环境的指标。

您可以在 Stackdriver 收集器中配置过滤条件，以选择将哪些指标提取到 Cloud Monitoring 中。例如，要仅导入由 kubernetes-pods 和 kubernetes-service-endpoints 生成的这些指标，请在启动 Stackdriver-prometheus-sidecar 时添加以下 --include 语句：

 --include={job=~"kubernetes-pods|kubernetes-service-endpoints"}

如需了解详情，请参阅 Stackdriver Prometheus 辅助信息文件文档。

您还可以估算这些指标对帐单的影响。

Prometheus 集成问题

Cloud Monitoring 中没有显示数据。

如果您在完成安装步骤后，Cloud Monitoring 中没有显示任何数据，请在收集器日志中搜索错误消息。

如果日志未包含任何明显的失败消息，请通过将 --log.level=debug 标志传递给收集器，启用调试日志记录。您必须重启收集器使日志记录更改生效。重启收集器后，在收集器日志中搜索错误消息。

若要验证数据是否已发送到 Cloud Monitoring，您可以使用 --stackdriver.store-in-files-directory 命令行参数向文件发送请求，然后检查此目录中的文件。

没有权限

如果您看到 Monitoring API 的“没有权限”错误，请查看准备工作中所述的要求。请确保您的服务帐号具有正确的权限。如果您使用 Workload Identity，请务必在 KSA 和 GSA 之间创建关系。

我正在使用记录规则，但 Cloud Monitoring 中未显示指标。

在使用记录角色时，尽可能将原始指标提取到 Cloud Monitoring 中，并使用 Cloud Monitoring 功能在创建图表或信息中心时聚合数据。

如果无法提取原始指标，请在收集器的配置中添加 static_metadata 条目。此选项要求您保留 job 和 instance 标签。例如，当前配置有效：

您的 Prometheus 服务器配置：

groups:
- name: my-groups
  rules:
  - record: backlog_avg_10m
    expr: avg_over_time(backlog_k8s[10m])
  - record: backlog_k8s
    expr: sum(total_lag) by (app, job, instance)

您的 Prometheus 收集器配置：

static_metadata:
  - metric: backlog_avg_10m
    type: gauge

不支持更改或移除 job 或 instance 标签的记录规则。

我的指标缺少 job 和 instance Prometheus 标签。

Stackdriver Prometheus 收集器利用众所周知的 Prometheus 标签为您的 Kubernetes 对象构建 Cloud Monitoring MonitoredResource。在您更改标签描述符时，收集器无法将指标写入 Monitoring。

我在日志中看到“duplicate time series”或“out-of-order writes”错误。

如果两次将指标数据写入相同的时间序列，则会导致这些错误。当您的 Prometheus 端点两次使用单个 Cloud Monitoring 所监控的资源中的相同指标时，就会发生这种情况。

例如，一个 Kubernetes 容器可能会在多个端口发送 Prometheus 指标。由于 Monitoring k8s_container 监控的资源不会根据端口区分资源，因此 Monitoring 检测到的结果是您将两个点写入相同的时间序列。要避免这种情况，请在 Prometheus 中添加用于区分时间序列的指标标签。例如，您可以使用标签 __meta_kubernetes_pod_annotation_prometheus_io_port，因为它在容器重启过程中保持不变。

我在日志中看到“metric kind must be X, but is Y”错误。

这些错误是由更改现有指标描述符的 Prometheus 指标类型引起的。Cloud Monitoring 指标分类严格，并且不支持在仪表盘、计数器等之间更改指标类型。

若要更改指标的类型，您必须删除相应的指标描述符并创建新的描述符。删除指标描述符会导致无法访问现有时间序列数据。

我确定之前看过 Prometheus 指标类型，但现在找不到了！

Prometheus 已预先配置为将指标作为外部指标导出到 Cloud Monitoring。导出数据时，Monitoring 会为外部指标创建适当的指标描述符。如果系统至少 24 个月没有写入该指标类型的数据，则指标描述符可能会被删除。

无法保证未使用的指标描述符在 24 个月后会被删除，但 Monitoring 保留删除过去 24 个月中未使用的任何 Prometheus 指标描述符的权利。

弃用政策

Prometheus 与 Cloud Monitoring 的集成受代理弃用政策的约束。