OTLP 로그 레코드와 로그 항목 간 매핑

이 문서에서는 OTLP 로그 레코드가 Telemetry API를 사용하여 Google Cloud 로 전송될 때 Google Cloud Observability가 해당 레코드에서 LogEntry 필드를 결정하는 방법을 설명합니다.

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` 로그 이름은 URL 보안이어야 하며, 그렇지 않으면 수집 중에 URL로 인코딩됩니다.
`resource`	시스템은 `resource` 필드에 설정된 정보를 사용하거나 리소스를 추론합니다. 자세한 내용은 OTLP 속성-리소스 유형 매핑을 참고하세요.
`timestamp`	시스템은 다음 우선순위가 지정된 OpenTelemetry 로그 레코드 필드 목록을 사용하여 `timestamp`를 결정합니다. 0이 아닌 경우 `time_unix_nano` 0이 아닌 경우 `observed_time_unix_nano` 로그 항목이 수집된 시간입니다. 데이터를 저장하는 로그 버킷의 보관 기간에 따라 수집할 수 있는 가장 오래된 타임스탬프가 결정됩니다. 자세한 내용은 Cloud Logging 할당량을 참고하세요.
`receiveTimestamp`	`LogEntry`이 수집된 시간으로 설정됩니다.
`severity`	시스템은 로그 레코드의 OpenTelemetry 심각도를 Cloud Logging 심각도에 매핑합니다. 자세한 내용은 심각도 필드를 참고하세요.
`httpRequest`	시스템은 로그 레코드의 `gcp.http_request` 속성을 이에 상응하는 `LogEntry` 필드에 매핑합니다. 자세한 내용은 HttpRequest 필드를 참고하세요. FIXME 이 필드에 매핑되는 다른 필드가 있습니다.
`labels`	시스템은 로그 레코드 속성 값을 사용하여 이 필드를 설정합니다. 자세한 내용은 라벨 필드를 참고하세요.
`trace`	시스템은 이 필드를 로그 레코드의 `traceId` 필드 값으로 설정합니다. 값은 유효한 32자 16진수 문자열이어야 합니다. 그렇지 않으면 항목이 거부됩니다.
`spanId`	시스템은 이 필드를 로그 레코드의 `spanId` 필드 값으로 설정합니다. 값은 유효한 16자 16진수 문자열이어야 합니다. 그렇지 않으면 항목이 거부됩니다.
`traceSampled`	설정되지 않았습니다.
`sourceLocation`	시스템은 이 필드를 로그 레코드의 Code 속성 값으로 설정합니다. 자세한 내용은 SourceLocation 필드를 참고하세요.
`split`	설정되지 않았습니다.
`apphub` `apphubDestination` `apphubSource`	설정되지 않았습니다.
`otel`	`LogEntry`에 상응하는 필드가 없는 OTLP 로그 데이터의 필드의 경우 시스템에서 데이터 유형을 변환한 다음 변환된 데이터를 `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`	부울
`cacheHit`	`httpRequest.cacheHit`	부울
`cacheValidatedWithOriginServer`	`httpRequest.cacheValidatedWithOriginServer`	부울
`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`	부울
`gcp.http_request {cacheHit}` `http_request {cacheHit}`	`httpRequest.cacheHit`	부울
`gcp.http_request { cacheValidatedWithOriginServer}` `http_request { cacheValidatedWithOriginServer}`	`httpRequest.cacheValidatedWithOriginServer`	부울
`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",
}
```
속성의 최대 중첩 깊이는 5입니다. 더 깊이 중첩된 콘텐츠는 잘립니다.

Otel 필드

LogEntry에 상응하는 필드가 없는 OTLP 로그 데이터의 필드의 경우 시스템에서 데이터 유형을 변환한 다음 변환된 데이터를 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 쌍의 중첩 깊이가 5보다 큰 경우 시스템은 콘텐츠를 깊이 5로 자릅니다.

심각도 필드

이 섹션에서는 Google Cloud Observability가 OpenTelemetry 심각도 필드를 Cloud Logging 심각도 수준에 매핑하는 방법을 설명합니다. OpenTelemetry는 심각도 번호와 심각도 텍스트를 정의합니다. logs.proto는 심각도 번호를 정의합니다.

Google Cloud Observability는 설정된 경우 OpenTelemetry 심각도 번호에서 로깅 심각도를 확인합니다. 그렇지 않으면 심각도 텍스트를 사용합니다. 둘 다 설정되지 않은 경우 로깅 심각도는 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` 수를 나타냅니다. 한도
각 요청의 최대 크기	5MiB	한도
OTLP 로그 레코드에서 생성된 `LogEntry` 의 최대 크기	256KiB	Cloud Logging은 필요한 경우 OTLP 로그 레코드의 데이터를 자르거나 삭제합니다. 한도
속성 키의 최대 길이	512B	OTLP 로그 레코드가 `LogEntry`로 변환될 때 크기가 초과된 라벨 키가 잘립니다. 한도
속성 값의 최대 길이	64KiB	OTLP 로그 레코드가 `LogEntry`으로 변환될 때 크기가 초과된 라벨 값 한도
속성 중첩의 최대 깊이	5	이 한도를 초과하는 속성은 OTLP 로그 레코드가 `LogEntry`로 변환될 때 잘립니다.
분당 최대 로그 수집 바이트 수	`asia-east1, asia-northeast1, asia-southeast1, asia-south1, europe-west1, europe-west2, europe-west3, europe-west4, us-central1, us-east4, us-west1` 지역의 경우 2.4GB 다른 모든 리전의 경우 300MB	할당량입니다.

동작

OpenTelemetry 심각도 번호와 심각도 텍스트가 모두 설정된 경우 시스템은 심각도 번호를 사용하여 Cloud Logging 심각도 수준을 결정합니다. OTLP 레코드에 심각도 정보가 포함되어 있지 않으면 Cloud Logging 심각도 수준이 DEFAULT로 설정됩니다.
OTLP 레코드에 중복된 속성 키가 포함된 경우 시스템은 첫 번째 키를 유지하고 중복된 키가 있는 속성을 삭제합니다.
시스템은 로그 레코드에 연결된 속성을 문자열로 변환합니다. 예를 보려면 라벨 필드를 참고하세요.
로그 이름은 URL 보안이어야 하며, 그렇지 않으면 수집 중에 URL로 인코딩됩니다. 로그 이름이 설정되는 방식에 관한 자세한 내용은 LogEntry 필드가 설정되는 방식을 참고하세요.