開始使用 OpenTelemetry 收集器

本文說明如何設定 OpenTelemetry Collector，以便擷取標準 Prometheus 指標，並將這些指標回報至 Google Cloud Managed Service for Prometheus。OpenTelemetry Collector 是一種代理程式，您可以自行部署並設定匯出至 Managed Service for Prometheus。設定方式與使用自行部署的集合執行 Managed Service for Prometheus 相似。

您可能會選擇 OpenTelemetry 收集器，而非自行部署的收集器，原因如下：

  • 透過 OpenTelemetry Collector，您可以在管道中設定不同的匯出程式，將遙測資料路由至多個後端。
  • 收集器也支援指標、記錄和追蹤記錄的信號，因此您可以使用收集器在單一代理程式中處理所有三種信號類型。
  • OpenTelemetry 的供應商通用資料格式 (OpenTelemetry 通訊協定，或稱 OTLP) 支援強大的程式庫和可插入的收集器元件生態系統。這可讓您透過各種自訂選項接收、處理及匯出資料。

不過，執行 OpenTelemetry 收集器需要自行管理部署和維護方式，因此這些優點必須權衡利弊。您選擇的方法取決於您的具體需求，但在本文件中，我們提供建議的規範，說明如何使用 Managed Service for Prometheus 做為後端，設定 OpenTelemetry Collector。

事前準備

本節說明本文所述工作所需的設定。

設定專案和工具

如要使用 Google Cloud Managed Service for Prometheus，您需要下列資源：

  • 已啟用 Cloud Monitoring API 的 Google Cloud 專案。

    • 如果您沒有 Google Cloud 專案，請執行下列操作：

      1. 在 Google Cloud 控制台中，前往「New Project」(新增專案)：

        建立新專案

      2. 在「Project Name」欄位中輸入專案名稱，然後按一下「Create」。

      3. 前往「帳單」：

        前往「帳單」頁面

      4. 如果頁面頂端沒有顯示已選取的專案，請選取您剛建立的專案。

      5. 系統會提示您選擇現有的付款資料或是建立新的付款資料。

      新專案預設會啟用 Monitoring API。

    • 如果您已擁有 Google Cloud 專案，請確認 Monitoring API 已啟用：

      1. 前往「API 和服務」：

        前往「API 和服務」

      2. 選取專案。

      3. 點選「啟用 API 和服務」。

      4. 搜尋「監控」。

      5. 在搜尋結果中，點選「Cloud Monitoring API」。

      6. 如果畫面未顯示「API 已啟用」，請按一下「啟用」按鈕。

  • Kubernetes 叢集。如果您沒有 Kubernetes 叢集，請按照 GKE 快速入門中的操作說明進行。

您還需要下列指令列工具：

  • gcloud
  • kubectl

gcloud 和 kubectl 工具是 Google Cloud CLI 的一部分。如要瞭解如何安裝這些元件，請參閱「管理 Google Cloud CLI 元件」。如要查看已安裝的 gcloud CLI 元件，請執行下列指令：

gcloud components list

設定環境

為避免重複輸入專案 ID 或叢集名稱，請執行下列設定：

  • 請按照下列方式設定指令列工具：

    • 設定 gcloud CLI 以參照Google Cloud 專案的 ID：

      gcloud config set project PROJECT_ID

    • 設定 kubectl CLI 以使用叢集：

      kubectl config set-cluster CLUSTER_NAME

    如要進一步瞭解這些工具，請參閱下列資源：

設定命名空間

為範例應用程式建立的資源建立 NAMESPACE_NAME Kubernetes 命名空間：

kubectl create ns NAMESPACE_NAME

驗證服務帳戶憑證

如果 Kubernetes 叢集已啟用 Workload Identity Federation for GKE，您可以略過本節。

在 GKE 上執行時，Managed Service for Prometheus 會根據 Compute Engine 預設服務帳戶，自動從環境中擷取憑證。預設服務帳戶具備必要權限 monitoring.metricWriter 和 monitoring.viewer。如果您未為 GKE 使用 Workload Identity Federation，且先前已從預設節點服務帳戶移除其中任一角色，則必須重新加入缺少的權限，才能繼續操作。

設定 Workload Identity Federation for GKE 的服務帳戶

