이 문서에서는 Telemetry (OTLP) API를 사용하여 Google Cloud 프로젝트로 전송되는 로그 데이터가 Cloud Logging 구조에 매핑되는 방법을 설명합니다. 이 API는 OpenTelemetry 프로토콜을 구현합니다. `
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 형식 로그 데이터 처리 방법
Telemetry API로 OTLP resourceLogs 구조를 전송하면 Google Cloud Observability가 다음 작업을 수행합니다.
각
logRecord에 대해 시스템은LogEntry를 만듭니다.다음 문서에서는 시스템이 OTLP 로그 데이터에서
LogEntry를 채우는 방법을 설명합니다.각
LogEntry에는 상응하는 Cloud Logging 리소스 유형에 대한 정보가 포함되어 있으므로 각LogEntry는 상응하는 OTLPlogRecord보다 클 수 있습니다.OTLP
resourceLogs구조에서 일련의LogEntry구조로의 변환은 손실될 수 있습니다. 즉,LogEntry구조에서 원래resource및logRecord필드로 변환하지 못할 수 있습니다.LogEntry는 로그 항목이 Cloud Logging API를 사용하여 프로젝트로 전송된 것과 정확히 동일한 방식으로 프로젝트 계층 구조의 집계된 싱크와 프로젝트의 싱크에 의해 라우팅됩니다.
권장사항
trace 데이터를 Google Cloud 프로젝트로 전송하도록 애플리케이션을 계측할 때는 OTLP 형식 데이터를 수집기에 작성하는 내보내기 도구를 사용하는 것이 좋습니다. 그러면 수집기에서 trace 데이터를 Telemetry API로 전송합니다. 수집기에서 루트 URL만 지정합니다.
exporters:
otlphttp:
encoding: proto
endpoint: https://telemetry.googleapis.com
OpenTelemetry는 데이터 유형을 감지하고 적절하게 /v1/traces, /v1/metrics 또는 /v1/logs를 자동으로 추가합니다. 자세한 내용은
OTLP/HTTP 요청을 참고하세요.
trace 또는 측정항목 데이터를 Telemetry API로 내보내는 예는 다음 문서를 참고하세요.
수집기를 사용할 수 없는 경우 프로세스 내 OTLP 내보내기 도구가 포함된 OpenTelemetry 라이브러리를 사용하여 원격 분석을 Telemetry API로 전송할 수 있습니다. trace 데이터를 직접 내보내는 방법을 알아보려면 Cloud Trace 내보내기 도구에서 OTLP 엔드포인트로를 참고하세요.
인증
프로젝트 Google Cloud 로 데이터를 전송하는 데 필요한 사용자 인증 정보로 내보내기 도구를 구성해야 합니다. 예를 들어 수집기를 사용하는 경우 일반적으로 googleclientauth 확장 프로그램을 사용하여 Google 사용자 인증 정보로 인증합니다.
trace 데이터의 직접 내보내기를 사용할 때 인증의 예는 인증 구성을 참고하세요. 이 예에서는 Google Cloud애플리케이션 기본 사용자 인증 정보 (ADC)로 내보내기 도구를 구성하고 애플리케이션에 언어별 Google 인증 라이브러리를 추가하는 방법을 보여줍니다.
Telemetry API를 사용하여 Google Cloud 프로젝트로 원격 분석 데이터를 전송하려면 다음 작업도 수행해야 합니다.
할당량 프로젝트를 구성합니다. 자세한 내용은 할당량 프로젝트 설정을 참고하세요.
애플리케이션에서 사용하는 사용자 또는 서비스 계정에 다음 ID 및 액세스 관리 (IAM) 역할을 부여합니다.
- 서비스 사용량 소비자
역할 (
roles/serviceusage.serviceUsageConsumer) 할당량 프로젝트 - Cloud Telemetry 작성자
역할 (
roles/telemetry.writer) 이 역할을 사용하면 애플리케이션에서 로그, 측정항목, trace 데이터를 쓸 수 있습니다.
- 서비스 사용량 소비자
역할 (
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 잘립니다. |
| 분당 최대 로그 수집 바이트 수 | 다음 리전의 경우 2.4GB: 기타 모든 리전의 경우 300MB |
할당량 |
행동
OpenTelemetry 심각도 번호와 심각도 텍스트가 모두 설정된 경우 시스템은 심각도 번호를 사용하여 Cloud Logging 심각도 수준을 결정합니다. OTLP 레코드에 심각도 정보가 포함되어 있지 않으면 Cloud Logging 심각도 수준이
DEFAULT로 설정됩니다.OTLP 레코드에 중복된 속성 키가 포함되어 있으면 시스템은 첫 번째 키를 유지하고 중복된 키가 있는 속성을 삭제합니다.
시스템은 로그 레코드에 연결된 속성을 문자열로 변환합니다. 예를 보려면 라벨 필드를 참고하세요.
로그 이름은 URL 보안 문자여야 하며, 그렇지 않으면 수집 중에 URL로 인코딩됩니다. 로그 이름이 설정되는 방법에 대한 자세한 내용은
LogEntry필드가 설정되는 방법을 참고하세요.
할당량
Telemetry API와 연결된 할당량에 대한 자세한 내용은 Telemetry API 한도를 참고하세요.