在 Compute Engine 上部署 Google 建構的 OpenTelemetry 收集器

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

事前準備

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

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

啟用 Cloud Logging、Cloud Monitoring 和 Cloud Trace API。

啟用 API 時所需的角色

如要啟用 API，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

啟用 API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

啟用 Cloud Logging、Cloud Monitoring 和 Cloud Trace API。

啟用 API 時所需的角色

如要啟用 API，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

啟用 API

Compute Engine 執行個體。如果您沒有 Compute Engine 執行個體，請按照「建立及啟動 Compute Engine 執行個體」一文中的操作說明進行。
安裝 gcloud。如要瞭解如何安裝 gcloud，請參閱「安裝 gcloud CLI」。

設定收集器的權限

根據預設，Compute Engine 執行個體會使用 Compute Engine 預設服務帳戶 PROJECT_NUMBER-compute@developer.gserviceaccount.com。這個服務帳戶通常會具備必要的 Identity and Access Management (IAM) 角色，可寫入本文所述指標和記錄：

如果您選擇使用使用者管理的服務帳戶 (而非預設帳戶)，則必須指派這些相同角色。詳情請參閱服務帳戶。

安裝收集器

如要將 Google 建構的 OpenTelemetry 收集器安裝為 Compute Engine 執行個體的套件，請完成下列步驟。

Debian 與 Ubuntu

使用 SSH 或類似工具開啟連至 VM 執行個體的終端機連線，並確認您有 sudo 存取權。

執行下列指令來設定套件存放區：

sudo mkdir -p /etc/apt/keyrings
sudo curl -o /etc/apt/keyrings/otelcol-google.asc https://packages.cloud.google.com/apt/doc/apt-key.gpg
cat <<EOF | sudo tee /etc/apt/sources.list.d/otelcol-google.list
deb [signed-by=/etc/apt/keyrings/otelcol-google.asc] https://us-apt.pkg.dev/projects/cloud-ops-agents-artifacts google-cloud-opentelemetry-collector-apt main
EOF

重新整理套件管理員並安裝套件：
```
sudo apt update
sudo apt install otelcol-google
```
安裝完成後，Google 建構的 OpenTelemetry Collector 會自動啟動。

CentOS、RHEL 和 Rocky Linux

使用 SSH 或類似工具開啟連至 VM 執行個體的終端機連線，並確認您有 sudo 存取權。

執行下列指令來設定套件存放區：

cat <<EOF | sudo tee /etc/yum.repos.d/otelcol-google.repo
[otelcol-google]
name=Google Built OpenTelemetry Collector
baseurl=https://us-yum.pkg.dev/projects/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector-yum
autorefresh=0
enabled=1
type=rpm-md
gpgcheck=1
repo_gpgcheck=0
gpgkey=http://dl.google.com/linux/linux_signing_key.pub
EOF

安裝套件：
```
sudo yum install otelcol-google
```
安裝完成後，Google 建構的 OpenTelemetry Collector 會自動啟動。

SLES

使用 SSH 或類似工具開啟連至 VM 執行個體的終端機連線，並確認您有 sudo 存取權。

執行下列指令來設定套件存放區：

cat <<EOF | sudo tee /etc/zypp/repos.d/otelcol-google.repo
[otelcol-google]
name=Google Built OpenTelemetry Collector
baseurl=https://us-yum.pkg.dev/projects/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector-yum
autorefresh=0
enabled=1
type=rpm-md
gpgkey=http://dl.google.com/linux/linux_signing_key.pub
EOF

安裝套件：
```
sudo zypper install otelcol-google
```
安裝完成後，Google 建構的 OpenTelemetry Collector 會自動啟動。

Windows

使用遠端桌面協定或類似工具連線至執行個體，並登入 Windows。
以滑鼠右鍵按一下 PowerShell 圖示，然後選取「以系統管理員身分執行」，開啟具有管理員權限的 PowerShell 終端機。

執行下列 PowerShell 指令，設定套件存放區：

