Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

將收集器遷移至使用 OTLP 匯出工具

遙測 (OTLP) API 是 OpenTelemetry Protocol 的實作項目。支援 OTLP 可讓您在收集器設定中新增一般 otlphttp 和 otlp_grpc/otlp_logs 匯出器，避免使用特定廠商的匯出器。應用程式可以將記錄、指標和追蹤資料傳送至 Telemetry API。

如果收集器的設定使用 googlecloud 匯出工具或 googlemanagedprometheus 匯出工具，則本指南適用於您：

記錄資料：從 googlecloud 匯出工具遷移至 otlp_grpc/otlp_logs 匯出工具。
指標資料：從 googlemanagedprometheus 匯出工具遷移至 otlphttp 匯出工具。
追蹤資料：從 googlecloud 匯出工具遷移至 otlphttp 匯出工具。

如要遷移至 OTLP 匯出工具，請按照下列步驟操作：

啟用 Telemetry API
授權給收集器服務帳戶
設定 GOOGLE_CLOUD_PROJECT 環境變數
新增 googleclientauth 擴充功能
新增 otlphttp 和 otlp_grpc/otlp_logs 匯出工具
新增處理器
更新服務管道
驗證設定
遷移資訊主頁和快訊政策
移除特定供應商的匯出工具

啟用 Telemetry API

OTLP 匯出工具會寫入 Telemetry API，因此您必須在專案中啟用該 API。如要啟用 Telemetry API，請執行下列指令：

gcloud services enable telemetry.googleapis.com

授權給收集器服務帳戶

收集器會使用執行環境的身分，向 Google Cloud API 進行驗證。執行收集器的服務帳戶必須有權使用 Telemetry API 寫入記錄、指標和追蹤資料。此外，由於 Telemetry API 是消費者 API，您必須明確指定 Google Cloud API 呼叫會耗用哪個專案的配額，並授予服務帳戶耗用該專案配額所需的權限。

必要的角色

為確保執行收集器的服務帳戶具備必要權限，可傳送記錄、指標和追蹤資料，請要求管理員在專案中，將下列 IAM 角色授予執行收集器的服務帳戶：

Cloud 遙測資料寫入者 (roles/telemetry.writer)
服務使用情形用戶 (roles/serviceusage.serviceUsageConsumer)

這些預先定義的角色具備傳送記錄、指標和追蹤資料所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要傳送記錄、指標和追蹤資料，必須具備下列權限：

logging.logEntries.create
monitoring.timeSeries.create
telemetry.traces.write
serviceusage.services.use

Kubernetes 服務帳戶

如果您使用 GKE 適用的工作負載身分聯盟，在 Google Kubernetes Engine (GKE) 上部署收集器，請將必要角色授予 Kubernetes 服務帳戶。

如果 API 配額是從與 Telemetry API 呼叫目的地相同的 Google Cloud 專案中提取，您可以使用下列指令授予必要角色。執行指令前，請將 PROJECT_ID 替換為專案 ID。不過，如果您使用獨立的配額專案，請將第二個指令中的 PROJECT_ID 替換為配額專案的 ID：

export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/telemetry.writer \
  --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/serviceusage.serviceUsageConsumer \
  --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

Workload Identity Federation for GKE 的服務帳戶

如果您為 Workload Identity Federation for GKE 設定服務帳戶，可以使用 Google Cloud Managed Service for Prometheus 說明文件中的指令授權服務帳戶，但須進行下列變更：

將 gmp-test-sa 替換成服務帳戶名稱。
執行指令，授予必要角色，以便寫入記錄、指標和追蹤資料。

其他服務帳戶

如果您在 Compute Engine VM 或 GKE 外部執行收集器，請將必要角色授予部署作業使用的 Google Cloud 服務帳戶。

設定 `GOOGLE_CLOUD_PROJECT` 環境變數

在收集器部署作業中設定 GOOGLE_CLOUD_PROJECT 環境變數。結果如下所示：

env:
- name: GOOGLE_CLOUD_PROJECT
  value: PROJECT_ID

新增 `googleclientauth` 擴充功能

