OTLP 記錄記錄到記錄項目的對應

本文說明當 OTLP 記錄傳送至 Telemetry API 時，Google Cloud Observability 如何判斷 LogEntry 的欄位。 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。

如何設定 LogEntry 欄位

Google Cloud Observability 會使用下列規則，判斷 LogEntry 欄位的值：

`LogEntry` 欄位 (HTTP 參照中的名稱)	系統如何判斷欄位值
`logName`	系統會使用下列優先順序清單的 OpenTelemetry 記錄記錄屬性，判斷記錄名稱： `gcp.log_name` `log_name` `event_name` 記錄檔名稱必須使用網址安全字元，否則系統會在擷取期間進行網址編碼。
`resource`	系統會使用 `resource` 欄位中設定的資訊，或推斷資源。詳情請參閱「OTLP 屬性至資源類型對應」。
`timestamp`	系統會使用下列 OpenTelemetry 記錄檔記錄欄位優先順序清單，判斷 `timestamp`： `time_unix_nano` (非零時)。 `observed_time_unix_nano` (非零時)。記錄項目擷取時間。儲存資料的記錄檔 bucket 保留期限，決定了可擷取的舊時間戳記。詳情請參閱「Cloud Logging 配額」。
`receiveTimestamp`	設為 `LogEntry` 的擷取時間。
`severity`	系統會將記錄檔記錄中的 OpenTelemetry 嚴重性對應至 Cloud Logging 嚴重性。詳情請參閱「嚴重程度欄位」。
`httpRequest`	系統會將記錄中的 `gcp.http_request` 屬性對應至對等的 `LogEntry` 欄位。詳情請參閱「HttpRequest 欄位」。 FIXME. 其他欄位會對應至這個欄位。
`labels`	系統會使用記錄檔記錄屬性值設定這個欄位。詳情請參閱「標籤欄位」。
`trace`	系統會將這個欄位設為記錄項目 `traceId` 欄位的值。這個值必須是有效的 32 個半形字元十六進位字串，否則系統會拒絕該項目。
`spanId`	系統會將這個欄位設為記錄項目 `spanId` 欄位的值。值必須是有效的 16 字元十六進位字串，否則系統會拒絕該項目。
`traceSampled`	未設定。
`sourceLocation`	系統會將這個欄位設為記錄項目「Code」屬性的值。詳情請參閱「SourceLocation 欄位」。
`split`	未設定。
`apphub` `apphubDestination` `apphubSource`	未設定。
`otel`	如果 OTLP 記錄資料中的欄位在 `LogEntry` 中沒有對應欄位，系統會轉換資料類型，然後將轉換後的資料新增至 `otel` 欄位。詳情請參閱「Otel 欄位」。
酬載	系統會將記錄的本文轉換為適當的酬載類型，藉此設定酬載。詳情請參閱「酬載欄位」。

HttpRequest 欄位

Google Cloud Observability 會將適用於 HTTP 要求的 OTLP 屬性對應至 LogEntry 欄位。以下各節說明系統如何對應平面和巢狀屬性。

平面屬性

下表說明 Google Cloud Observability 如何將適用於 HTTP 要求的平面屬性對應至 LogEntry 欄位。舉例來說，系統會將屬性 http.request.method: "GET", 的值設為記錄項目中 httpRequest.requestMethod 欄位的值：

OpenTelemetry `LogRecord.attribute` 鍵/值組合。	儲存在下列 `LogEntry` 欄位中的值 (來自 HTTP 參照的名稱)	接受的類型
`http.request.method`	`httpRequest.requestMethod`	字串
`url.full` `http.url`	`httpRequest.requestUrl`	字串
`http.request.body.size`	`httpRequest.requestSize`	字串、整數
`http.response.status_code`	`httpRequest.status`	字串、整數
`http.response.body.size`	`httpRequest.responseSize`	字串、整數
`user_agent.original` `http.user_agent`	`httpRequest.userAgent`	字串
`client.address`	`remoteIp`	字串
`server.address`	`serverIp`	字串
`referrer`	`httpRequest.referer`	字串
`latency`	`httpRequest.latency`	字串、整數
`cacheLookup`	`httpRequest.cacheLookup`	bool
`cacheHit`	`httpRequest.cacheHit`	bool
`cacheValidatedWithOriginServer`	`httpRequest.cacheValidatedWithOriginServer`	bool
`cacheFillBytes`	`httpRequest.cacheFillBytes`	字串、整數
`network.protocol.version` `protocol`	`httpRequest.protocol`	字串

