收集 OpenTelemetry Protocol (OTLP) 指標和追蹤記錄

本文件說明如何使用 Ops Agent 和 OpenTelemetry Protocol (OTLP) 接收器，從使用 OpenTelemetry 檢測並在 Compute Engine 上執行的應用程式，收集使用者定義的指標和追蹤記錄。

本文件的架構如下：

• 總覽：說明 OTLP 接收器的用途。
• 使用 OTLP 接收器的必要條件。
• 設定代理程式以使用 OTLP 接收器。
• 使用接收器收集指標。本節說明如何在 Cloud Monitoring 中查詢 OpenTelemetry 指標。
• 使用接收器收集追蹤記錄。本節說明如何授權服務帳戶將資料寫入 Cloud Trace。

使用 OTLP 接收器的簡介

您可以使用作業套件代理程式 OTLP 接收器執行下列操作：

• 使用 OpenTelemetry 的其中一個語言專屬 SDK 為應用程式進行檢測。如需支援語言的相關資訊，請參閱「OpenTelemetry 檢測程式」。OpenTelemetry SDK 和作業套件代理程式可為您執行下列操作：
  • 從應用程式收集 OTLP 指標，並將這些指標傳送至 Cloud Monitoring 進行分析。
  • 從應用程式收集 OTLP 時距 (追蹤記錄資料)，然後將這些時距傳送至 Cloud Trace 進行分析。
• 從內建支援 OTLP 的第三方應用程式，或支援 OTLP 的外掛程式 (例如 Nginx 等應用程式) 收集追蹤記錄。作業套件代理程式中的 OTLP 接收器可以收集這些追蹤記錄。如需範例，請參閱 OpenTelemetry nginx 模組。
• 使用 OpenTelemetry 自訂檢測功能。
• 使用 OpenTelemetry 自動檢測功能。

您可以使用接收器收集指標和/或追蹤記錄。在 Ops Agent 收集指標後，您可以使用 Cloud Monitoring 的功能 (包括圖表、資訊主頁和快訊政策) 監控指標。如果應用程式也傳送追蹤資料，您可以使用 Cloud Trace 分析該資料。

優點

在作業套件代理程式提供 OTLP 外掛程式之前，要檢測應用程式以收集使用者定義的指標和追蹤記錄，主要有以下幾種方式：

• 使用實作 Monitoring API 或 Trace API 的用戶端程式庫。
• 使用較舊的 OpenCensus 程式庫。

與上述方法相比，使用 OpenTelemetry 搭配 OTLP 接收器有幾項優點，包括：

• OpenTelemetry 是 OpenCensus 的替代方案。OpenCensus 專案正在封存中。詳情請參閱「什麼是 OpenTelemetry？」。
• 擷取作業是在代理程式層級控制，因此如果代理程式設定有所變更，您就不需要重新部署應用程式。
• 應用程式不需要設定 Google Cloud 憑證；所有授權作業都會在代理程式層級處理。
• 您的應用程式程式碼不含任何 Google Cloud專屬監控或追蹤程式碼。您不必直接使用 Monitoring API 或 Trace API。
• 應用程式會將資料推送至 Ops Agent，如果應用程式發生當機，Ops Agent 收集的任何資料都不會遺失。

限制

作業套件代理程式接收器公開的 OTLP 事件監聽器支援 gRPC 傳輸。系統不支援 HTTP (主要用於 JavaScript 用戶端)。如要進一步瞭解 OpenTelemetry 通訊協定，請參閱「通訊協定詳細資料」。

OTLP 接收器不會收集記錄。您可以使用 Ops Agent 和其他接收器收集記錄，並在 OTLP 跨度中加入記錄資訊，但 OTLP 接收器不支援直接收集記錄。如要瞭解如何使用 Ops Agent 收集記錄，請參閱「記錄設定」。

必要條件

如要使用 OTLP 接收器和作業套件代理程式收集 OTLP 指標和追蹤記錄，您必須安裝作業套件代理程式 2.37.0 以上版本。

本文件假設您已使用其中一個 OpenTelemetry SDK 編寫的 OpenTelemetry 應用程式。本文未涵蓋 OpenTelemetry SDK 的使用方式。如需 SDK 和支援語言的相關資訊，請參閱「OpenTelemetry 檢測程式」。

設定作業套件代理程式

如要設定 Ops Agent 使用 OTLP 接收器，請按照下列步驟操作：

1. 修改 Ops Agent 的使用者設定檔，納入 OTLP 接收器。
2. 重新啟動 Ops Agent。

以下各節將說明每個步驟。

