以收集器為基礎的檢測範例總覽

如要在收集遙測資料並傳送至 Google Cloud時，讓應用程式程式碼保持供應商中立，您可以使用以 OpenTelemetry 收集器為基礎的檢測範例，適用於 Go、Java、Node.js 和 Python。

這些範例說明如何設定程序內 OpenTelemetry SDK，將指標、記錄和追蹤記錄匯出至本機 OpenTelemetry 收集器，以便將遙測資料轉送至 Google Cloud。範例會使用 Telemetry API，將 OpenTelemetry Protocol (OTLP) 格式的記錄、指標和追蹤記錄資料傳送至 Google Cloud 專案。

範例運作方式

Go、Java、Node.js 和 Python 的範例會使用 OpenTelemetry 通訊協定收集追蹤記錄和指標資料。範例會設定記錄架構來寫入結構化記錄，並設定 OpenTelemetry 收集器，從應用程式的 stdout 串流讀取。如需架構建議，請參閱「選擇檢測方法」。

應用程式是使用 Docker 建構及部署。使用 OpenTelemetry 檢測應用程式時，不一定要使用 Docker。

您可以在 Cloud Shell、 Google Cloud資源或本機開發環境中執行範例。

深入探索

範例使用 OpenTelemetry Collector 做為 sidecar，接收並充實應用程式的遙測資料，然後由匯出工具傳送至 Google Cloud 專案。範例會使用支援 OTLP 格式的 Telemetry API，將記錄、指標和追蹤記錄資料傳送至專案。

這些範例說明如何執行下列操作：

1. 設定 OpenTelemetry，使用 OpenTelemetry 收集器收集指標和追蹤記錄。

   這個步驟的複雜程度取決於語言。舉例來說，在 Go 中，您需要更新 main 函式，以初始化遙測收集作業，並設定 HTTP 伺服器和用戶端。

2. 設定記錄架構，寫入結構化記錄。

   建議您讓應用程式寫入結構化記錄，將記錄酬載格式設為 JSON 物件。您可以建構查詢，搜尋特定 JSON 路徑，並為記錄酬載中的特定欄位建立索引。

   部分服務 (例如 Google Kubernetes Engine) 內建代理程式，可擷取結構化記錄，並將這些記錄傳送至 Google Cloud 專案。其他服務 (例如 Compute Engine) 則需要您安裝代理程式，以便抓取及傳送記錄。如要瞭解您安裝的代理程式，請參閱「Ops Agent 總覽」。

   您不必安裝任何代理程式，即可使用這些範例。

3. 設定 Docker 檔案。所有範例都包含下列 YAML 檔案：

   • docker-compose.yaml：設定應用程式、OpenTelemetry 收集器和負載產生器的服務。舉例來說，OpenTelemetry 收集器的服務 otelcol 會指定映像檔、磁碟區和環境變數。OpenTelemetry 收集器的端點是由 OTEL_EXPORTER_OTLP_ENDPOINT 環境變數設定，該變數是在 app 服務中指定。

   • otel-collector-config.yaml：設定 OpenTelemetry 收集器：

     • 範例會使用 otlp 接收器接收指標和追蹤記錄資料，並使用 filelog 接收器接收記錄資料。

     • 範例使用 otlphttp 匯出工具，匯出記錄、指標和追蹤資料。

       otlphttp 匯出工具會使用支援 OTLP 的 Telemetry API，將資料傳送至專案。

   • docker-compose.creds.yaml：這個檔案會視需要在 otelcol 容器中掛接 Google Cloud憑證檔案。在本機電腦上執行範例時，如果應用程式預設憑證 (ADC) 僅以檔案形式提供，您就需要這個檔案。

所需權限

• 如要取得讓範例應用程式寫入記錄、指標和追蹤記錄資料所需的權限，請要求管理員授予您下列 IAM 角色：

  • 專案的記錄檔寫入者 (roles/logging.logWriter)
  • 專案的 Monitoring 指標寫入者 (roles/monitoring.metricWriter)
  • 專案的 Cloud 遙測資料追蹤記錄寫入者 (roles/telemetry.tracesWriter)
  • 配額專案的服務使用情形消費者 (roles/serviceusage.serviceUsageConsumer)

  如果您在 Cloud Shell、 Google Cloud 資源或本機開發環境中執行範例，這些權限就足夠。如要瞭解如何設定配額專案，請參閱「設定配額專案」。

  注意： 正式版應用程式通常會依賴服務帳戶，提供寫入記錄、指標和追蹤資料所需的憑證。在這些情況下，請將上述角色授予服務帳戶。

• 如要取得查看記錄、指標和追蹤記錄資料所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

  • 記錄檢視器 (roles/logging.viewer)
  • Monitoring 檢視者 (roles/monitoring.viewer)
  • Cloud Trace 使用者 (roles/cloudtrace.user)

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

  您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

必要 API

啟用 Cloud Logging、Cloud Monitoring、Cloud Trace 和 Telemetry API (如有任何 API 尚未啟用)：

啟用 API 所需的角色

您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「Service Usage 管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

其他檢測方法

您可能也會對其他說明不同設定的範例感興趣：

• 從 Trace 匯出工具遷移至 OTLP 端點：說明如何使用程序內檢測，將追蹤記錄資料直接傳送至 Google Cloud 專案。

  如果環境支援使用收集器，建議您使用 OpenTelemetry 收集器匯出遙測資料。如果無法使用收集器，則必須使用程序內匯出工具，直接將資料傳送至 Google Cloud 專案。

• 使用範例建立指標和追蹤記錄之間的關聯：說明如何設定 Go 應用程式來產生範例。「範例」是附加至指標資料點的範例資料點。您可以使用範例，將追蹤記錄和指標資料建立關聯。

• 使用 Ops Agent 和 OpenTelemetry Protocol (OTLP) 說明如何設定 Ops Agent 和 OTLP 接收器，以便從應用程式收集指標和追蹤記錄。

後續步驟

如要進一步瞭解收集器，請參閱「Google 建構的 OpenTelemetry 收集器」。

探索使用收集器匯出功能的範例。

• Go 範例
• Java 範例
• Node.js 範例
• Python 範例