在 Google Kubernetes Engine 上部署 Google 建構的 OpenTelemetry Collector

本文說明如何在 Google Kubernetes Engine 上執行 Google 建構的 OpenTelemetry Collector，從已檢測的應用程式收集 OTLP 記錄、指標和追蹤記錄，然後將這些資料匯出至 Google Cloud。

事前準備

執行 Google 建構的 OpenTelemetry 收集器需要下列資源：

  • 已啟用 Cloud Monitoring API、Cloud Trace API 和 Cloud Logging API 的 Google Cloud 專案。

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

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

        建立新專案

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

      3. 前往「帳單」：

        前往「帳單」頁面

      4. 如果尚未在頁面頂端選取您剛建立的專案，請立即選取。

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

      新專案預設會啟用 Monitoring API、Trace API 和 Logging API。

    • 如果您已有 Google Cloud 專案，請確認已啟用 Monitoring API、Trace API 和 Logging API：

      Enable the APIs

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

  • 下列指令列工具：

    • gcloud
    • kubectl

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

    gcloud components list

設定收集器的權限

如果您已停用 GKE 工作負載身分，則可略過本節。

為確保 OpenTelemetry Collector 的 Kubernetes 服務帳戶具備匯出遙測資料的必要權限，請要求管理員將專案的下列 IAM 角色授予 OpenTelemetry Collector 的 Kubernetes 服務帳戶：

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

管理員或許還可透過自訂角色或其他預先定義的角色，將必要權限授予 OpenTelemetry Collector 的 Kubernetes 服務帳戶。

如要設定權限，請使用下列 add-iam-policy-binding 指令：

gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/logging.logWriter \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector
gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/monitoring.metricWriter \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector
gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/cloudtrace.agent \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector

執行指令前，請先替換下列變數：

  • PROJECT_ID：專案的 ID。
  • PROJECT_NUMBER： Google Cloud 專案編號。

部署收集器

您可以直接從自我管理的 OTLP Kubernetes 擷取存放區提供的經過審查範例，部署 Collector 管道。將 PROJECT_ID 換成專案 ID 後，即可使用下列指令直接從 GitHub 部署： Google Cloud 

export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export PROJECT_NUMBER=PROJECT_NUMBER
kubectl kustomize https://github.com/GoogleCloudPlatform/otlp-k8s-ingest.git/k8s/base | envsubst | kubectl apply -f -

執行指令前，請先替換下列變數：

  • PROJECT_ID：專案的 ID。
  • PROJECT_NUMBER：專案的數值 ID。

設定收集器

我們提供 OpenTelemetry Collector 設定，供您搭配 Google 建構的 Collector 使用。這項設定旨在提供大量 OTLP 指標、記錄和追蹤記錄，並一律附加 GKE 和 Kubernetes 中繼資料。這項設定也旨在避免常見的擷取問題。您可以新增設定，但強烈建議不要移除元素。

本節說明提供的設定、匯出工具、處理器、接收器等重要元件，以及其他可用元件。

提供的收集器設定

您可以在 otlp-k8s-ingest 存放區中，找到 Kubernetes 環境的 Collector 設定：

# Copyright 2024 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

exporters:
  googlecloud:
    log:
      default_log_name: opentelemetry-collector
    user_agent: Google-Cloud-OTLP manifests:0.5.0 OpenTelemetry Collector Built By Google/0.131.0 (linux/amd64)
  googlemanagedprometheus:
    user_agent: Google-Cloud-OTLP manifests:0.5.0 OpenTelemetry Collector Built By Google/0.131.0 (linux/amd64)
  # The otlphttp exporter is used to send traces to Google Cloud Trace using OTLP http/proto
  # The otlp exporter could also be used to send them using OTLP grpc
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com
    # Use the googleclientauth extension to authenticate with Google credentials
    auth:
      authenticator: googleclientauth


extensions:
  health_check:
    endpoint: ${env:MY_POD_IP}:13133
  googleclientauth:


processors:
  filter/self-metrics:
    metrics:
      include:
        match_type: strict
        metric_names:
        - otelcol_process_uptime
        - otelcol_process_memory_rss
        - otelcol_grpc_io_client_completed_rpcs
        - otelcol_googlecloudmonitoring_point_count
  batch:
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  k8sattributes:
    extract:
      metadata:
      - k8s.namespace.name
      - k8s.deployment.name
      - k8s.statefulset.name
      - k8s.daemonset.name
      - k8s.cronjob.name
      - k8s.job.name
      - k8s.replicaset.name
      - k8s.node.name
      - k8s.pod.name
      - k8s.pod.uid
      - k8s.pod.start_time
    passthrough: false
    pod_association:
    - sources:
      - from: resource_attribute
        name: k8s.pod.ip
    - sources:
      - from: resource_attribute
        name: k8s.pod.uid
    - sources:
      - from: connection

  memory_limiter:
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  metricstransform/self-metrics:
    transforms:
    - action: update
      include: otelcol_process_uptime
      operations:
      - action: add_label
        new_label: version
        new_value: Google-Cloud-OTLP manifests:0.5.0 OpenTelemetry Collector Built By Google/0.131.0 (linux/amd64)

  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  transform/collision:
    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")

  # The relative ordering of statements between ReplicaSet & Deployment and Job & CronJob are important.
  # The ordering of these controllers is decided based on the k8s controller documentation available at
  # https://kubernetes.io/docs/concepts/workloads/controllers.
  # The relative ordering of the other controllers in this list is inconsequential since they directly
  # create pods.
  transform/aco-gke:
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["top_level_controller_type"], "ReplicaSet") where resource.attributes["k8s.replicaset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.replicaset.name"]) where resource.attributes["k8s.replicaset.name"] != nil
      - set(attributes["top_level_controller_type"], "Deployment") where resource.attributes["k8s.deployment.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.deployment.name"]) where resource.attributes["k8s.deployment.name"] != nil
      - set(attributes["top_level_controller_type"], "DaemonSet") where resource.attributes["k8s.daemonset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.daemonset.name"]) where resource.attributes["k8s.daemonset.name"] != nil
      - set(attributes["top_level_controller_type"], "StatefulSet") where resource.attributes["k8s.statefulset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.statefulset.name"]) where resource.attributes["k8s.statefulset.name"] != nil
      - set(attributes["top_level_controller_type"], "Job") where resource.attributes["k8s.job.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.job.name"]) where resource.attributes["k8s.job.name"] != nil
      - set(attributes["top_level_controller_type"], "CronJob") where resource.attributes["k8s.cronjob.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.cronjob.name"]) where resource.attributes["k8s.cronjob.name"] != nil

  # When sending telemetry to the GCP OTLP endpoint, the gcp.project_id resource attribute is required to be set to your project ID.
  resource/gcp_project_id:
    attributes:
    - key: gcp.project_id
      # MAKE SURE YOU REPLACE THIS WITH YOUR PROJECT ID
      value: ${GOOGLE_CLOUD_PROJECT}
      action: insert
  # The metricstarttime processor is important to include if you are using the prometheus receiver to ensure the start time is set properly.
  # It is a no-op otherwise.
  metricstarttime:
    strategy: subtract_initial_point

receivers:
  # This collector is configured to accept OTLP metrics, logs, and traces, and is designed to receive OTLP from workloads running in the cluster.
  otlp:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:4317
      http:
        cors:
          allowed_origins:
          - http://*
          - https://*
        endpoint: ${env:MY_POD_IP}:4318
  otlp/self-metrics:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:14317

service:
  extensions:
  - health_check
  - googleclientauth
  pipelines:
    logs:
      exporters:
      - googlecloud
      processors:
      - k8sattributes
      - resourcedetection
      - memory_limiter
      - batch
      receivers:
      - otlp
    metrics/otlp:
      exporters:
      - googlemanagedprometheus
      processors:
      - k8sattributes
      - memory_limiter
      - metricstarttime
      - resourcedetection
      - transform/collision
      - transform/aco-gke
      - batch
      receivers:
      - otlp
    metrics/self-metrics:
      exporters:
      - googlemanagedprometheus
      processors:
      - filter/self-metrics
      - metricstransform/self-metrics
      - k8sattributes
      - memory_limiter
      - resourcedetection
      - batch
      receivers:
      - otlp/self-metrics
    traces:
      exporters:
      - otlphttp
      processors:
      - k8sattributes
      - memory_limiter
      - resource/gcp_project_id
      - resourcedetection
      - batch
      receivers:
      - otlp
  telemetry:
    logs:
      encoding: json
    metrics:
      readers:
      - periodic:
          exporter:
            otlp:
              protocol: grpc
              endpoint: ${env:MY_POD_IP}:14317