修改作業套件代理程式使用者設定檔

將 OTLP 接收器的設定元素新增至 Ops Agent 的使用者設定檔：

• 適用於 Linux：/etc/google-cloud-ops-agent/config.yaml
• Windows：C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml

如需代理程式設定的一般資訊，請參閱「設定模型」。

OTLP 接收器會為作業套件代理程式引進 combined 設定部分。使用接收器時，即使您未同時使用指標和追蹤記錄，也必須設定這兩項服務。

以下各節說明 OTLP 接收器的設定步驟。

新增 combined 接收器區段

您可以在 combined 區段中放置 OTLP 指標和追蹤記錄的接收器。combined 區段不允許使用任何處理器或服務。您不得設定任何其他接收器，其名稱與 combined 區段中的接收器相同。以下範例使用 otlp 做為接收器的名稱。

OTLP 的最低 combined 設定如下所示：

combined:
  receivers:
    otlp:
      type: otlp

otlp 接收器提供下列設定選項：

• type：必填。必須為 otlp
• grpc_endpoint：選用。OTLP 接收器所監聽的 gRPC 端點。預設值為 0.0.0.0:4317。

• metrics_mode：選用。預設為 googlemanagedprometheus，表示接收端會使用 Managed Service for Prometheus 所用的 Prometheus API，將 OTLP 指標傳送為 Prometheus 格式指標。

  如要改用 Monitoring API 將指標傳送為 Cloud Monitoring 自訂指標，請將 metrics_mode 選項設為 googlecloudmonitoring 值。

  這項選擇會影響指標的擷取方式，以及用於計費的評估方式。如要進一步瞭解指標格式，請參閱「OLTP 指標的攝入格式」。

為服務新增 OTLP 管道

OTLP 接收器可以收集指標和追蹤記錄，因此您必須定義指標和追蹤記錄的服務。如果您不打算收集指標或追蹤記錄，可以建立空白服務。如果您已有其他管道服務，可以將 OTLP 管道新增至這些服務。

下圖顯示 metrics 和 traces 服務，以及管道中包含的 OTLP 接收器：

combined:
  receivers:
    otlp:
      type: otlp
metrics:
  service:
    pipelines:
      otlp:
        receivers: [otlp]
traces:
  service:
    pipelines:
      otlp:
        receivers: [otlp]

如果您不想使用 metrics 或 traces 服務收集 OTLP，請將 OTLP 接收器從服務管道中移除。即使服務沒有管道，也必須存在。如果應用程式傳送特定類型的資料，但沒有對應的管道包含接收器，則 Ops Agent 會捨棄資料。

重新啟動 Ops Agent

如要套用設定變更，您必須重新啟動 Ops Agent。

收集 OTLP 指標

使用 OTLP 接收器收集 OpenTelemetry 應用程式指標時，接收器的主要設定選項就是您要用來擷取指標的 API。

您可以變更 otlp 接收器設定中的 metrics_mode 選項，或使用預設值來做出這項選擇。這項選擇會影響 OTLP 指標如何匯入 Cloud Monitoring，以及系統如何評估這類資料以供帳單用途。

metrics_mode 選項不會影響您在 Monitoring 中建立圖表、資訊主頁和快訊政策的功能。

• 如要進一步瞭解如何建立圖表和資訊主頁，請參閱資訊主頁和圖表總覽。
• 如要進一步瞭解快訊政策，請參閱快訊總覽。

以下各節說明指標模式使用的格式差異，以及如何查詢攝入的資料，以便在監控中使用。

OTLP 指標的擷取格式

OTLP 接收器提供 metrics_mode 選項，可指定用於擷取指標資料的 API。根據預設，接收器會使用 Prometheus API；metrics_mode 選項的預設值為 googlemanagedprometheus。系統會使用 Managed Service for Prometheus 使用的 API 擷取指標。

您可以將接收器設為將指標資料傳送至 Cloud Monitoring API。如要將資料傳送至 Monitoring API，請將 metrics_mode 選項的值設為 googlecloudmonitoring，如以下範例所示：

combined:
  receivers:
    otlp:
      type: otlp
      metrics_mode: googlecloudmonitoring

您使用的擷取格式會決定 OTLP 指標如何對應至 Cloud Monitoring。您可以在 Monitoring 中為任何指標格式的指標建立圖表、資訊主頁和警示政策，但在查詢中參照指標的方式不同。

擷取格式也會決定用於擷取資料的定價模式。

以下各節將說明價格、Prometheus API 擷取的指標與 Monitoring API 擷取的相同指標之間的結構差異，以及如何在查詢中參照指標。