如果 Kubernetes 叢集未啟用 Workload Identity Federation for GKE，您可以略過本節。

Managed Service for Prometheus 會使用 Cloud Monitoring API 擷取指標資料。如果叢集使用 GKE 適用的工作負載身分聯盟，您必須將 Monitoring API 的權限授予 Kubernetes 服務帳戶。本節說明下列事項：

建立及繫結服務帳戶

這個步驟會出現在 Managed Service for Prometheus 說明文件的多個位置。如果您已在先前的任務中執行此步驟，則不必重複執行。請跳到「授權服務帳戶」一節。

下列指令序列會建立 gmp-test-sa 服務帳戶，並將其繫結至 NAMESPACE_NAME 命名空間中的預設 Kubernetes 服務帳戶：

gcloud config set project PROJECT_ID \
&&
gcloud iam service-accounts create gmp-test-sa \
&&
gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE_NAME/default]" \
  gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace NAMESPACE_NAME \
  default \
  iam.gke.io/gcp-service-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com

如果您使用的是其他 GKE 命名空間或服務帳戶，請視情況調整指令。

授權給服務帳戶

相關權限的群組會收集到角色中，您可以將角色授予主體，在本例中為 Google Cloud服務帳戶。如要進一步瞭解監控角色，請參閱「存取權控管」。

下列指令會授予 Google Cloud 服務帳戶 gmp-test-sa 所需的 Monitoring API 角色，以便寫入指標資料。

如果您已在先前的任務中授予 Google Cloud 服務帳戶特定角色，則不必再次執行。

gcloud projects add-iam-policy-binding PROJECT_ID\
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.metricWriter

對 GKE 適用的工作負載身分聯盟設定進行偵錯

如果您無法順利使用 Workload Identity Federation for GKE，請參閱相關文件，瞭解如何驗證 Workload Identity Federation for GKE 設定，以及Workload Identity Federation for GKE 疑難排解指南。

由於輸入錯誤和部分複製貼上作業是設定 GKE 工作負載身分識別聯邦的常見錯誤來源，因此我們強烈建議您使用這些操作說明中程式碼範例內建的可編輯變數和可點選的複製貼上圖示。

在實際工作環境中使用 Workload Identity Federation for GKE

本文所述範例會將 Google Cloud 服務帳戶繫結至預設 Kubernetes 服務帳戶，並授予 Google Cloud服務帳戶使用 Monitoring API 所需的所有權限。

在正式環境中，您可能會想採用更精細的方法，為每個元件建立服務帳戶，並為每個服務帳戶授予最基本的權限。如要進一步瞭解如何設定服務帳戶以管理工作負載身分，請參閱「使用 GKE 適用的工作負載身分聯盟」。

設定 OpenTelemetry 收集器

本節將逐步引導您設定及使用 OpenTelemetry Collector，從範例應用程式擷取指標，並將資料傳送至 Google Cloud Managed Service for Prometheus。如需詳細設定資訊，請參閱以下各節：

OpenTelemetry Collector 類似於 Managed Service for Prometheus 代理程式二進位檔。OpenTelemetry 社群會定期發布版本，包括原始碼、二進位檔和容器映像檔。

您可以使用最佳做法預設值，在 VM 或 Kubernetes 叢集中部署這些構件，也可以使用收集器建構工具，自行建構收集器，只包含所需的元件。如要建構收集器，以便與 Managed Service for Prometheus 搭配使用，您需要下列元件：

  • Managed Service for Prometheus 匯出器，可將指標寫入 Managed Service for Prometheus。
  • 用來擷取指標的接收器。本文假設您使用的是 OpenTelemetry Prometheus 接收器，但 Managed Service for Prometheus 匯出器與任何 OpenTelemetry 指標接收器皆相容。
  • 處理器可依據環境批次處理及標記指標，以便納入重要資源 ID。

您可以使用設定檔啟用這些元件，並透過 --config 標記將其傳遞至收集器。

以下各節將詳細說明如何設定這些元件。本文說明如何在 GKE 和其他地方執行收集器。

設定及部署收集器

無論您是在 Google Cloud 上還是在其他環境中執行收集作業，都可以設定 OpenTelemetry Collector 將資料匯出至 Managed Service for Prometheus。最大的差異在於收集器的設定方式。在非Google Cloud 環境中，指標資料可能需要額外的格式設定，才能與 Prometheus 的 Managed Service 相容。不過，在 Google Cloud上，收集器可以自動偵測大部分的格式設定。

