v1.logs 總覽

本文說明如何將使用 Telemetry (OTLP) API 傳送至 Google Cloud 專案的記錄檔資料，對應至 Cloud Logging 結構。這個 API 會實作 OpenTelemetry OTLP 通訊協定。使用 otlphttp 匯出工具和 OpenTelemetry Collector 檢測應用程式，或使用 OpenTelemetry SDK 時，您可以將資料傳送至這個 API。

OpenTelemetry 是 Google Cloud支援的開放原始碼專案， Google Cloud有專責工程師確保支援遙測資料的擷取和視覺化。

OTLP 格式記錄資料的一般結構

使用 Telemetry API 將記錄檔資料傳送至 Google Cloud 時，資料格式必須與 OTLP 一致。這類資料的一般結構如下所示：

"resourceLogs": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeLogs": [
        {
          "logRecords": [...]
        }
      ]
    }
]

請注意，OpenTelemetry 會批次處理個別記錄，每筆記錄都以 logRecord 結構表示，並包含記錄來源的相關資訊，以 resource 結構表示。

Google Cloud Observability 收到 resourceLogs 物件時，會為每個 logRecord 建構一個 LogEntry。與 OTLP 不同，後者會將來源資訊與個別記錄的集合批次處理，而每個 LogEntry 結構都包含記錄來源和記錄本身的相關資訊。

如要進一步瞭解 OTLP 格式記錄資料的結構，請參閱 OpenTelemetry logs.proto。

如何處理 OTLP 格式的記錄檔資料

將 OTLP resourceLogs 結構體傳送至 Telemetry API 時，Google Cloud Observability 會執行下列動作：

系統會為每個 logRecord 建立 LogEntry。

下列文件說明系統如何從 OTLP 記錄資料填入 LogEntry：
- OTLP 記錄記錄到記錄項目對應。
- OTLP 屬性至 Cloud Logging 資源類型對應。
由於每個 LogEntry 都包含對應的 Cloud Logging 資源類型資訊，因此每個 LogEntry 可能會大於對應的 OTLP logRecord。

從 OTLP resourceLogs 結構轉換為一系列 LogEntry 結構時，可能會遺失資料。也就是說，您可能無法從 LogEntry 結構轉換為原始的 resource 和 logRecord 欄位。
專案階層中的匯總接收器和專案中的接收器，會以與使用 Cloud Logging API 將記錄項目傳送至專案完全相同的方式，將 LogEntry 轉送至專案。

最佳做法

監測應用程式以將追蹤記錄資料傳送至Google Cloud 專案時，建議您使用匯出工具，將 OTLP 格式的資料寫入 Collector，然後將追蹤記錄資料傳送至 Telemetry API。在收集器中，只指定根網址：

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

OpenTelemetry 會偵測資料類型，並視情況自動附加 /v1/traces、/v1/metrics 或 /v1/logs。詳情請參閱「OTLP/HTTP 要求」。

如需將追蹤或指標資料匯出至 Telemetry API 的範例，請參閱下列文件：

如果無法使用收集器，可以改用含有程序內 OTLP 匯出器的 OpenTelemetry 程式庫，將遙測資料傳送至 Telemetry API。如要瞭解如何直接匯出追蹤資料，請參閱「Cloud Trace exporter to the OTLP endpoint」。

驗證

您必須使用必要憑證設定匯出工具，才能將資料傳送至 Google Cloud 專案。舉例來說，使用收集器時，通常也會使用 googleclientauth 擴充功能，透過 Google 憑證進行驗證。

如需使用直接匯出追蹤資料時的驗證範例，請參閱「設定驗證」。這個範例說明如何使用 Google Cloud 應用程式預設憑證 (ADC) 設定匯出工具，以及如何將特定語言的 Google Auth 程式庫新增至應用程式。

Cloud Logging 和資料落地

根據預設，Cloud Logging 會將專案產生的記錄項目，轉送至系統建立的記錄 bucket。記錄檔值區是區域資源。您可以更新預設記錄檔接收器，將記錄項目傳送至所選位置的自訂記錄檔 bucket。詳情請參閱將記錄區域化。

Cloud Logging 提供可為機構和資料夾設定的設定。這些設定會指定系統建立的新記錄檔 bucket 位置、這些記錄檔 bucket 是否使用客戶自行管理的加密金鑰 (CMEK)，以及預設記錄檔接收器的設定。詳情請參閱「機構和資料夾支援」。

查看擷取資料的位置

您可以使用「記錄檔探索工具」和「Observability Analytics」頁面查看記錄檔資料。詳情請參閱下列文章：

限制

本節將說明相關限制。同時說明 Google Cloud Observability 如何處理特定類型的資料。

限制

說明	值	附註
每個 OTLP 要求的記錄數量上限	8192	是指 OTLP `resourceLogs` 結構中的 `logRecords` 數量上限。限制。
每個要求的最大大小	5 MiB	限制。
從 OTLP 記錄檔記錄建立的 `LogEntry` 大小上限	256 KiB	必要時，Cloud Logging 會截斷或捨棄 OTLP 記錄檔記錄中的資料。限制。
屬性鍵長度上限	512 B	當 OTLP 記錄轉換為 `LogEntry` 時，系統會截斷過大的標籤鍵。限制。
屬性值長度上限	64 KiB	當 OTLP 記錄轉換為 `LogEntry` 時，標籤值過大。限制。
屬性巢狀結構深度上限	5	如果屬性超出此限制，系統會將 OTLP 記錄轉換為 `LogEntry` 時截斷屬性。
每分鐘記錄擷取位元組數上限	以下地區為 2.4 GB：`asia-east1, asia-northeast1, asia-southeast1, asia-south1, europe-west1, europe-west2, europe-west3, europe-west4, us-central1, us-east4, us-west1`。所有其他地區為 300 MB。	配額。

行為

如果同時設定 OpenTelemetry 嚴重性編號和嚴重性文字，系統會使用嚴重性編號判斷 Cloud Logging 嚴重性等級。如果 OTLP 記錄不含嚴重程度資訊，Cloud Logging 嚴重程度層級會設為 DEFAULT。
如果 OTLP 記錄含有重複的屬性鍵，系統會保留第一個鍵，並捨棄含有重複鍵的屬性。
系統會將附加至記錄的屬性轉換為字串。如需範例，請參閱標籤欄位。
記錄檔名稱必須是網址安全名稱，否則系統會在擷取期間進行網址編碼。如要瞭解如何設定記錄名稱，請參閱「如何設定 LogEntry 欄位」。