將 googleclientauth 擴充功能新增至收集器設定。 Telemetry API 是消費者 API，因此您必須同時指定 Google Cloud 專案和配額專案。結果類似下方：

extensions:
  googleclientauth:
    project: ${GOOGLE_CLOUD_PROJECT}
    quota_project: ${GOOGLE_CLOUD_PROJECT}

新增 `otlphttp` 和 `otlp_grpc/otlp_logs` 匯出工具

使用 otlphttp 匯出工具，將 OTLP 格式的指標和追蹤記錄資料傳送至專案，並使用 otlp_grpc/otlp_logs 匯出工具傳送記錄資料。請務必使用 googleclientauth 擴充功能設定這兩個匯出工具。

傳回的結果看起來類似下列內容：

exporters:
  # ... existing content ...
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
  otlp_grpc/otlp_logs:
    auth:
      authenticator: googleclientauth
    balancer_name: pick_first
    endpoint: telemetry.googleapis.com:443

如果是 otlp_grpc/otlp_logs 匯出工具，則必須使用 host:port 格式指定 endpoint 欄位。

新增處理器

本節列出需要新增至收集器的處理器。您可能想使用其他處理器。舉例來說，Google 打造的 OpenTelemetry Collector 收集器設定通常包含 memory_limiter 處理器，以及可轉換指標資料的處理器。如需範例，請參閱「Google-Built OpenTelemetry Collector on GKE」。

新增 `resource/gcp_project_id` 處理器

新增可擷取專案相關資訊的 resource 處理器。Google Cloud

  resource/gcp_project_id:
    attributes:
      - action: insert
        value: ${GOOGLE_CLOUD_PROJECT}
        key: gcp.project_id

新增 `resourcedetection` 處理器

如果您在 Google Cloud上執行，請考慮新增 resourcedetection 處理器。這個處理器可以自動探索架構相關資訊。

下列設定會尋找標準 OpenTelemetry 環境變數，然後查詢 Google Cloud 中繼資料伺服器，以收集基礎架構的相關資訊：

  resourcedetection:
    detectors: ["env", "gcp"]

新增 `batch` 處理器

如要更有效率地將遙測資料傳送至 Google Cloud 專案，建議使用 batch 處理器。

舉例來說，Google 內建的 OpenTelemetry Collector 收集器會使用下列批次處理器設定：

batch:
  send_batch_max_size: 200
  send_batch_size: 200
  timeout: 5s

新增 `metricstarttime` 處理器

將 metricstarttime 處理器新增至設定。這個處理器可確保累計指標包含開始時間和觀察時間。根據預設，Prometheus 指標只會包含目前時間。因此，如果您省略這個處理器，且應用程式產生 Prometheus 指標，系統可能會拒絕指標資料，或您可能會看到資料尖峰。

如果收集器會接收 Prometheus 指標，就必須新增這個處理器。

processors:
  # This processor ensures the start time is set for Prometheus metrics.
  # Set in the pipeline before the k8sattributes processor, if used.
  # No-op for OTLP metrics.
  metricstarttime:
    strategy: subtract_initial_point

新增轉換處理器

如要在記錄檔資料中保留插碼來源和版本，請新增下列 transform 處理器：

  transform/otlp_grpc/preserve_instrumentation_source_version:
    error_mode: ignore
    log_statements:
      - context: log
        statements:
          - set(attributes["instrumentation_source"], instrumentation_scope.name) where instrumentation_scope.name != ""
          - set(attributes["instrumentation_version"], instrumentation_scope.version) where instrumentation_scope.version != ""
          - set(attributes["service.name"], resource.attributes["service.name"]) where resource.attributes["service.name"] != nil
          - set(attributes["service.namespace"], resource.attributes["service.namespace"]) where resource.attributes["service.namespace"] != nil
          - set(attributes["service.instance.id"], resource.attributes["service.instance.id"]) where resource.attributes["service.instance.id"] != nil

更新服務管道