在 GKE 上執行 OpenTelemetry Collector

您可以將下列設定複製到名為 config.yaml 的檔案中，在 GKE 上設定 OpenTelemetry Collector：

receivers:
  prometheus:
    config:
      scrape_configs:
      - job_name: 'SCRAPE_JOB_NAME'
        kubernetes_sd_configs:
        - role: pod
        relabel_configs:
        - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_name]
          action: keep
          regex: prom-example
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
          action: replace
          target_label: __metrics_path__
          regex: (.+)
        - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
          action: replace
          regex: (.+):(?:\d+);(\d+)
          replacement: $$1:$$2
          target_label: __address__
        - action: labelmap
          regex: __meta_kubernetes_pod_label_(.+)

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  transform:
    # "location", "cluster", "namespace", "job", "instance", and "project_id" are reserved, and
    # metrics containing these labels will be rejected.  Prefix them with exported_ to prevent this.
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

# Note that the googlemanagedprometheus exporter block is intentionally blank
exporters:
  googlemanagedprometheus:

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [batch, memory_limiter, resourcedetection, transform]
      exporters: [googlemanagedprometheus]

上述設定會使用 Prometheus 接收器和 Managed Service for Prometheus 匯出器，在 Kubernetes Pod 上抓取指標端點，並將這些指標匯出至 Managed Service for Prometheus。管道處理器會將資料格式化並分批處理。

如要進一步瞭解此設定的各個部分的作用，以及不同平台的設定，請參閱以下有關擷取指標和新增處理器的詳細說明。

將現有的 Prometheus 設定與 OpenTelemetry Collector 的 prometheus 接收器搭配使用時，請將任何單一美元符號字元 替換為雙字元 ，以免觸發環境變數替換作業。詳情請參閱「擷取 Prometheus 指標」。

您可以根據環境、供應器和要擷取的指標修改此設定，但在 GKE 上執行時，建議您從範例設定開始。

在 Google Cloud外執行 OpenTelemetry 收集器

在 Google Cloud以外 (例如內部部署或其他雲端服務供應商) 執行 OpenTelemetry 收集器，與在 GKE 上執行收集器類似。不過，您擷取的指標不太可能自動納入最適合 Managed Service for Prometheus 的資料格式。因此，您必須特別小心設定收集器，以便將指標格式化，使其與 Managed Service for Prometheus 相容。

您可以將下列設定加入名為 config.yaml 的檔案中，設定 OpenTelemetry Collector，以便在非 GKE Kubernetes 叢集中部署：

receivers:
  prometheus:
    config:
      scrape_configs:
      - job_name: 'SCRAPE_JOB_NAME'
        kubernetes_sd_configs:
        - role: pod
        relabel_configs:
        - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_name]
          action: keep
          regex: prom-example
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
          action: replace
          target_label: __metrics_path__
          regex: (.+)
        - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
          action: replace
          regex: (.+):(?:\d+);(\d+)
          replacement: $$1:$$2
          target_label: __address__
        - action: labelmap
          regex: __meta_kubernetes_pod_label_(.+)

processors:
  resource:
    attributes:
    - key: "cluster"
      value: "CLUSTER_NAME"
      action: upsert
    - key: "namespace"
      value: "NAMESPACE_NAME"
      action: upsert
    - key: "location"
      value: "REGION"
      action: upsert

  transform:
    # "location", "cluster", "namespace", "job", "instance", and "project_id" are reserved, and
    # metrics containing these labels will be rejected.  Prefix them with exported_ to prevent this.
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

exporters:
  googlemanagedprometheus:
    project: "PROJECT_ID"

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [batch, memory_limiter, resource, transform]
      exporters: [googlemanagedprometheus]

這個設定會執行以下操作：

  • 為 Prometheus 設定 Kubernetes 服務探索抓取設定。詳情請參閱「擷取 Prometheus 指標」。
  • 手動設定 cluster、namespace 和 location 資源屬性。如要進一步瞭解資源屬性 (包括 Amazon EKS 和 Azure AKS 的資源偵測)，請參閱「偵測資源屬性」。
  • 在 googlemanagedprometheus 匯出工具中設定 project 選項。如要進一步瞭解匯出工具，請參閱「設定 googlemanagedprometheus 匯出工具」。

