本文件說明如何在 Google Kubernetes Engine 上執行 Google 建構的 OpenTelemetry Collector,收集來自檢測應用程式的 OTLP 記錄、指標和追蹤記錄,然後將這些資料匯出至 Google Cloud。
事前準備
執行 Google 建構的 OpenTelemetry 收集器需要下列資源:
Google Cloud 已啟用 Cloud Monitoring API、Cloud Trace API 和 Cloud Logging API 的專案。
如果您沒有 Google Cloud 專案,請執行下列操作:
在 Google Cloud 控制台中,前往「New Project」(新增專案):
在「Project Name」欄位中輸入專案名稱,然後按一下「Create」。
前往「帳單」:
如果頁面頂端沒有顯示已選取的專案,請選取您剛建立的專案。
系統會提示您選擇現有的付款資料,或是建立新的付款資料。
根據預設,新專案會啟用 Monitoring API、Trace API 和 Logging API。
如果您已擁有 Google Cloud 專案,請確認已啟用 Monitoring API、Trace API 和 Logging API:
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 服務帳戶:
-
Monitoring 指標寫入者 (
roles/monitoring.metricWriter
) -
記錄 Log Writer (
roles/logging.logWriter
) -
Cloud Trace 代理程式 (
roles/cloudtrace.agent
)
如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。
管理員也可能會透過自訂角色或其他預先定義的角色,為 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 專案編號。
部署收集器
您可以直接從 Self-Managed OTLP Kubernetes Ingestion repo 提供的經過審查的範例,部署 Collectors 管道。將 PROJECT_ID 替換為 Google Cloud 專案的 ID 後,您可以直接使用下列指令從 GitHub 部署:
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 環境的收集器設定:
出口商
收集器設定包含下列匯出工具:
googlecloud
匯出器,用於記錄和追蹤記錄。這個匯出工具會使用預設的記錄檔名稱進行設定。googlemanagedprometheus
匯出工具,用於指標。這個匯出工具不需要任何設定,但有設定選項。如要瞭解googlemanagedprometheus
匯出工具的設定選項,請參閱 Google Cloud Managed Service for Prometheus 說明文件中的「開始使用 OpenTelemetry Collector」。
處理器
收集器設定包含下列處理器:
batch
:設定為以 Google Cloud 每項要求的最大項目數量,或 Google Cloud 每 5 秒的最低間隔 (以先發生者為準) 來批次處理遙測資料要求。memory_limiter
:在超過上限時捨棄資料點,以便限制收集器的記憶體用量,防止記憶體不足而導致應用程式當機。resourcedetection
:自動偵測 Google Cloud 資源標籤,例如project_id
和cluster_name
。k8sattributes
:自動將 Kubernetes 資源屬性對應至遙測標籤。transform
:重新命名與監控資源標籤衝突的指標標籤。 Google Cloud
接收器
收集器設定僅包含 otlp
接收器。如要瞭解如何檢測應用程式,以便將 OTLP 追蹤記錄和指標傳送至收集器的 OTLP 端點,請參閱「選擇檢測方法」。
可用的元件
Google 建構的 OpenTelemetry 收集器包含大多數使用者在 Google Cloud 觀測功能中啟用豐富體驗所需的元件。如需可用元件的完整清單,請參閱 opentelemetry-operations-collector
存放區中的「元件」。
如要要求變更或新增可用的元件,請在 opentelemetry-operations-collector
存放區中提出功能要求。
產生遙測
本節將說明如何部署範例應用程式,並將該應用程式指向收集器的 OTLP 端點,以及在Google Cloud中查看遙測資料。範例應用程式是小型產生器,可將追蹤記錄、記錄和指標匯出至收集器。
如果您已使用 OpenTelemetry SDK 檢測應用程式,則可以改為將應用程式指向收集器的端點。
如要部署範例應用程式,請執行下列指令:
kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/main/sample/app.yaml
如要將使用 OpenTelemetry SDK 的現有應用程式指向收集器的端點,請將 OTEL_EXPORTER_OTLP_ENDPOINT
環境變數設為 http://opentelemetry-collector.opentelemetry.svc.cluster.local:4317
。
幾分鐘後,應用程式產生的遙測資料就會開始透過收集器傳送至各信號的 Google Cloud 主控台。
查看遙測
Google 建構的 OpenTelemetry Collector 會將檢測應用程式中的指標、記錄和追蹤記錄傳送至 Google Cloud Observability。收集器也會傳送自觀察指標。下列各節將說明如何查看這項遙測資料。
查看指標
Google 建構的 OpenTelemetry 收集器會收集 Prometheus 指標,您可以使用 Metrics Explorer 查看這些指標。收集的指標取決於應用程式的檢測功能,不過 Google 建構的收集器也會寫入一些自有指標。
如要查看 Google 建構的 OpenTelemetry 收集器收集的指標,請按照下列步驟操作:-
前往 Google Cloud 控制台的 leaderboard「Metrics Explorer」頁面:
如果您是使用搜尋列尋找這個頁面,請選取子標題為「Monitoring」的結果。
- 在 Google Cloud 控制台的工具列中,選取您的 Google Cloud 專案。 如要設定 App Hub,請選取 App Hub 主機專案或已啟用應用程式的資料夾管理專案。
- 在「指標」元素中,展開「選取指標」選單,在篩選列中輸入
Prometheus Target
,然後使用子選單選取特定資源類型和指標:- 在「Active resources」選單中,選取「Prometheus Target」。
- 如要選取指標,請使用「Active metric categories」和「Active metrics」選單。
由 Google 建構的 OpenTelemetry Collector 收集的指標會加上前置字串
prometheus.googleapis.com
。 - 按一下 [套用]。
- 設定資料檢視方式。
當指標的測量值為累積值時,「Metrics Explorer」會自動根據對齊期間將測量資料標準化,因此圖表會顯示速率。詳情請參閱「類型、類型和轉換」一文。
當系統測量整數或雙精度值時 (例如使用
counter
指標),Metrics Explorer 會自動加總所有時間序列。如要變更這項行為,請將「Aggregation」項目的第一個選單設為「None」。如要進一步瞭解如何設定圖表,請參閱「在使用 Metrics Explorer 時選取指標」。
查看追蹤記錄
如要查看追蹤記錄資料,請按照下列步驟操作:
-
前往 Google Cloud 控制台的「Trace Explorer」頁面:
您也可以透過搜尋列找到這個頁面。
- 在 Google Cloud 控制台的工具列中,選取您的 Google Cloud 專案。如要設定 App Hub,請選取 App Hub 主機專案或已啟用應用程式的資料夾管理專案。
- 在頁面中的表格部分選取一列。
在「Trace details」面板的甘特圖中,選取所需時距。
畫面上會開啟一個面板,顯示追蹤要求的相關資訊。這些詳細資料包括方法、狀態碼、位元組數量,以及呼叫端的使用者代理程式。
如要查看與此追蹤記錄相關聯的記錄,請選取「Logs & Events」分頁標籤。
這個分頁會顯示個別記錄。如要查看記錄項目的詳細資料,請展開記錄項目。您也可以按一下「View Logs」,然後使用 Logs Explorer 查看記錄檔。
如要進一步瞭解如何使用 Cloud Trace 探索工具,請參閱「尋找及探索追蹤記錄」一文。
查看記錄檔
您可以透過「記錄檔探索器」檢查記錄,也可以查看相關的追蹤記錄 (如果有)。
-
前往 Google Cloud 控制台的「Logs Explorer」頁面:
如果您是使用搜尋列尋找這個頁面,請選取子標題為「Logging」的結果。
找出已檢測的應用程式記錄項目。如要查看詳細資料,請展開記錄項目。
在含有追蹤記錄訊息的記錄項目上,按一下
「Traces」,然後選取「View trace details」。
「Trace details」面板會隨即開啟,並顯示所選的追蹤記錄。
如要進一步瞭解如何使用記錄檔探索工具,請參閱「使用記錄檔探索工具查看記錄檔」。
觀察及偵錯收集器
Google 建構的 OpenTelemetry 收集器會自動提供自觀察度指標,協助您監控效能,並確保 OTLP 攝入管道的持續運作時間。
如要監控收集器,請為收集器安裝範例資訊主頁。這個資訊主頁可讓您一目瞭然地掌握收集器的多項指標,包括正常運作時間、記憶體用量,以及對 Google Cloud Observability 的 API 呼叫。
如要安裝資訊主頁,請按照下列步驟操作:
-
在 Google Cloud 控制台中,前往「Dashboards」(資訊主頁)
頁面:
如果您是使用搜尋列尋找這個頁面,請選取子標題為「Monitoring」的結果。
- 按一下「資訊主頁範本」。
- 搜尋「OpenTelemetry Collector」資訊主頁。
- 選用步驟:如要預覽資訊主頁,請選取該資訊主頁。
按一下 playlist_add「將資訊主頁新增至清單」,然後完成對話方塊。
您可以透過對話方塊選取資訊主頁名稱,並在資訊主頁中新增標籤。
如要進一步瞭解如何安裝資訊主頁,請參閱「安裝資訊主頁範本」。