本頁說明使用 Cloud Storage 用戶端程式庫與 Cloud Storage 互動時,如何透過 OpenTelemetry 啟用用戶端追蹤。您可以使用下列支援的 Cloud Storage 用戶端程式庫,收集及查看追蹤記錄資料:
總覽
在 Cloud Storage 用戶端程式庫中啟用追蹤功能,即可監控效能、找出延遲問題,並快速對 Cloud Storage 要求執行偵錯。追蹤記錄可讓您查看已完成要求的序列,詳細瞭解 Cloud Storage 如何接收、管理及回應要求。單一追蹤記錄是由多個「span」組成,這些 span 是應用程式在整個 Cloud Storage 要求中執行的每個函式或作業的詳細記錄,並附有時間戳記。
優點
收集及傳播追蹤記錄資料可為應用程式帶來下列好處:
提升效能可視性:Cloud Storage 完成您提出的每項要求時,都會近乎即時地產生追蹤資料,因此您可以快速找出效能瓶頸,並偵測延遲問題。
錯誤處理:您可以找出問題發生位置,並使用追蹤記錄中提供的各項 Cloud Storage 要求相關資訊,加快根本原因分析速度,縮短停機時間。
用戶端追蹤記錄的運作方式
以下各節將詳細說明追蹤記錄收集作業的運作方式。
OpenTelemetry 的追蹤記錄收集方式
Cloud Storage 用戶端程式庫支援使用 OpenTelemetry SDK 收集追蹤資料,設定收集及傳播追蹤資料所需的下列元件:
追蹤記錄供應器:Cloud Storage 用戶端程式庫會使用追蹤記錄供應器建立及管理追蹤記錄系統,包括在應用程式中產生及管理追蹤記錄和時距。
追蹤記錄匯出工具:由 OpenTelemetry SDK 使用,負責將追蹤記錄資料傳送至後端觀測能力平台,例如 Cloud Trace,您可以在該平台分析及視覺化追蹤記錄資料。如要進一步瞭解追蹤記錄匯出工具,請參閱「追蹤記錄匯出工具的運作方式」。
追蹤記錄匯出工具的運作方式
使用 OpenTelemetry SDK 設定追蹤記錄時,請選取可觀測性後端,將資料匯出至該處進行分析、儲存及視覺化。您可以將追蹤資料匯出至任何您選擇的可觀測性後端,但我們建議使用 Cloud Trace,您可透過 Cloud de Confiance 控制台存取這項服務,並與其他 Cloud de Confiance by S3NS 服務整合。
設定並啟用追蹤記錄供應器和追蹤記錄匯出工具後,您就能近乎即時地查看追蹤記錄資料,因為系統會為每項 Cloud Storage 要求產生追蹤記錄和 span。
您可以在Cloud de Confiance 控制台中使用 Cloud Trace 探索工具,查看每項追蹤記錄,其中包含下列資訊:
從頭到尾的 Cloud Storage 要求高階檢視畫面。
多個範圍,每個範圍都會擷取所執行 Cloud Storage 要求中的單一作業,並加上時間戳記。
如要進一步瞭解追蹤記錄和範圍,請參閱 OpenTelemetry 追蹤記錄和範圍說明文件。
定價
追蹤記錄資料須付費。費用取決於 Cloud Trace 擷取及掃描的追蹤記錄 span 數量。如要進一步瞭解可計費的追蹤記錄 span 和定價範例,請參閱「Cloud Trace 費用」。
事前準備
您必須先完成下列步驟,才能收集 Cloud Storage API 使用情形的追蹤記錄:
-
如果尚未啟用,請啟用 Cloud Trace API。
啟用 API 所需的角色
如要啟用 API,您必須具備
serviceusage.services.enable權限。如果您建立了專案,可能已透過擁有者角色 (roles/owner) 取得這項權限。否則,您可以透過服務使用情形管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。 啟用 Cloud Storage API。
必要的角色
如要取得將追蹤記錄寫入 Cloud Trace 的權限,請要求管理員針對用戶端使用的專案,授予您 Cloud Trace 代理 (roles/cloudtrace.agent) IAM 角色。
這個預先定義的角色具備 cloudtrace.traces.patch 權限,可將追蹤記錄寫入 Cloud Trace。
您或許還可透過預先定義的角色取得這些權限,或是建立自訂角色來授予特定權限。如需授予專案角色的操作說明,請參閱「授予或撤銷角色」。如要進一步瞭解 Cloud Trace 代理程式角色,請參閱「Identity and Access Management (IAM) 說明文件」。
設定應用程式追蹤
請按照下列操作說明設定追蹤,並開始使用 Cloud Storage 用戶端程式庫收集追蹤資料:
C++
安裝下列版本:
C++ 用戶端程式庫 v2.16.0 以上版本
C++ 14 以上版本
如要在 C++ 用戶端程式庫中啟用 OpenTelemetry 追蹤檢測功能,請更新 CMake 或 Bazel 的建構系統設定。
建立已啟用 OpenTelemetry 追蹤的 Cloud Storage 用戶端執行個體。
Java
安裝下列 Cloud Storage Java 用戶端程式庫版本:
com.google.cloud:google-cloud-storage:2.47.0以上版本com.google.cloud:libraries-bom:26.53.0以上版本
安裝 OpenTelemetry 適用的 Cloud Trace 匯出工具。 您也可以使用任何其他匯出工具。
安裝 Cloud Trace 傳播器。
建立已啟用 OpenTelemetry 追蹤的 Cloud Storage 用戶端執行個體。
Python
安裝 Cloud Storage Python 用戶端程式庫:
pip install google-cloud-storage[tracing]>=2.18.0
安裝 Cloud Trace 匯出器和傳播器。您也可以使用任何其他匯出工具。
pip install opentelemetry-exporter-gcp-trace opentelemetry-propagator-gcp
安裝 OpenTelemetry 要求檢測功能,追蹤基礎 HTTP 要求。
pip install opentelemetry-instrumentation-requests
設定環境變數,選擇加入 Python 儲存用戶端的追蹤功能:
export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True
設定追蹤記錄匯出工具和追蹤記錄提供者。
查看追蹤記錄
使用 Cloud Trace 探索工具,在 Cloud de Confiance 控制台中查看追蹤記錄資料:
-
前往 Cloud de Confiance 控制台的
「Trace Explorer」頁面:前往「Trace explorer」(Trace 探索工具)
您也可以透過搜尋列找到這個頁面。
在「Trace explorer」(追蹤探索工具) 頁面中,按一下散布圖中的特定追蹤記錄,即可查看追蹤記錄詳細資料。
「Trace details」(追蹤記錄詳細資料) 窗格會顯示追蹤記錄 span 表格。
選用:按一下跨度資料列,即可查看特定跨度的詳細資訊,例如:
屬性:提供 Span 相關額外資訊的鍵/值組合。
記錄檔和事件:與時距相關聯的記錄項目。
堆疊追蹤:與 Span 相關聯的堆疊追蹤。
Metadata & Links:與 Span 相關聯的其他 Cloud de Confiance by S3NS 服務連結。
如要進一步瞭解如何使用 Cloud Trace 探索工具,請參閱「尋找及探索追蹤記錄」。