本頁面由 Cloud Translation API 翻譯而成。

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

本文說明為 Go、Java、Node.js 和 Python 語言提供的檢測範例結構。這些範例提供指引，說明如何檢測應用程式，以使用 OpenTelemetry SDK 和 OpenTelemetry 收集器。

這些範例中的檢測 (包括使用 OpenTelemetry SDK 和 SDK 的程序內 OTLP 匯出工具) 與供應商無關。程序內匯出工具會將遙測資料傳送至 OpenTelemetry 收集器，收集器收到資料後，會將資料傳送至您的 Google Cloud 專案。收集器包含 Google Cloud的繫結。這些範例會使用 Google Cloud 匯出工具，將記錄和指標資料傳送至專案。不過，這些程式庫會使用 Telemetry API 將追蹤記錄資料傳送至您的專案。

您可能對其他範例感興趣，這些範例說明瞭不同的設定：

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

如果您的環境支援使用收集器，建議您使用 OpenTelemetry 收集器匯出遙測資料。如果無法使用收集器，則必須使用程序內匯出工具，將資料直接傳送至 Google Cloud 專案。
使用樣本關聯指標和追蹤記錄：說明如何設定 Go 應用程式來產生樣本。範例是附加至指標資料點的範例資料點。您可以使用範例將追蹤和指標資料建立關聯。
使用作業套件代理程式和 OpenTelemetry Protocol (OTLP)：說明如何設定作業套件代理程式和 OTLP 接收器，從應用程式收集指標和追蹤記錄。

範例的運作方式

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

應用程式會使用 Docker 建構及部署。使用 OpenTelemetry 檢測應用程式時，您不必使用 Docker。

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

深入瞭解

這些範例會使用 OpenTelemetry Collector 做為輔助程序，接收及擴充應用程式的遙測資料，然後使用 Google Cloud exporter 將資料傳送至您的Google Cloud 專案。匯出工具會將遙測資料轉換為與 Cloud Trace API、Cloud Monitoring API 或 Cloud Logging API 相容的格式。接著，他們會發出 API 指令，將轉換後的資料傳送至您的Google Cloud 專案。

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

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

如果您查看範例，會發現這個步驟的複雜程度取決於語言。舉例來說，如果是 Go，這個步驟會設定 main 函式，以呼叫設定指標和追蹤記錄集合的函式。如果是 Go，HTTP 伺服器和用戶端也會更新。
設定記錄架構，寫入結構化記錄。

建議應用程式寫入結構化記錄，這樣記錄酬載就會格式化為 JSON 物件。對於這些記錄，您可以建構查詢來搜尋特定 JSON 路徑，也可以為記錄酬載中的特定欄位建立索引。

部分服務 (例如 Google Kubernetes Engine) 內建代理程式，可擷取結構化記錄並傳送至 Google Cloud 專案。其他服務 (例如 Compute Engine) 則需要安裝代理程式，代理程式會擷取並傳送記錄。如要瞭解您安裝的代理程式，請參閱「作業套件代理程式總覽」。

您不必安裝任何代理程式就能使用這些範例。
設定 Docker 檔案。所有範例都包含下列 YAML 檔案：
- docker-compose.yaml：設定應用程式、OpenTelemetry 收集器和負載產生器的服務。舉例來說，OpenTelemetry 收集器的服務 otelcol 會指定映像檔、磁碟區和環境變數。OpenTelemetry 收集器的端點是由 OTEL_EXPORTER_OTLP_ENDPOINT 環境變數設定，該變數是在 app 服務中指定。
- otel-collector-config.yaml：設定 OpenTelemetry 收集器。這個收集器會指定接收器、匯出器、處理器和管道。
  
  telemetry 服務會定義追蹤記錄、指標和記錄檔資料的管道。每個管道項目都會指定接收器、處理器和匯出工具。指標和追蹤記錄使用相同的接收器 otlp。
  
  「exporters」一節說明如何將收集到的資料匯出至 Google Cloud 專案。記錄和指標資料則使用匯出工具Google Cloud 。這些匯出工具會將遙測資料轉換為與對應 API 相容的格式，然後發出 API 指令，將轉換後的資料傳送至您的Google Cloud 專案。相較之下，追蹤記錄資料是使用支援 OTLP 的 Telemetry API 傳送至專案。
- docker-compose.creds.yaml：這個檔案會在 otelcol 容器中選用掛接Google Cloud 憑證檔案。在本機執行範例時，如果應用程式預設憑證 (ADC) 只能以檔案形式提供，就必須使用這個檔案。

所需權限

如要取得範例應用程式寫入記錄、指標和追蹤資料所需的權限，請要求管理員在專案中授予您下列 IAM 角色：
- 記錄寫入者 (roles/logging.logWriter)
- Monitoring 指標寫入者 (roles/monitoring.metricWriter)
- Cloud 遙測資料追蹤記錄寫入者 (roles/telemetry.tracesWriter)
如果您在 Cloud Shell、 Google Cloud 資源或本機開發環境中執行範例，先前的權限就足以寫入記錄、指標和追蹤資料。對於正式版應用程式，服務帳戶通常會提供必要憑證。

如要取得查看記錄、指標和追蹤資料所需的權限，請要求管理員在專案中授予您下列 IAM 角色：
- 記錄檢視器 (roles/logging.viewer)
- Monitoring 檢視者 (roles/monitoring.viewer)
- Cloud Trace 使用者 (roles/cloudtrace.user)
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

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

必要 API

Enable the Cloud Logging, Cloud Monitoring, Cloud Trace, and Telemetry APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

後續步驟

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

探索使用以收集器為準的匯出作業的範例。