將現有的 Prometheus 設定與 OpenTelemetry Collector 的 prometheus 接收器搭配使用時，請將任何單一美元符號字元 替換為雙字元 ，以免觸發環境變數替換作業。詳情請參閱「擷取 Prometheus 指標」。

如要進一步瞭解在其他雲端設定收集器的最佳做法，請參閱 Amazon EKS 或 Azure AKS。

部署範例應用程式

範例應用程式會在其 metrics 通訊埠上發出 example_requests_total 計數器指標和 example_random_numbers 直方圖指標 (以及其他指標)。這個範例的資訊清單定義了三個備份。

如要部署範例應用程式，請執行下列指令：

kubectl -n NAMESPACE_NAME apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.15.3/examples/example-app.yaml

將收集器設定建立為 ConfigMap

建立設定檔並放入名為 config.yaml 的檔案後，請使用該檔案根據 config.yaml 檔案建立 Kubernetes ConfigMap。收集器部署後，會掛載 ConfigMap 並載入檔案。

如要使用設定檔建立名為 otel-config 的 ConfigMap，請使用下列指令：

kubectl -n NAMESPACE_NAME create configmap otel-config --from-file config.yaml

部署收集器

建立名為 collector-deployment.yaml 的檔案，並在其中加入下列內容：

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: NAMESPACE_NAME:prometheus-test
rules:
- apiGroups: [""]
  resources:
  - pods
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: NAMESPACE_NAME:prometheus-test
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: NAMESPACE_NAME:prometheus-test
subjects:
- kind: ServiceAccount
  namespace: NAMESPACE_NAME
  name: default
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: otel-collector
spec:
  replicas: 1
  selector:
    matchLabels:
      app: otel-collector
  template:
    metadata:
      labels:
        app: otel-collector
    spec:
      containers:
      - name: otel-collector
        image: otel/opentelemetry-collector-contrib:0.128.0
        args:
        - --config
        - /etc/otel/config.yaml
        - --feature-gates=exporter.googlemanagedprometheus.intToDouble
        volumeMounts:
        - mountPath: /etc/otel/
          name: otel-config
      volumes:
      - name: otel-config
        configMap:
          name: otel-config

請執行下列指令，在 Kubernetes 叢集中建立收集器部署：

kubectl -n NAMESPACE_NAME create -f collector-deployment.yaml

Pod 啟動後，會擷取範例應用程式，並將指標回報至 Managed Service for Prometheus。

如要瞭解查詢資料的方式，請參閱「使用 Cloud Monitoring 進行查詢」或「使用 Grafana 進行查詢」。

明確提供憑證

在 GKE 上執行時，OpenTelemetry Collector 會根據節點的服務帳戶，自動從環境中擷取憑證。在非 GKE Kubernetes 叢集中，您必須使用標記或 GOOGLE_APPLICATION_CREDENTIALS 環境變數，明確向 OpenTelemetry Collector 提供憑證。

  1. 將內容設定為目標專案：

    gcloud config set project PROJECT_ID

  2. 建立服務帳戶：

    gcloud iam service-accounts create gmp-test-sa

    這個步驟會建立服務帳戶，您可能已在 Workload Identity Federation for GKE 操作說明中建立此帳戶。

  3. 將必要權限授予服務帳戶：

    gcloud projects add-iam-policy-binding PROJECT_ID\
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.metricWriter

  4. 建立並下載服務帳戶金鑰：

    gcloud iam service-accounts keys create gmp-test-sa-key.json \
  --iam-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com

  5. 將金鑰檔案新增為非 GKE 叢集的密鑰：

    kubectl -n NAMESPACE_NAME create secret generic gmp-test-sa \
  --from-file=key.json=gmp-test-sa-key.json

  6. 開啟 OpenTelemetry 部署資源進行編輯：

    kubectl -n NAMESPACE_NAME edit deployment otel-collector

  1. 將粗體文字新增至資源：

    apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: NAMESPACE_NAME
  name: otel-collector
spec:
  template
    spec:
      containers:
      - name: otel-collector
        env:
        - name: "GOOGLE_APPLICATION_CREDENTIALS"
          value: "/gmp/key.json"