定價與配額

您使用的擷取格式會決定 OTLP 指標的收費方式：

• Prometheus API：如果您使用 Prometheus API 擷取應用程式指標，系統會以樣本計費，就像是使用 Managed Service for Prometheus 擷取指標一樣。

  • 如要查看目前定價，請參閱 Cloud Monitoring 定價摘要。
  • 如要進一步瞭解如何計算樣本數量和估算費用，請參閱「根據已擷取的樣本數量計費範例」。

• Monitoring API：使用 Monitoring API 擷取應用程式指標時，資料會依據用量計費，例如與 Ops Agent 整合的其他資料。

  • 如要查看目前定價，請參閱 Cloud Monitoring 定價摘要。
  • 如要進一步瞭解擷取量和預估費用，請參閱「依據擷取的位元組數計費示例」。

使用 OTLP 接收器擷取的指標，在擷取至 Cloud Monitoring 時會視為「自訂」指標，並受自訂指標的配額和限制約束。

指標結構

Cloud Monitoring 會使用稱為「指標描述元」的結構描述指標資料格式。指標描述元包含指標名稱、指標值的資料類型、每個值與先前值的關聯方式，以及與值相關聯的任何標籤。如果您設定 OTLP 接收器使用 Prometheus API 擷取指標，則建立的指標描述元會與使用 Monitoring API 時建立的指標描述元不同。

Prometheus API：使用 Prometheus API 擷取應用程式指標時，每個指標都會透過標準的 OpenTelemetry 至 Prometheus 轉換轉換，並對應至 Cloud Monitoring 監控資源類型。

• 轉換作業包括下列變更：
  • OTLP 指標名稱的前置字串為 prometheus.googleapis.com/。
  • OTLP 指標名稱中的任何非英數字元 (例如句號 .) 都會替換為底線 (_)。
  • OTLP 指標名稱的後置字串會指出指標類型，例如 /gauge 或 /counter。
• 系統會將下列標籤加入指標，這些標籤會填入 OTLP 資源的值：
  • instance_name：host.name 資源屬性的值。
  • machine_type：host.type 資源屬性的值。

• 使用指標測量值記錄的受控資源是一般 prometheus_target 類型。產生的 Prometheus 時間序列包含來自 prometheus_target 資源的下列標籤，並填入 OTLP 資源的值：

  • location：cloud.availability_zone 資源屬性的值。
  • namespace：host.id 資源屬性的值。

  prometheus_target 資源類型也包含下列標籤：

  • project_id： Google Cloud 專案的 ID，例如 my-project，作業套件代理程式會在其中執行。
  • cluster：當作業套件代理程式收集指標時，這個值一律為 __gce__。

如果傳入的 OTLP 資料缺少用於標籤值的資源屬性，系統會從執行 Ops Agent 的 VM 相關資訊中取得值。這項行為表示，如果 OTLP 資料沒有這些資源屬性，就會顯示與 Ops Agent Prometheus 接收器收集的資料相同的標籤。

Monitoring API：使用 Monitoring API 擷取應用程式指標時，系統會依下列方式處理每項指標：

• 除非 OTLP 指標名稱已包含此字串或其他有效指標網域 (例如 custom.googleapis.com)，否則 OTLP 指標名稱的前置字串為 workload.googleapis.com/。建議您使用「workload」網域。
• 使用指標測量值記錄的監控資源是 Compute Engine 虛擬機器類型 gce_instance。

以下範例顯示一組 OpenTelemetry 指標的指標描述元。這些指標是由使用 Go OpenTelemetry 指標程式庫的應用程式建立。「Prometheus API」分頁會顯示 OTLP 接收器使用預設 Prometheus 指標模式時建立的指標描述元。「Monitoring API」分頁會顯示 OTLP 接收器使用 googlecloudmonitoring 指標模式時建立的指標描述元。

在建立指標的應用程式中，不會有任何變更；唯一的變更是 OTLP 接收器使用的指標模式。

應用程式會建立 OTLP 量測指標 otlp.test.gauge，用於記錄 64 位元浮點值。下列分頁會顯示每個擷取 API 建立的指標描述元：

{
  "name": "projects/PROJECT_ID/metricDescriptors/prometheus.googleapis.com/otlp_test_gauge/gauge",
  "labels": [
    {
      "key": "instance_name"
    },
    {
      "key": "machine_type"
    }
  ],
  "metricKind": "GAUGE",
  "valueType": "DOUBLE",
  "type": "prometheus.googleapis.com/otlp_test_gauge/gauge",
  "monitoredResourceTypes": [
    "prometheus_target"
  ]
}