接下來，請更新收集器的管道，使用 otlp_grpc/otlp_logs 和 otlphttp 匯出工具。如果是記錄和追蹤資料，這些操作說明會將目前的匯出工具替換為適當的 OTLP 匯出工具。對於指標資料，這些指示會導致雙重寫入。這個方法可讓您確認 OTLP 匯出工具是否將指標資料傳送至 Google Cloud 專案。此外，您也可以在關閉原始匯出工具的資料串流前，更新圖表和快訊政策。

對收集器的管道設定進行下列變更：

將 googleclientauth 擴充功能新增至 service 項目。
在記錄管道中，將 googlecloud/logging 替換為 otlp_grpc/otlp_logs，然後將下列處理器新增至管道的處理器清單：
- resource/gcp_project_id
- transform/otlp_grpc/preserve_instrumentation_source_version
- resourcedetection (如果您新增了這個處理器)
- batch
這項設定會對記錄資料執行單一寫入作業。 如要雙重寫入記錄資料，請將otlp_grpc/otlp_logs匯出工具新增至匯出工具清單。
在指標管道中，將 otlphttp 匯出工具新增至管道的匯出工具清單，並與 googlemanagedprometheus 匯出工具並列，然後新增下列處理器：
- resource/gcp_project_id
- metricstarttime
- resourcedetection (如果您新增了這個處理器)
- batch
這項設定會對指標資料執行雙重寫入作業。驗證指標資料串流，並更新圖表和警告政策後，請移除 Prometheus 匯出工具。
在追蹤管道中，將目前的匯出工具替換為 otlphttp 匯出工具，然後新增下列處理器：
- resource/gcp_project_id
- resourcedetection (如果您新增了這個處理器)
- batch
這項設定會執行單一追蹤記錄資料寫入作業。

變更後的結果如下所示：

service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - transform/otlp_grpc/preserve_instrumentation_source_version
        - batch
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - metricstarttime
        - batch
      exporters: ["googlemanagedprometheus", "otlphttp"]
    traces:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - batch
      exporters: ["otlphttp"]

上述程式碼片段會使用記錄、指標和追蹤資料的 OTLP 接收器。您的收集器設定可能有所不同。舉例來說，如果您有可寫入結構化記錄檔資料的應用程式，則適合使用 filelog 接收器。

驗證設定

重新啟動部署作業，然後確認 otlphttp 和 otlp_grpc/otlp_logs 匯出工具是否將資料傳送至 Google Cloud 專案。如要驗證設定，請按照下列步驟操作：

查詢記錄項目，找出與寫入遙測資料相關的錯誤。
查看 Cloud Logging API、Cloud Monitoring API 和 Telemetry API 的錯誤率。
使用 Metrics Explorer 查看時間序列。

遷移資訊主頁和快訊政策

請按照下列步驟更新圖表和資訊主頁：

如果您使用圖表或快訊政策監控 Cloud Logging API 或 Cloud Monitoring API 的用量，請建立其他圖表或快訊政策，監控 Telemetry API 的用量。
如果指標接收器包含 otlp 接收器，或收集器擷取含有 UTF-8 字元的 Prometheus 指標，請更新圖表和資訊主頁。otlphttp 匯出工具產生的指標與 googlemanagedprometheus 匯出工具不同。詳情請參閱「匯出指標的格式差異」。

如果收集器只接收 Prometheus 指標資料，就不需要更新圖表和資訊主頁。
如果指標管道包含 prometheus 接收器，otlphttp 和 googlemanagedprometheus 匯出工具產生的指標之間就會發生資料串流衝突。如要解決這些衝突，請移除 googlemanagedprometheus 匯出工具。

匯出指標的格式差異

由於 OTLP 和 googlemanagedprometheus匯出工具匯出的指標有下列差異，因此必須更新以指標為準的圖表和快訊政策：

Telemetry API 允許在指標名稱中使用半形句號 (.) 和斜線 (/) 字元。googlemanagedprometheus 匯出工具會將所有這類字元例項轉換為底線 (_) 字元。舉例來說，名為 prometheus.googleapis.com/foo.bar/gauge 的 OTLP 指標會由 OTLP 匯出工具逐字匯出，但會由 googlemanagedprometheus 匯出工具匯出為 prometheus.googleapis.com/foo_bar/gauge。

