이 문서에서는 Telemetry (OTLP) API를 사용하여 Google Cloud 프로젝트로 전송되는 로그 데이터가 Cloud Logging 구조에 매핑되는 방법을 설명합니다. 이 API는 OpenTelemetry OTLP 프로토콜을 구현합니다. otlphttp 내보내기 도구와 OpenTelemetry 수집기로 애플리케이션을 계측하거나 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를 채우는 방법을 설명합니다.각
LogEntry에는 해당 Cloud Logging 리소스 유형에 관한 정보가 포함되어 있으므로 각LogEntry는 해당 OTLPlogRecord보다 클 수 있습니다.OTLP
resourceLogs구조에서 일련의LogEntry구조로의 변환은 손실이 있을 수 있습니다. 즉,LogEntry구조에서 원래resource및logRecord필드로 변환하지 못할 수도 있습니다.LogEntry는 프로젝트 계층 구조의 집계된 싱크와 프로젝트의 싱크에 의해 라우팅됩니다. 이는 로그 항목이 Cloud Logging API를 사용하여 프로젝트로 전송된 것과 정확히 동일한 방식입니다.
권장사항
Google Cloud 프로젝트에 trace 데이터를 전송하도록 애플리케이션을 계측할 때는 OTLP 형식의 데이터를 수집기에 작성하는 내보내기 도구를 사용하는 것이 좋습니다. 그러면 수집기에서 trace 데이터를 Telemetry API로 전송합니다. 수집기에서 루트 URL만 지정합니다.
exporters:
otlphttp:
encoding: proto
endpoint: https://telemetry.googleapis.com
OpenTelemetry는 데이터 유형을 감지하고 적절한 /v1/traces, /v1/metrics 또는 /v1/logs를 자동으로 추가합니다. 자세한 내용은 OTLP/HTTP 요청을 참고하세요.
추적 또는 측정항목 데이터를 Telemetry API로 내보내는 예시는 다음 문서를 참고하세요.
- 수집기 기반 계측 샘플 개요
- OTLP 측정항목 수집 개요를 참고하세요.
수집기를 사용할 수 없는 경우 프로세스 내 OTLP 내보내기 도구가 포함된 OpenTelemetry 라이브러리를 사용하여 원격 분석을 Telemetry API로 전송할 수 있습니다. 추적 데이터를 직접 내보내는 방법을 알아보려면 Cloud Trace 내보내기 도구에서 OTLP 엔드포인트로를 참고하세요.
인증
Google Cloud 프로젝트로 데이터를 전송하는 데 필요한 사용자 인증 정보로 내보내기 도구를 구성해야 합니다. 예를 들어 수집기를 사용하는 경우 일반적으로 googleclientauth 확장 프로그램을 사용하여 Google 사용자 인증 정보로 인증합니다.
추적 데이터의 직접 내보내기를 사용할 때의 인증 예시는 인증 구성을 참고하세요. 이 예에서는 Google Cloud 애플리케이션 기본 사용자 인증 정보 (ADC)로 내보내기 도구를 구성하고 애플리케이션에 언어별 Google 인증 라이브러리를 추가하는 방법을 보여줍니다.
Cloud Logging 및 데이터 상주
기본적으로 Cloud Logging은 프로젝트에서 시작된 로그 항목을 시스템 생성 로그 버킷으로 라우팅합니다. 로그 버킷은 리전별 리소스입니다. 원하는 위치에 있는 맞춤 로그 버킷으로 로그 항목을 전송하도록 기본 로그 싱크를 업데이트할 수 있습니다. 자세한 내용은 로그 리전화를 참고하세요.
Cloud Logging은 조직 및 폴더에 대해 구성할 수 있는 설정을 제공합니다. 이러한 설정은 새로 시스템에서 생성된 로그 버킷의 위치, 이러한 로그 버킷이 고객 관리 암호화 키(CMEK)를 사용하는지 여부, 기본 로그 싱크의 구성을 지정합니다. 자세한 내용은 조직 및 폴더 지원을 참고하세요.
수집된 데이터를 확인할 수 있는 위치
로그 탐색기 및 관측 가능성 분석 페이지를 사용하여 로그 데이터를 볼 수 있습니다. 자세한 내용은 다음을 참고하세요.
제한사항
이 섹션에서는 한도를 설명합니다. 또한 Google Cloud Observability에서 특정 유형의 데이터를 처리하는 방법도 설명합니다.
한도
| 설명 | 값 | 참고 |
|---|---|---|
| OTLP 요청당 최대 로그 수 | 8192 | OTLP resourceLogs 구조의 최대 logRecords 수를 나타냅니다. 한도 |
| 각 요청의 최대 크기 | 5MiB | 한도 |
OTLP 로그 레코드에서 생성된 LogEntry의 최대 크기 |
256KiB | Cloud Logging은 필요한 경우 OTLP 로그 레코드의 데이터를 자르거나 삭제합니다. 한도 |
| 속성 키의 최대 길이 | 512B | OTLP 로그 레코드가 LogEntry로 변환될 때 크기가 초과된 라벨 키가 잘립니다. 한도 |
| 속성 값의 최대 길이 | 64KiB | OTLP 로그 레코드가 LogEntry으로 변환될 때 크기가 초과된 라벨 값 한도 |
| 속성 중첩의 최대 깊이 | 5 | 이 한도를 초과하는 속성은 OTLP 로그 레코드가 LogEntry로 변환될 때 잘립니다. |
| 분당 최대 로그 수집 바이트 수 |
다른 모든 리전의 경우 300MB |
할당량입니다. |
동작
OpenTelemetry 심각도 번호와 심각도 텍스트가 모두 설정된 경우 시스템은 심각도 번호를 사용하여 Cloud Logging 심각도 수준을 결정합니다. OTLP 레코드에 심각도 정보가 포함되어 있지 않으면 Cloud Logging 심각도 수준이
DEFAULT로 설정됩니다.OTLP 레코드에 중복된 속성 키가 포함된 경우 시스템은 첫 번째 키를 유지하고 중복된 키가 있는 속성을 삭제합니다.
시스템은 로그 레코드에 연결된 속성을 문자열로 변환합니다. 예를 보려면 라벨 필드를 참고하세요.
로그 이름은 URL 보안이어야 하며, 그렇지 않으면 수집 중에 URL로 인코딩됩니다. 로그 이름이 설정되는 방식에 관한 자세한 내용은
LogEntry필드가 설정되는 방식을 참고하세요.