...
        volumeMounts:
        - name: gmp-sa
          mountPath: /gmp
          readOnly: true
...
      volumes:
      - name: gmp-sa
        secret:
          secretName: gmp-test-sa
...

  2. 儲存檔案並關閉編輯器。套用變更後，系統會重新建立 Pod，並開始使用指定的服務帳戶對指標後端進行驗證。

抓取 Prometheus 指標

本節和後續章節會提供 OpenTelemetry Collector 的其他自訂資訊。這項資訊在某些情況下可能會有所幫助，但執行「設定 OpenTelemetry 收集器」一文中所述範例時，並不需要任何這類資訊。

如果您的應用程式已公開 Prometheus 端點，OpenTelemetry Collectors 可以使用與任何標準 Prometheus 設定相同的擷取設定格式擷取這些端點。如要這麼做，請在收集器設定中啟用 Prometheus 接收器。

Kubernetes 容器的 Prometheus 接收器設定可能如下所示：

receivers:
  prometheus:
    config:
      scrape_configs:
      - job_name: 'kubernetes-pods'
        kubernetes_sd_configs:
        - role: pod
        relabel_configs:
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
          action: keep
          regex: true
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
          action: replace
          target_label: __metrics_path__
          regex: (.+)
        - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
          action: replace
          regex: (.+):(?:\d+);(\d+)
          replacement: $$1:$$2
          target_label: __address__
        - action: labelmap
          regex: __meta_kubernetes_pod_label_(.+)

service:
  pipelines:
    metrics:
      receivers: [prometheus]

這是以服務探索為基礎的擷取設定，您可以視需要修改這項設定，擷取應用程式。

將現有的 Prometheus 設定與 OpenTelemetry Collector 的 prometheus 接收器搭配使用時，請將任何單一美元符號字元 替換為雙字元 ，以免觸發環境變數替換作業。這點對於 relabel_configs 部分中的 replacement 值尤其重要。舉例來說，如果您有以下 relabel_config 區段：

- source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
  action: replace
  regex: (.+):(?:\d+);(\d+)
  replacement: $1:$2
  target_label: __address__

然後改寫為：

- source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
  action: replace
  regex: (.+):(?:\d+);(\d+)
  replacement: $$1:$$2
  target_label: __address__

詳情請參閱 OpenTelemetry 說明文件。

接下來，我們強烈建議您使用處理器來設定指標格式。在許多情況下，您必須使用處理器才能正確格式化指標。

新增處理器

OpenTelemetry 處理器會在匯出前修改遙測資料。您可以使用下列處理器，確保指標以與 Managed Service for Prometheus 相容的格式編寫。

偵測資源屬性

OpenTelemetry 的 Managed Service for Prometheus 匯出工具會使用 prometheus_target 監控的資源來明確識別時間序列資料點。匯出工具會剖析指標資料點的資源屬性，從中擷取必要的監控資源欄位。以下是擷取值的欄位和屬性：

  • project_id：由匯出程式設定中的應用程式預設憑證、gcp.project.id 或 project 自動偵測 (請參閱「設定匯出程式」)
  • 位置：location、cloud.availability_zone、cloud.region
  • 叢集：cluster、k8s.cluster_name
  • 命名空間：namespace、k8s.namespace_name
  • job：service.name + service.namespace
  • instance：service.instance.id

如果未將這些標籤設為不重複的值，匯出至 Prometheus 的 Managed Service 時，可能會發生「重複時間序列」錯誤。在許多情況下，系統可自動偵測這些標籤的值，但在某些情況下，您可能必須自行對應這些值。本節的其餘部分將說明這些情境。

Prometheus 接收器會根據刮除設定中的 job_name 自動設定 service.name 屬性，並根據刮除目標的 instance 設定 service.instance.id 屬性。接收器也會在刮除設定中使用 role: pod 時設定 k8s.namespace.name。

盡可能使用資源偵測處理器自動填入其他屬性。不過，視環境而定，系統可能無法自動偵測某些屬性。在這種情況下，您可以使用其他處理器手動插入這些值，或從指標標籤解析這些值。下列各節說明如何在不同平台上偵測資源。

GKE