出口商

Collector 設定包含下列匯出工具：

  • googlecloud，適用於記錄和追蹤記錄。這個匯出工具已設定預設記錄名稱。

  • googlemanagedprometheus 指標匯出工具。這個匯出工具不需要任何設定，但有設定選項。如要瞭解 googlemanagedprometheus 匯出工具的設定選項，請參閱 Google Cloud Managed Service for Prometheus 說明文件中的「開始使用 OpenTelemetry Collector」。

處理器

Collector 設定包含下列處理器：

  • batch： 設定為以每個要求最多 Google Cloud 個項目的形式，或每 5 秒的 Google Cloud 最短間隔 (以先到者為準)，批次處理遙測要求。

  • memory_limiter： 限制 Collector 的記憶體用量，在超過上限時捨棄資料點，避免發生記憶體不足導致當機的問題。

  • resourcedetection： 自動偵測 Google Cloud 資源標籤，例如 project_id 和 cluster_name。

  • k8sattributes： 自動將 Kubernetes 資源屬性對應至遙測標籤。

  • transform： 重新命名與受監控資源上的標籤衝突的指標標籤。 Google Cloud

接收器

收集器設定只包含otlp接收器。如要瞭解如何檢測應用程式，將 OTLP 追蹤記錄和指標傳送至 Collector 的 OTLP 端點，請參閱「選擇檢測方法」。

可用的元件

Google 建構的 OpenTelemetry Collector 包含大多數使用者啟用 Google Cloud Observability 豐富體驗所需的元件。如需可用元件的完整清單，請參閱 opentelemetry-operations-collector 存放區中的「Components」(元件) 。

如要要求變更或新增可用元件，請在 opentelemetry-operations-collector 存放區中開啟功能要求。

產生遙測資料

本節說明如何部署範例應用程式、將該應用程式指向 Collector 的 OTLP 端點，以及在Google Cloud中查看遙測資料。範例應用程式是小型產生器，可將追蹤記錄、記錄和指標匯出至 Collector。

如果應用程式已使用 OpenTelemetry SDK 進行檢測，則可以改為將應用程式指向 Collector 的端點。

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

kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/main/sample/app.yaml

如要將使用 OpenTelemetry SDK 的現有應用程式指向 Collector 的端點，請將 OTEL_EXPORTER_OTLP_ENDPOINT 環境變數設為 http://opentelemetry-collector.opentelemetry.svc.cluster.local:4317。

幾分鐘後，應用程式產生的遙測資料就會開始透過 Collector 傳送至 Google Cloud 控制台，顯示各項信號。

查看遙測資料

Google 內建的 OpenTelemetry Collector 會將已檢測應用程式的指標、記錄檔和追蹤記錄傳送至 Google Cloud Observability。收集器也會傳送自我觀察指標。下列各節將說明如何查看這項遙測資料。

查看指標

Google 建構的 OpenTelemetry Collector 會收集 Prometheus 指標，您可以使用 Metrics Explorer 查看這些指標。收集的指標取決於應用程式的檢測，不過 Google 建構的收集器也會寫入一些自我指標。