googet addrepo otelcol-google `
    https://us-googet.pkg.dev/projects/cloud-ops-agents-artifacts/repos/google-cloud-opentelemetry-collector-googet

安裝套件：
```
googet install otelcol-google
```
安裝完成後，Google 建構的 OpenTelemetry Collector 會自動啟動。

部署收集器

Google 內建的 OpenTelemetry Collector 預設包含最精簡的設定，不會匯出遙測資料。如要匯出遙測資料，請在安裝收集器後，覆寫預設設定來設定收集器。將 Collector 的設定放在下列檔案中：

Linux：/etc/otelcol-google/config.yaml
Windows：C:\Program Files\Google\OpenTelemetry Collector\config.yaml

設定收集器

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

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

提供的收集器設定

您可以在 opentelemetry-operations-collector 存放區的 google-built-opentelemetry-collector 目錄中找到 Collector 設定：

receivers:
  # Open two OTLP servers:
  # - On port 4317, open an OTLP GRPC server
  # - On port 4318, open an OTLP HTTP server
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver
  otlp:
    protocols:
      grpc:
        endpoint: localhost:4317
      http:
        cors:
          # This effectively allows any origin
          # to make requests to the HTTP server.
          allowed_origins:
          - http://*
          - https://*
        endpoint: localhost:4318

processors:
  # The batch processor is in place to regulate both the number of requests
  # being made and the size of those requests.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/batchprocessor
  batch:
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  # The memorylimiter will check the memory usage of the collector process.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/memorylimiterprocessor
  memory_limiter:
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  # The resourcedetection processor is configured to detect GCP resources.
  # Resource attributes that represent the GCP resource the collector is
  # running on will be attached to all telemetry that goes through this
  # processor.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#gcp-metadata
  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")

exporters:
  # The googlecloud exporter will export telemetry to different
  # Google Cloud services:
  # Logs -> Cloud Logging
  # Metrics -> Cloud Monitoring
  # Traces -> Cloud Trace
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlecloudexporter
  googlecloud:
    log:
      default_log_name: opentelemetry-collector

  # The googlemanagedprometheus exporter will send metrics to
  # Google Managed Service for Prometheus.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlemanagedprometheusexporter
  googlemanagedprometheus:

extensions:
  # Opens an endpoint on 13133 that can be used to check the
  # status of the collector. Since this does not configure the
  # `path` config value, the endpoint will default to `/`.
  #
  # When running on Cloud Run, this extension is required and not optional.
  # In other environments it is recommended but may not be required for operation
  # (i.e. in Container-Optimized OS or other GCE environments).
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/healthcheckextension
  health_check:
    endpoint: 0.0.0.0:13133

service:
  extensions:
  - health_check
  pipelines:
    logs:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - memory_limiter
      - batch
      exporters:
      - googlecloud
    metrics/otlp:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - transform/collision
      - memory_limiter
      - batch
      exporters:
      - googlemanagedprometheus
    traces:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - memory_limiter
      - batch
      exporters:
      - googlecloud
  # Internal telemetry for the collector supports both push and pull-based telemetry data transmission.
  # Leveraging the pre-configured OTLP receiver eliminates the need for an additional port.
  #
  # Docs:
  # https://opentelemetry.io/docs/collector/internal-telemetry/
  telemetry:
    metrics:
      readers:
        - periodic:
            exporter:
              otlp:
                protocol: grpc
                endpoint: http://localhost:4317
                insecure: true

出口商

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。

接收器

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

可用的元件

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

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

產生遙測資料

你可以使用開放原始碼的 telemetrygen 工具測試設定。連結中包含下載及執行工具的操作說明。如要執行這項工具，請安裝 Go 或 Docker。

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

查看遙測資料

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

查看指標

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

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

前往 Google Cloud 控制台的「指標探索器」頁面：
前往 Metrics Explorer

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。
在 Google Cloud 控制台的工具列中，選取 Google Cloud 專案。如要進行 App Hub 設定，請選取 App Hub 主專案或已啟用應用程式的資料夾管理專案。
在「指標」元素中，展開「選取指標」選單，在篩選列中輸入 Prometheus Target，然後使用子選單選取特定資源類型和指標：
1. 在「Active resources」(有效資源) 選單中，選取「Prometheus Target」(Prometheus 目標)。
2. 如要選取指標，請使用「使用中的指標類別」和「使用中的指標」選單。 Google 內建 OpenTelemetry Collector 收集的指標會加上 prometheus.googleapis.com 前置字元。
3. 按一下「套用」。
如要新增篩選器，從查詢結果中移除時間序列，請使用「Filter」元素。
設定資料的顯示方式。
如果指標的測量結果是累計值，Metrics Explorer 會自動以對齊週期將測量資料正規化，因此圖表會顯示比率。詳情請參閱「種類、型別和轉換」一文。

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

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

查看追蹤記錄

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

前往 Google Cloud 控制台的「Trace Explorer」頁面：
前往「Trace explorer」(Trace 探索工具)

您也可以透過搜尋列找到這個頁面。
在 Google Cloud 控制台的工具列中，選取您的 Google Cloud 專案。如果是 App Hub 設定，請選取 App Hub 主專案或管理專案。
在頁面的表格部分中，選取一列。
在「Trace details」(追蹤記錄詳細資料) 面板的甘特圖中，選取所需時距。

畫面上會開啟面板，顯示追蹤要求相關資訊。這些詳細資料包括方法、狀態碼、位元組數，以及呼叫者的使用者代理程式。
如要查看與這項追蹤記錄相關聯的記錄檔，請選取「記錄檔和事件」分頁標籤。

這個分頁會顯示個別記錄。如要查看記錄項目的詳細資料，請展開記錄項目。您也可以點選「查看記錄」，然後使用 Logs Explorer 查看記錄。

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

查看記錄檔

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

前往 Google Cloud 控制台的「Logs Explorer」頁面：
前往「Logs Explorer」(記錄檔探索工具)

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。
找出已插碼應用程式的記錄項目。如要查看詳細資料，請展開記錄項目。
在含有追蹤記錄訊息的記錄項目上，按一下「追蹤記錄」，然後選取「查看追蹤記錄詳細資料」。

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

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

觀察及偵錯 Collector

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

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

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

前往 Google Cloud 控制台的「Dashboards」(資訊主頁) 頁面：
前往「Dashboards」(資訊主頁)

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。
按一下「資訊主頁範本」。
搜尋 OpenTelemetry Collector 資訊主頁。
選用步驟：如要預覽資訊主頁，請選取該資訊主頁。
按一下「將資訊主頁新增至清單」，然後完成對話方塊。

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

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

在 Compute Engine 上部署 Google 建構的 OpenTelemetry 收集器 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

設定收集器的權限

安裝收集器

Debian 與 Ubuntu

CentOS、RHEL 和 Rocky Linux

SLES

Windows

部署收集器

設定收集器

提供的收集器設定

出口商

處理器

接收器

可用的元件

產生遙測資料

查看遙測資料

查看指標

查看追蹤記錄

查看記錄檔

觀察及偵錯 Collector

在 Compute Engine 上部署 Google 建構的 OpenTelemetry 收集器