Cloud Monitoring 會在擷取指標時，根據名稱建立指標描述元。由於擷取路徑處理句號 (.) 和斜線 (/) 字元的方式不同，因此使用 googlemanagedprometheus 匯出工具擷取的指標，與使用 otlphttp 匯出工具擷取的指標，其產生的指標描述元也會有所不同。如果同時使用這兩種擷取路徑，就會有兩組指標；如要查詢完整結果，必須手動合併 Prometheus 和 OTLP 版本的指標結果。
如果指標名稱包含單位，Telemetry API 不會附加單位，也不會附加 _total 後置字串至計數器。因此，使用 Telemetry API 匯出的指標為 prometheus.googleapis.com/foo/counter，但 googlemanagedprometheus 匯出工具匯出的指標為 prometheus.googleapis.com/foo_seconds_total/counter。這項差異也適用於 _total 和 _ratio 後置字元。

如要進一步瞭解指標之間的差異，請參閱「googlemanagedprometheus 匯出工具與 Telemetry API 之間的差異」。

轉換規則不適用於含有 UTF-8 字元的指標。因此，您必須重新編寫資訊主頁和警報政策，才能使用新的指標名稱，或是使用結合新舊指標名稱的查詢。我們不建議編寫處理器規則來重新建立這些轉換，繼續編寫 UTF-8 指標，就好像這些指標是由 googlemanagedprometheus 匯出工具收集一樣。這麼做可保留回溯相容性，但會犧牲前向相容性，且您無法使用參照 UTF-8 指標名稱的開放原始碼資產。

移除特定供應商的匯出者

驗證新資料串流並更新資訊主頁和快訊政策後，請從收集器設定中移除 googlecloud/logging 和 googlemanagedprometheus 匯出工具。您可能也需要移除僅供匯出工具使用的處理器，這些匯出工具已從設定中移除。

您需要更新匯出工具清單和服務管道。

exporters:
  otlphttp: [...]
  otlp_grpc/otlp_logs: [...]

...
service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]
    traces:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]

疑難排解

本節說明如何解決遷移收集器設定時可能發生的失敗問題。

指標資料遺漏或出現尖峰

如果指標資料遺失或出現尖峰，請確認您已將 metricstarttime 處理器新增至收集器的設定。詳情請參閱「新增 metricstarttime 處理器」。

您也可以查看收集器記錄、系統記錄，以及 Monitoring 的資料存取稽核記錄。舉例來說，如果寫入時間序列失敗，系統就會產生包含失敗原因的資料存取稽核記錄。

寫入時間序列時出現的錯誤訊息

系統會在嘗試將資料寫入時間序列失敗時產生錯誤訊息。您可以根據這些訊息瞭解寫入作業失敗的原因，以及如何解決問題。

指出值不符的錯誤訊息：
```
"One or more TimeSeries could not be written: Value type DOUBLE does not match metric descriptor value type INT64."
```
如果您先前傳送 INT64 target_info 指標，就會發生這個錯誤，因為 Telemetry API 會將所有指標的值類型設為 DOUBLE。從長遠來看，最佳解決方案是刪除 INT64 target_info 指標的指標描述元。如要從指標範圍刪除這個描述元，請使用這個 Golang 指令碼。
指出多個來源正在寫入時間序列資料的錯誤訊息：
```
"One or more TimeSeries could not be written: Points must be written in order. One or more of the points specified had an older end time than the most recent point."
```
如要解決這個問題，請從收集器的設定中移除 googlemanagedprometheus 匯出工具。詳情請參閱「移除特定供應商的匯出工具」。

後續步驟

以收集器為基礎的檢測範例總覽：指可供下載及安裝的範例應用程式。每個範例應用程式都包含完整的收集器，可使用 Telemetry API 匯出指標和追蹤資料。
「在 Google Kubernetes Engine 上部署 Google 建構的 OpenTelemetry 收集器」一文提供完整的收集器設定。