如要查看 Google 內建 OpenTelemetry Collector 收集的指標，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的 「Metrics Explorer」頁面：

    前往 Metrics Explorer

    如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。

  2. 在 Google Cloud 控制台的工具列中，選取您的 Google Cloud 專案。 如要進行 App Hub 設定，請選取 App Hub 主專案或已啟用應用程式的資料夾的管理專案。
  3. 在「指標」元素中，展開「選取指標」選單， 在篩選列中輸入 Prometheus Target， 然後使用子選單選取特定資源類型和指標：
    1. 在「Active resources」(有效資源) 選單中，選取「Prometheus Target」(Prometheus 目標)。
    2. 如要選取指標，請使用「使用中的指標類別」和「使用中的指標」選單。 Google 建構的 OpenTelemetry Collector 收集的指標會加上 prometheus.googleapis.com 前置字元。
    3. 按一下 [套用]。

  4. 如要新增篩選器，從查詢結果中移除時間序列，請使用「Filter」元素。

  5. 設定資料的顯示方式。

    如果指標的測量值是累計值，指標探索工具會自動以對齊週期將測量資料正規化，因此圖表會顯示比率。詳情請參閱「種類、型別和轉換」。

    如果測量整數或雙精度值 (例如使用 counter 指標)，Metrics Explorer 會自動加總所有時間序列。如要變更這項行為，請將「Aggregation」(彙整) 項目的第一個選單設為「None」(無)。

    如要進一步瞭解如何設定圖表，請參閱「使用 Metrics Explorer 時選取指標」。

查看追蹤記錄

如要查看追蹤記錄資料，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Trace Explorer」頁面：

    前往「Trace Explorer」頁面

    您也可以透過搜尋列找到這個頁面。

  2. 在 Google Cloud 控制台的工具列中，選取您的 Google Cloud 專案。如要進行 App Hub 設定，請選取 App Hub 主專案或已啟用應用程式的資料夾管理專案。
  3. 在頁面的表格部分中，選取一列。

  4. 在「Trace details」(追蹤記錄詳細資料) 面板的甘特圖中，選取時距。

    畫面上會開啟面板，顯示追蹤要求相關資訊。這些詳細資料包括方法、狀態碼、位元組數，以及呼叫者的使用者代理程式。

  5. 如要查看與這項追蹤記錄相關聯的記錄檔，請選取「記錄檔和事件」分頁標籤。

    這個分頁會顯示個別記錄。如要查看記錄項目的詳細資料，請展開記錄項目。您也可以按一下「查看記錄」，然後使用記錄探索工具查看記錄。

如要進一步瞭解如何使用 Cloud Trace 探索工具，請參閱「尋找及探索追蹤記錄」。

查看記錄檔

您可以在記錄檔探索器中檢查記錄，也可以查看相關聯的追蹤記錄 (如有)。

  1. 前往 Google Cloud 控制台的「Logs Explorer」頁面：

    前往「Logs Explorer」(記錄檔探索工具)

    如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

  2. 找出已插碼應用程式的記錄項目。如要查看詳細資料，請展開記錄項目。

  3. 在含有追蹤記錄訊息的記錄項目上，按一下「追蹤記錄」，然後選取「查看追蹤記錄詳細資料」。

    「Trace details」(追蹤記錄詳細資料) 面板隨即開啟，並顯示所選追蹤記錄。

如要進一步瞭解如何使用記錄檔探索工具，請參閱「使用記錄檔探索工具查看記錄檔」。

觀察及偵錯收集器

Google 建構的 OpenTelemetry Collector 會自動提供自我監控指標，協助您監控其效能，並確保 OTLP 擷取管道持續運作。

如要監控 Collector，請安裝 Collector 的範例資訊主頁。這個資訊主頁可讓您一目瞭然地掌握 Collector 的多項指標，包括正常運作時間、記憶體用量，以及對 Google Cloud Observability 的 API 呼叫。

如要安裝資訊主頁，請按照下列步驟操作：

  1. 在 Google Cloud 控制台中，前往「Dashboards」(資訊主頁) 頁面：

    前往「Dashboards」(資訊主頁)

    如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。

  2. 按一下「資訊主頁範本」。
  3. 搜尋 OpenTelemetry Collector 資訊主頁。
  4. 選用：如要預覽資訊主頁，請選取該資訊主頁。

  5. 按一下「將資訊主頁新增至清單」，然後完成對話方塊。

    您可以在對話方塊中選取資訊主頁名稱，並為資訊主頁新增標籤。

如要進一步瞭解如何安裝資訊主頁，請參閱「安裝資訊主頁範本」。