在 GKE 上執行 OpenTelemetry 時，您需要啟用資源偵測處理器，才能填入資源標籤。請確認指標未包含任何預留資源標籤。如果無法避免這種情況，請參閱「透過重新命名屬性，避免資源屬性衝突」。

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

您可以直接將此區段複製到設定檔中，取代現有的 processors 區段。

Amazon EKS

EKS 資源偵測器不會自動填入 cluster 或 namespace 屬性。您可以使用資源處理器手動提供這些值，如以下範例所示：

processors:
  resourcedetection:
    detectors: [eks]
    timeout: 10s

  resource:
    attributes:
    - key: "cluster"
      value: "my-eks-cluster"
      action: upsert
    - key: "namespace"
      value: "my-app"
      action: upsert

您也可以使用 groupbyattrs 處理器將這些值從指標標籤轉換為資源標籤 (請參閱下方的「將指標標籤移至資源標籤」)。

Azure AKS

AKS 資源偵測器不會自動填入 cluster 或 namespace 屬性。您可以使用資源處理器手動提供這些值，如以下範例所示：

processors:
  resourcedetection:
    detectors: [aks]
    timeout: 10s

  resource:
    attributes:
    - key: "cluster"
      value: "my-eks-cluster"
      action: upsert
    - key: "namespace"
      value: "my-app"
      action: upsert

您也可以使用 groupbyattrs 處理器，將這些值從指標標籤轉換為資源標籤，請參閱「將指標標籤移至資源標籤」。

地端部署和非雲端環境

在內部部署或非雲端環境中，您可能無法自動偵測任何必要的資源屬性。在這種情況下，您可以在指標中發出這些標籤，並將標籤移至資源屬性 (請參閱「將指標標籤移至資源標籤」)，或是手動設定所有資源屬性，如以下範例所示：

processors:
  resource:
    attributes:
    - key: "cluster"
      value: "my-on-prem-cluster"
      action: upsert
    - key: "namespace"
      value: "my-app"
      action: upsert
    - key: "location"
      value: "us-east-1"
      action: upsert

將收集器設定做為 ConfigMap 建立一文說明如何使用設定。該部分假設您已將設定放入名為 config.yaml 的檔案中。

使用應用程式預設憑證執行收集器時，仍可自動設定 project_id 資源屬性。如果收集器無法存取應用程式預設憑證，請參閱「設定 project_id」。

或者，您也可以在環境變數 OTEL_RESOURCE_ATTRIBUTES 中手動設定所需的資源屬性，並以半形逗號分隔的鍵/值組合清單表示，例如：

export OTEL_RESOURCE_ATTRIBUTES="cluster=my-cluster,namespace=my-app,location=us-east-1"

接著，使用 env 資源偵測器處理器設定資源屬性：

processors:
  resourcedetection:
    detectors: [env]

重新命名屬性，避免資源屬性衝突

如果指標已包含與必要資源屬性 (例如 location、cluster 或 namespace) 衝突的標籤，請重新命名指標，以免發生衝突。Prometheus 慣例是將前置字串 exported_ 新增至標籤名稱。如要新增這個前置字串，請使用轉換處理工具。

下列 processors 設定會重新命名任何可能的衝突，並解決指標中任何衝突的鍵：

processors:
  transform:
    # "location", "cluster", "namespace", "job", "instance", and "project_id" are reserved, and
    # metrics containing these labels will be rejected.  Prefix them with exported_ to prevent this.
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

將指標標籤移至資源標籤

在某些情況下，由於匯出程式會監控多個命名空間，因此指標可能會刻意回報 namespace 等標籤。例如執行 kube-state-metrics 匯出程式時。

在這種情況下，您可以使用 groupbyattrs 處理器將這些標籤移至資源屬性：

processors:
  groupbyattrs:
    keys:
    - namespace
    - cluster
    - location

在前述範例中，如果指標具有 namespace、cluster 或 location 標籤，這些標籤就會轉換為相符的資源屬性。

限制 API 要求和記憶體用量

其他兩個處理器 (批次處理器和記憶體限制器處理器) 可讓您限制收集器的資源消耗量。

批次處理

您可以透過批次要求，定義單一要求中要傳送的資料點數量。請注意，Cloud Monitoring 每個要求的限制為 200 個時序。使用下列設定啟用批次處理工具：

