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

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

本文說明 Google Cloud Observability 如何根據 OTLP 記錄，判斷 LogEntry 的欄位，前提是該記錄是透過 Telemetry API 傳送至 Google Cloud 。

Cloud Logging 的 Google Cloud 匯出工具會將 OTLP 格式的記錄資料轉換為 LogEntry 物件。然後使用 Cloud Logging API 將這些資料傳送至您的 Google Cloud 專案。不過，Google Cloud Observability 和匯出工具用來建構記錄項目的預設規則不同。詳情請參閱「設定 Google Cloud Observability 以使用匯出工具對應」。

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`	系統會使用 OTLP `LogRecord` 的 `event_name` 欄位值。如果該欄位不存在或未設定，系統會使用下列 OpenTelemetry 記錄屬性優先順序清單，判斷記錄名稱： `log.name` `gcp.log.name` `log_name` `gcp.log_name` `logging.googleapis.com/logName` `service.name` `gcp.service.name` `service_name` `gcp.service_name` `event.name` `gcp.event.name` `event_name` `gcp.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` 欄位。系統接受這些屬性做為結構化屬性或 JSON 字串。詳情請參閱「HttpRequest 欄位」。
`labels`	系統會使用記錄檔記錄屬性值設定這個欄位。詳情請參閱「標籤欄位」。
`trace`	系統會將這個欄位設為記錄檔 `traceId` 欄位的值。值必須是有效的 32 個字元十六進位字串，否則系統會拒絕該項目。
`spanId`	系統會將這個欄位設為記錄檔 `spanId` 欄位的值。值必須是有效的 16 個字元十六進位字串，否則系統會拒絕該項目。
`traceSampled`	系統會根據記錄檔記錄 `flags` 欄位的最低有效位元，設定這個欄位。如果最低有效位元等於 `1`，這個欄位會設為 `true`，否則會維持未設定狀態。
`sourceLocation`	系統會將這個欄位設為記錄檔 Code 屬性的值。詳情請參閱「SourceLocation 欄位」。
`split`	未設定。
`apphub` `apphubDestination` `apphubSource`	未設定。
`otel`	如果 OTLP 記錄資料中的欄位在 `LogEntry` 中沒有對應欄位，系統會轉換資料類型，然後將轉換後的資料新增至 `otel` 欄位。詳情請參閱「Otel 欄位」。
`operation`	系統會將記錄中的 `gcp.operation` 屬性對應至相等的 `LogEntry` 欄位。詳情請參閱「作業欄位」。
酬載	系統會將記錄檔主體轉換為適當的酬載類型，藉此設定酬載。詳情請參閱「酬載欄位」。

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`	string, int
`http.response.status_code`	`httpRequest.status`	string, int
`http.response.body.size`	`httpRequest.responseSize`	string, int
`user_agent.original` `http.user_agent`	`httpRequest.userAgent`	字串
`client.address`	`remoteIp`	字串
`server.address`	`serverIp`	字串
`referrer`	`httpRequest.referer`	字串
`latency`	`httpRequest.latency`	string, int
`cacheLookup`	`httpRequest.cacheLookup`	bool
`cacheHit`	`httpRequest.cacheHit`	bool
`cacheValidatedWithOriginServer`	`httpRequest.cacheValidatedWithOriginServer`	bool
`cacheFillBytes`	`httpRequest.cacheFillBytes`	string, int
`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 欄位的格式可以是結構化巢狀屬性，也可以是結構化屬性的 JSON 字串。

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

在表格中，巢狀屬性會以大括號表示。舉例來說，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`	string, int
`gcp.http_request {status}` `http_request {status}`	`httpRequest.status`	string, int
`gcp.http_request {responseSize}` `http_request {responseSize}`	`httpRequest.responseSize`	string, int
`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`	string, int
`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`	string, int
`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",
}
```
屬性的巢狀深度上限為五。任何巢狀結構更深的內容都會遭到截斷。

作業欄位