巢狀屬性

本節說明 Google Cloud Observability 如何將適用於 HTTP 要求的巢狀 OTLP 屬性，對應至 LogEntry 中的欄位。以下範例說明包含兩個屬性的記錄，每個屬性至少包含一個其他屬性：

log_record {
  attributes: {
    gcp.http_request {
      "requestMethod": "GET",
      "requestUrl": "some-URL",
    }
    http_request {
      "requestMethod": "GET",
    }
  }
}

在表格中，巢狀屬性會以大括號表示。舉例來說，gcp.http_request {requestMethod} 表示屬性 gcp.http_request 包含屬性 requestMethod。最內層屬性的值會指派給記錄項目欄位的值：

OpenTelemetry `LogRecord.attribute` 鍵/值組合。	儲存在下列 `LogEntry` 欄位中的值 (來自 HTTP 參照的名稱)	接受的類型
`gcp.http_request {requestMethod}` `http_request {requestMethod}`	`httpRequest.requestMethod`	字串
`gcp.http_request {requestUrl}` `http_request {requestUrl}`	`httpRequest.requestUrl`	字串
`gcp.http_request {requestSize}` `http_request {requestSize}`	`httpRequest.requestSize`	字串、整數
`gcp.http_request {status}` `http_request {status}`	`httpRequest.status`	字串、整數
`gcp.http_request {responseSize}` `http_request {responseSize}`	`httpRequest.responseSize`	字串、整數
`gcp.http_request {userAgent}` `http_request {userAgent}`	`httpRequest.userAgent`	字串
`gcp.http_request {remoteIp}` `http_request {remoteIp}`	`httpRequest.remoteIp`	字串
`gcp.http_request {serverIp}` `http_request {serverIp}`	`httpRequest.serverIp`	字串
`gcp.http_request {referer}` `http_request {referrer}`	`httpRequest.referer`	字串
`gcp.http_request {latency}` `http_request {latency}`	`httpRequest.latency`	字串、整數
`gcp.http_request {cacheLookup}` `http_request {cacheLookup}`	`httpRequest.cacheLookup`	bool
`gcp.http_request {cacheHit}` `http_request {cacheHit}`	`httpRequest.cacheHit`	bool
`gcp.http_request { cacheValidatedWithOriginServer}` `http_request { cacheValidatedWithOriginServer}`	`httpRequest.cacheValidatedWithOriginServer`	bool
`gcp.http_request {cacheFillBytes}` `http_request {cacheFillBytes}`	`httpRequest.cacheFillBytes`	字串、整數
`gcp.http_request {protocol}` `http_request {protocol}`	`httpRequest.protocol`	字串

標籤欄位

為判斷要附加至記錄項目的標籤，系統會執行下列動作：

系統會從 OTLP 記錄檔記錄中，移除已對應至特定 LogEntry 欄位的任何屬性。

舉例來說，假設記錄項目附加了下列屬性：

attributes: {
    "log_array_attr: ["value1", "value2"],
    "log_json_attr": {"json_key": "json_value"}
    "log-string-attr": "string",
    "code.file.path": "my-file.cc",
    "code.function.name: "my-func",
    "code.line.number": 123,
    "gcp.http_request": {
        "requestMethod": "GET",
        "requestUrl": "my-URL",
  },
}

移除對應至特定 LogEntry 欄位的欄位後，系統會保留下列欄位：

attributes: {
    "log_array_attr: ["value1", "value2"],
    "log_json_attr": {"json_key": "json_value"}
    "log-string-attr": "string",
}

如果屬性包含陣列或 JSON 元素，系統會將值轉換為字串。

舉例來說，以下說明 LogEntry 如何代表先前的屬性：
```
labels: {
    "log_array_attr": "[\"value1\",\"value2\"]",
    "log_json_attr": "{\"json_key\":\"json_value\"}",
    "log-string-attr": "string",
}
```
屬性的巢狀結構深度上限為五層。任何巢狀結構較深的內容都會遭到截斷。

Otel 欄位

如果 OTLP 記錄資料中的欄位在 LogEntry 中沒有對應欄位，系統會轉換資料類型，然後將轉換後的資料新增至 otel 欄位。舉例來說，otel 欄位會儲存 resource、scope 和 entity 欄位的屬性。

系統會使用下列規則，將 OpenTelemetry 資料類型轉換為 protobuf Value 類型：