processors:
  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

記憶體限制

建議您啟用記憶體限制器處理器，以免收集器在傳輸量高的情況下當機。使用下列設定啟用處理作業：

processors:
  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

設定 googlemanagedprometheus 匯出工具

根據預設，在 GKE 上使用 googlemanagedprometheus 匯出工具不需要額外設定。在許多用途中，您只需要在 exporters 區段中使用空白區塊即可啟用此功能：

exporters:
  googlemanagedprometheus:

不過，匯出工具會提供一些選用設定。下列各節會說明其他設定。

設定 project_id

如要將時序資料與 Google Cloud 專案建立關聯，prometheus_target 監控資源必須設有 project_id。

在 Google Cloud上執行 OpenTelemetry 時，Managed Service for Prometheus 匯出工具預設會根據找到的應用程式預設憑證設定這個值。如果沒有可用的憑證，或您想覆寫預設專案，可以採取以下兩種做法：

  • 在匯出工具設定中設定 project
  • 在指標中加入 gcp.project.id 資源屬性。

我們強烈建議您盡可能使用 project_id 的預設 (未設定) 值，而非明確設定。

在匯出工具設定中設定 project

以下設定摘錄會將指標傳送至 Google Cloud project MY_PROJECT 中的 Managed Service for Prometheus：

receivers:
  prometheus:
    config:
    ...

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

exporters:
  googlemanagedprometheus:
    project: MY_PROJECT

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [resourcedetection]
      exporters: [googlemanagedprometheus]

與先前範例唯一不同的是新行 project: MY_PROJECT。如果您知道透過這個收集器傳送的每個指標都應傳送至 MY_PROJECT，這項設定就很實用。

設定 gcp.project.id 資源屬性

您可以為指標新增 gcp.project.id 資源屬性，依指標逐一設定專案關聯。將屬性值設為指標應關聯的專案名稱。

舉例來說，如果指標已有標籤 project，您可以使用收集器設定中的處理器將這個標籤移至資源屬性，並將其重新命名為 gcp.project.id，如以下範例所示：

receivers:
  prometheus:
    config:
    ...

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  groupbyattrs:
    keys:
    - project

  resource:
    attributes:
    - key: "gcp.project.id"
      from_attribute: "project"
      action: upsert

exporters:
  googlemanagedprometheus:

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [resourcedetection, groupbyattrs, resource]
      exporters: [googlemanagedprometheus]

設定用戶端選項

googlemanagedprometheus 匯出工具會使用 Managed Service for Prometheus 的 gRPC 用戶端。因此，您可以使用選用設定來設定 gRPC 用戶端：

  • compression：啟用 gRPC 要求的 gzip 壓縮功能，這有助於在將資料從其他雲端傳送至 Managed Service for Prometheus 時，盡可能降低資料傳輸費用 (有效值：gzip)。
  • user_agent：覆寫傳送至 Cloud Monitoring 要求的使用者代理程式字串；僅適用於指標。預設為 OpenTelemetry 收集器的版本號碼，例如 opentelemetry-collector-contrib 0.128.0。
  • endpoint：設定指標資料要傳送至哪個端點。
  • use_insecure：如果為 true，則使用 gRPC 做為通訊傳輸工具。只有在 endpoint 值不是 "" 時才有效。
  • grpc_pool_size：設定 gRPC 用戶端中的連線集區大小。
  • prefix：設定傳送至 Managed Service for Prometheus 的指標前置字串。預設值為 prometheus.googleapis.com。請勿變更這個前置字串，否則會導致無法在 Cloud Monitoring UI 中使用 PromQL 查詢指標。

在大多數情況下，您不需要將這些值從預設值變更為其他值。不過，您可以視情況變更這些設定。

所有這些設定都會在 googlemanagedprometheus 匯出器部分的 metric 區塊下方設定，如以下範例所示：

receivers:
  prometheus:
    config:
    ...

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

exporters:
  googlemanagedprometheus:
    metric:
      compression: gzip
      user_agent: opentelemetry-collector-contrib 0.128.0
      endpoint: ""
      use_insecure: false
      grpc_pool_size: 1
      prefix: prometheus.googleapis.com

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [resourcedetection]
      exporters: [googlemanagedprometheus]

後續步驟