{
  "name": "projects/PROJECT_ID/metricDescriptors/workload.googleapis.com/otlp.test.gauge",
  "labels": [
    {
      "key": "instrumentation_source"
    }
  ],
  "metricKind": "GAUGE",
  "valueType": "DOUBLE",
  "type": "workload.googleapis.com/otlp.test.gauge",
  "monitoredResourceTypes": [
    "gce_instance",
    ...many other types deleted...
  ]
}

應用程式會建立 OTLP 計數器指標 otlp.test.cumulative，用來記錄遞增的 64 位元浮點值。下列分頁會顯示每個擷取 API 建立的指標描述元：

{
  "name": "projects/PROJECT_ID/metricDescriptors/prometheus.googleapis.com/otlp_test_cumulative/counter",
  "labels": [
    {
      "key": "instance_name"
    },
    {
      "key": "machine_type"
    }
  ],
  "metricKind": "CUMULATIVE",
  "valueType": "DOUBLE",
  "type": "prometheus.googleapis.com/otlp_test_cumulative/counter",
  "monitoredResourceTypes": [
    "prometheus_target"
  ]
}

{
  "name": "projects/PROJECT_ID/metricDescriptors/workload.googleapis.com/otlp.test.cumulative",
  "labels": [
    {
      "key": "instrumentation_source"
    }
  ],
  "metricKind": "CUMULATIVE",
  "valueType": "DOUBLE",
  "type": "workload.googleapis.com/otlp.test.cumulative",
  "monitoredResourceTypes": [
    "gce_instance",
    ...many other types deleted...
  ]
}

下表摘要說明用於擷取 OTLP 指標的 API 所強制規定的部分格式差異：

擷取格式和查詢

在 OTLP 接收器中使用的指標模式會影響您在建立圖表、資訊主頁和警告政策時，在 Cloud Monitoring 中查詢產生指標的方式。

在 Cloud Monitoring 中設定圖表、資訊主頁或快訊政策時，設定會包含對圖表、資訊主頁或快訊政策運作資料的查詢。

Cloud Monitoring 支援下列工具，可用於查詢指標資料：

• 以查詢建構工具為基礎的介面，內建於 Metrics Explorer、資訊主頁建構工具介面和警示政策設定介面等工具中。
• Monitoring Query Language (MQL)：專屬於 Cloud Monitoring 的文字查詢語言。
• Prometheus 查詢語言 (PromQL)：開放原始碼 Prometheus 使用的文字查詢語言。

如要瞭解如何使用這些工具查詢 OTLP 指標，請參閱以下內容：

• 使用 Prometheus API 擷取的 OTLP 指標查詢
• 使用 Monitoring API 擷取的 OTLP 指標查詢

使用 Prometheus API 查詢已擷取的 OTLP 指標

本節說明如何使用 Prometheus API (這是 OTLP 接收器的預設指標模式) 查詢攝入的 OTLP 指標。

查詢會根據「指標結構」一文中所述的 OTLP 指標：

• otlp.test.gauge：記錄 64 位元浮點值的 OTLP 量表指標。
• otlp.test.cumlative：OTLP 計數器指標，可記錄遞增的 64 位元浮點值。

這些指標會使用下列指標類型 (可做為名稱) 擷取至 Cloud Monitoring：

• prometheus.googleapis.com/otlp_test_gauge/gauge
• prometheus.googleapis.com/otlp_test_cumulative/counter

使用 Prometheus API 擷取的指標會寫入受控資源類型 prometheus_target。

這些分頁會顯示使用 Google Cloud 控制台查詢指標時，基本查詢的樣貌。這些範例使用 Metrics Explorer，但資料主頁和快訊政策的原則相同。

使用 Monitoring API 查詢攝入的 OTLP 指標

本節說明如何使用 Monitoring API 查詢攝入的 OTLP 指標。您可以將 OTLP 接收器的 metrics_mode 欄位設為 googlecloudmonitoring 值，藉此選取 Cloud Monitoring API。

查詢會根據「指標結構」一文中所述的 OTLP 指標：

• otlp.test.gauge：記錄 64 位元浮點值的 OTLP 量表指標。
• otlp.test.cumlative：OTLP 計數器指標，可記錄遞增的 64 位元浮點值。

這些指標會使用下列指標類型 (可做為名稱) 擷取至 Cloud Monitoring：

• workload.googleapis.com/otlp.test.gauge
• workload.googleapis.com/otlp.test.cumulative