OpenTelemetry 類型	protobuf 型別
`string`	`string`
`boolean`	`bool`
`integer`	`double`
`float`	`double`
`Array`	`ListValues`
`KeyValueList`	`Struct`

為避免雙精度錯誤，請以字串形式傳遞整數。

酬載欄位

OTLP logRecord.body 欄位的資料類型會決定 LogEntry 酬載的結構：

string：系統會將字串複製到 LogEntry.textPayload 欄位。
Array：系統會建立陣列元素字串，同時保留新行。然後將字串複製到 LogEntry.textPayload 欄位。
KeyValueList：系統會將這些配對轉換為 JSON，然後填入 LogEntry.jsonPayload 欄位，但有下列限制：
- 如果 OTLP 記錄含有重複的屬性鍵，系統會保留第一個鍵，並捨棄含有重複鍵的屬性。
- 如果 JSON 配對的巢狀結構深度超過五層，系統會將內容截斷至五層深度。

嚴重性欄位

本節說明 Google Cloud Observability 如何將 OpenTelemetry 嚴重程度欄位對應至 Cloud Logging 嚴重程度層級。OpenTelemetry 會定義嚴重程度編號和嚴重程度文字。logs.proto 定義嚴重程度編號。

如果已設定 OpenTelemetry 嚴重性編號，Google Cloud Observability 會根據該編號判斷記錄嚴重性。否則會使用嚴重程度文字。如果兩者皆未設定，記錄嚴重性會設為 DEFAULT。

OpenTelemetry 嚴重程度編號列舉 (值)	OpenTelemetry 嚴重程度文字 (測試不區分大小寫)	Cloud Logging 嚴重程度列舉 (值)
`SEVERITY_NUMBER_UNSPECIFIED` (0)	未設定「default」	`DEFAULT` (0)
`SEVERITY_NUMBER_TRACE` (1) `SEVERITY_NUMBER_TRACE2` (2) `SEVERITY_NUMBER_TRACE3` (3) `SEVERITY_NUMBER_TRACE4` (4)	「trace」「trace2」「trace3」「trace4」	`DEBUG` (100)
`SEVERITY_NUMBER_DEBUG` (5) `SEVERITY_NUMBER_DEBUG2` (6) `SEVERITY_NUMBER_DEBUG3` (7) `SEVERITY_NUMBER_DEBUG4` (8)	「debug」「debug2」「debug3」「debug4」	`DEBUG` (100)
`SEVERITY_NUMBER_INFO` (9) `SEVERITY_NUMBER_INFO2` (10)	「info」「info2」	`INFO` (200)
`SEVERITY_NUMBER_INFO3` (11) `SEVERITY_NUMBER_INFO4` (12)	"notice" "info3" "info4"	`NOTICE` (300)
`SEVERITY_NUMBER_WARN` (13) `SEVERITY_NUMBER_WARN2` (14) `SEVERITY_NUMBER_WARN3` (15) `SEVERITY_NUMBER_WARN4` (16)	「warning」「warn」「warn2」「warn3」「warn4」	`WARNING` (400)
`SEVERITY_NUMBER_ERROR` (17) `SEVERITY_NUMBER_ERROR2` (18) `SEVERITY_NUMBER_ERROR3` (19) `SEVERITY_NUMBER_ERROR4` (20)	「error」「error2」「error3」「error4」	`ERROR` (500)
`SEVERITY_NUMBER_FATAL` (21) `SEVERITY_NUMBER_FATAL2` (22)	「critical」「fatal」「fatal2」	`CRITICAL` (600)
`SEVERITY_NUMBER_FATAL3` (23)	"alert" "fatal3"	`ALERT` (700)
`SEVERITY_NUMBER_FATAL4` (24)	"emergency" "fatal4"	`EMERGENCY` (800)

SourceLocation 欄位

Google Cloud Observability 會將下列 OTLP Code 直接對應至 LogEntry 欄位。由於這些 OpenTelemetry 屬性在語意上與 Cloud Logging 概念相同，因此可以進行對應。

OpenTelemetry `LogRecord.attribute` 鍵/值組合。	儲存在下列 `LogEntry` 欄位中的值 (來自 HTTP 參照的名稱)	接受的類型
`code.file.path: Value`	`sourceLocation.file`	字串
`code.function.name: Value`	`sourceLocation.function`	字串
`code.function.number: Value`	`sourceLocation.line`	字串、整數

限制

本節將說明相關限制。同時說明 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 欄位」。