Google Cloud Observability 會將適用於作業的 OTLP 屬性，對應至 LogEntry 的 operation 欄位。以下各節說明系統如何對應巢狀屬性。

gcp.operation 屬性必須包含鍵/值類型。不支援扁平化屬性名稱。以下範例說明記錄，其 gcp.operation 屬性包含四個鍵/值組合：

log_record {
  attributes: {
    gcp.operation {
      "id": "abc123",
      "producer": "my_producer",
      "first": "true",
      "last": "false",
    }
  }
}

下表說明 Google Cloud Observability 如何將 gcp.operation 對應至 LogEntry：

OpenTelemetry `LogRecord.attribute.operation` 鍵/值組合。	儲存在下列 `LogEntry` 作業欄位中的值	接受的類型
`id`	`id`	字串
`producer`	`httpRequest.requestUrl`	字串
`first`	`first`	bool
`last`	`last`	bool

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 定義嚴重性編號。

Google Cloud Observability 會根據 OpenTelemetry 嚴重性編號 (如有設定) 判斷 Logging 嚴重性。否則，系統會使用嚴重性文字。如果兩者皆未設定，Logging 嚴重程度會設為 DEFAULT。

OpenTelemetry 嚴重程度編號列舉 (值)	OpenTelemetry 嚴重性文字 (測試不區分大小寫)	Cloud Logging 嚴重性列舉 (值)
`SEVERITY_NUMBER_UNSPECIFIED` (0)	「預設」未設定	`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 程式碼直接對應至 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`	string, int

限制

本節說明限制。並說明 Google Cloud Observability 如何處理特定類型的資料。

限制

說明	值	附註
每項 OTLP 要求的記錄數量上限	8192	是指 OTLP `resourceLogs` 結構中的 `logRecords` 數量上限。Limit。
每項要求的大小上限	5 MiB	Limit。
從 OTLP 記錄建立的 `LogEntry` 大小上限	256 KiB	Cloud Logging 會視需要截斷或捨棄 OTLP 記錄中的資料。Limit。
屬性鍵長度上限	512 B	將 OTLP 記錄轉換為 `LogEntry` 時，系統會截斷過大的標籤鍵。Limit。
屬性值長度上限	64 KiB	將 OTLP 記錄轉換為 `LogEntry` 時，標籤值過大。Limit。
屬性巢狀結構的最大深度	20	如果 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 欄位的設定方式」。

設定 Google Cloud Observability，使用匯出工具對應

Google Cloud Observability 和 Cloud Logging 的 Google Cloud 匯出工具會使用不同的規則，從 OTLP 格式的記錄資料建構 LogEntry 物件。舉例來說，Google Cloud Observability 會填入 otel 欄位，但匯出工具不會。

如果您希望 Google Cloud Observability 使用與匯出工具相同的對應規則，請對將 OTLP 記錄檔記錄傳送至 Telemetry API 的應用程式進行下列變更：

將 gcp.use_legacy_mapping 屬性新增至要求中包含的資源。詳情請參閱「新增或刪除屬性」。

設定這項屬性後，會發生下列情況：
1. otel 欄位未填入任何內容。
2. 開頭為 gcp 的屬性會遭到捨棄，但下列情況除外：
  - gcp.log.name
  - gcp.insert_id
  前兩個屬性會對應至 LogEntry 欄位。
舊版對應規則會導致 Google Cloud Observability 捨棄部分內容。不過，LogEntry 物件的大小較小。
在 OTLP HTTP 收集器中新增處理器，設定下列記錄標籤：
- instrumentation_scope：設為 instrumentation_scope.name。
- instrumentation_version：設為 instrumentation_scope.version。
- service.name：設為 resource.attributes["service.name"]。
- service.namespace：設為 resource.attributes["service.namespace"]。
- service.instance.id：設為 resource.attributes["service.instance.id"]。
如需範例，請參閱「遷移至 OTLP 匯出工具：處理器」。