使用 Monitoring API 擷取的指標會寫入受控資源類型 gce_instance。

這些分頁會顯示使用 Google Cloud 控制台查詢指標時，基本查詢的樣貌。這些範例使用 Metrics Explorer，但資料主頁和快訊政策的原則相同。

在 Cloud Monitoring 中查看指標用量和診斷資訊

Cloud Monitoring 的「指標管理」頁面提供資訊，可協助您控制可計費指標的支出金額，且不會影響可觀察性。「指標管理」頁面會回報下列資訊：

• 以位元組和樣本為基礎的計費作業量，跨指標網域和個別指標。
• 指標的標籤和基數資料。
• 每個指標的讀取次數。
• 在警告政策和自訂資訊主頁中使用指標。
• 指標寫入錯誤率。

您也可以使用「指標管理」頁面排除不需要的指標，省下擷取這些指標的成本。

如要查看「指標管理」頁面，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往 query_stats「Metrics management」頁面：

   前往「指標管理」

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

2. 在工具列中選取時間範圍。根據預設，「指標管理」頁面會顯示過去一天內收集的指標資訊。

如要進一步瞭解「指標管理」頁面，請參閱「查看及管理指標使用情形」一文。

收集 OTLP 追蹤記錄

如果您已設定 Ops Agent 來收集追蹤記錄，但在執行應用程式時，Cloud Trace 中沒有任何追蹤記錄，則可能需要為代理程式使用的 Compute Engine 服務帳戶授予其他角色。根據預設，服務帳戶會取得寫入指標和記錄所需的角色，但不會取得追蹤記錄所需的角色。

以下各節將說明如何授予服務帳戶必要的 Cloud Trace 授權。

決定要授予服務帳戶的角色

如要查看授予服務帳戶的角色，請執行下列 gcloud projects get-iam-policy 指令：

gcloud projects get-iam-policy PROJECT_ID --format="table(bindings.role)" --flatten="bindings[].members" --filter="bindings.members:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com"

您可能會看到類似以下的輸出內容：

ROLE
roles/logging.logWriter
roles/monitoring.metricWriter

如果輸出內容包含 roles/cloudtrace.agent 或 roles/cloudtrace.admin，表示服務帳戶具有足夠的權限可寫入追蹤記錄。如要將其中一個角色授予服務帳戶，請參閱下一個部分。

將 Cloud Trace 角色授予服務帳戶

對於服務帳戶，通常適合使用 Cloud Trace 代理人角色 roles/cloudtrace.agent。如要將這個角色授予服務帳戶，請執行下列 gcloud projects add-iam-policy-binding 指令：

gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role="roles/cloudtrace.agent"

接著執行 gcloud projects get-iam-policy 指令，驗證是否已完成變更：

gcloud projects get-iam-policy PROJECT_ID --format="table(bindings.role)" --flatten="bindings[].members" --filter="bindings.members:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com"

輸出內容現在包含 roles/cloudtrace.agent：

ROLE
roles/cloudtrace.agent
roles/logging.logWriter
roles/monitoring.metricWriter

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

授權 Ops Agent 使用的服務帳戶將資料寫入 Cloud Trace 後，當您執行以 OpenTelemetry 為基礎的應用程式時，追蹤記錄就會顯示在 Cloud Trace 中。

停用 OTLP 接收器

如果您使用 Ops Agent 收集 OTLP 指標和追蹤記錄，但只想停用其中一種指標或追蹤記錄的收集功能，請按照下列步驟操作：

1. 如要停用指標或追蹤記錄的收集作業，請對使用者設定檔 config.yaml 進行下列任一變更：

   • 從 metrics 服務中移除 otlp 管道。
   • 從 traces 服務中移除 otlp 管道。

2. 重新啟動 Ops Agent。

如要停用 Ops Agent 收集 OTLP 指標和追蹤記錄的功能，請按照下列步驟操作：

1. 從使用者設定檔中移除 OTLP 設定：

   • 刪除整個 combined 區段，包括 otlp 接收器。
   • 從 metrics 服務中移除 otlp 管道。
   • 刪除整個 traces 服務。

2. 重新啟動 Ops Agent。

後續步驟

應用程式指標和追蹤記錄擷取完成後，您可以使用 Google Cloud 控制台監控及分析資料。

• 如要瞭解資訊主頁和可建立的圖表類型，請參閱「資訊主頁和圖表」。
• 如要瞭解快訊政策，請參閱「使用快訊政策」。
• 如要進一步瞭解如何分析追蹤記錄資料，請參閱「尋找及探索追蹤記錄」。