Telemetry (OTLP) API는
OpenTelemetry Protocol의 구현입니다. OTLP를 지원하면 공급업체별 내보내기 도구를 사용하지 않고도 일반 otlphttp 및 otlp_grpc/otlp_logs 내보내기 도구를 수집기 구성에 추가할 수 있습니다. 애플리케이션은 로그, 측정항목, trace 데이터를 Telemetry API로 전송할 수 있습니다.
이 가이드는 수집기의 구성에서
googlecloud 내보내기 도구 또는
googlemanagedprometheus 내보내기 도구를 사용하는 경우에 적용됩니다.
로그 데이터:
googlecloud내보내기 도구에서otlp_grpc/otlp_logs내보내기 도구로 이전합니다.측정항목 데이터:
googlemanagedprometheus내보내기 도구에서otlphttp내보내기 도구로 이전합니다.trace 데이터:
googlecloud내보내기 도구에서otlphttp내보내기 도구로 이전합니다.
OTLP 내보내기 도구로 이전하려면 다음 단계를 수행하세요.
- Telemetry API 사용 설정
- 수집기 서비스 계정 승인
GOOGLE_CLOUD_PROJECT환경 변수 설정googleclientauth확장 프로그램 추가otlphttp및otlp_grpc/otlp_logs내보내기 도구 추가- 프로세서 추가
- 서비스 파이프라인 업데이트
- 구성 검증
- 대시보드 및 알림 정책 이전
- 공급업체별 내보내기 도구 삭제
Telemetry API 사용 설정
OTLP 내보내기 도구는 Telemetry API에 쓰므로 프로젝트에서 해당 API를 사용 설정해야 합니다. Telemetry API를 사용 설정하려면 다음 명령어를 실행하세요.
gcloud services enable telemetry.googleapis.com
수집기 서비스 계정 승인
수집기는 실행되는 환경의 ID를 사용하여 Google Cloud API에 대해 인증합니다. 수집기를 실행하는 서비스 계정에는 Telemetry API를 사용하여 로그, 측정항목, trace 데이터를 쓸 수 있는 권한이 있어야 합니다. 또한 Telemetry API는 소비자 API이므로 API 호출에서 할당량을 사용하는 Google Cloud 프로젝트를 명시적으로 지정하고 서비스 계정에 해당 프로젝트의 할당량을 사용하는 데 필요한 권한을 부여해야 합니다.
필요한 역할
수집기를 실행하는 서비스 계정에 로그, 측정항목, trace 데이터를 전송하는 데 필요한 권한이 있는지 확인하려면 관리자에게 프로젝트에서 수집기를 실행하는 서비스 계정에 다음 IAM 역할을 부여해 달라고 요청하세요.
- Cloud 원격 분석 작성자 (
roles/telemetry.writer) - 서비스 사용량 소비자 (
roles/serviceusage.serviceUsageConsumer)
이러한 사전 정의된 역할에는 로그, 측정항목, trace 데이터를 전송하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.
필수 권한
로그, 측정항목, trace 데이터를 전송하려면 다음 권한이 필요합니다.
-
logging.logEntries.create -
monitoring.timeSeries.create -
telemetry.traces.write -
serviceusage.services.use
Kubernetes 서비스 계정
GKE용 워크로드 아이덴티티 제휴를 사용하여 Google Kubernetes Engine (GKE)에 수집기를 배포하는 경우 Kubernetes 서비스 계정에 필요한 역할을 부여합니다.
API 할당량이 Telemetry API 호출의 대상인 동일한 Google Cloud 프로젝트에서 가져오는 경우 다음 명령어를 사용하여 필요한 역할을 부여할 수 있습니다. 명령어를 실행하기 전에 PROJECT_ID를 프로젝트의 ID로 바꿉니다. 하지만 별도의 할당량 프로젝트를 사용하는 경우 두 번째 명령어에서 PROJECT_ID를 할당량 프로젝트의 ID로 바꿉니다.
export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
gcloud projects add-iam-policy-binding PROJECT_ID \
--role=roles/telemetry.writer \
--member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
--condition=None
gcloud projects add-iam-policy-binding PROJECT_ID \
--role=roles/serviceusage.serviceUsageConsumer \
--member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
--condition=None
GKE용 워크로드 아이덴티티 제휴 서비스 계정
GKE용 워크로드 아이덴티티 제휴 서비스 계정을 구성한 경우 Google Cloud Managed Service for Prometheus 문서의 명령어를 사용하여 서비스 계정을 승인할 수 있습니다. 단, 다음과 같이 변경해야 합니다.
gmp-test-sa를 서비스 계정의 이름으로 바꿉니다.- 명령어를 실행하여 필요한 역할 을 부여하여 로그, 측정항목, trace 데이터를 씁니다.
기타 서비스 계정
Compute Engine VM 또는 GKE 외부에서 수집기를 실행하는 경우 배포에서 사용하는 서비스 계정에 필요한 역할 을 Google Cloud 부여합니다.
GOOGLE_CLOUD_PROJECT 환경 변수 설정
수집기 배포에서 GOOGLE_CLOUD_PROJECT 환경 변수를 설정합니다. 다음과 유사한 결과가 표시됩니다.
env:
- name: GOOGLE_CLOUD_PROJECT
value: PROJECT_ID
googleclientauth 확장 프로그램 추가
수집기 구성에 googleclientauth 확장 프로그램을 추가합니다.
Telemetry API는 소비자 API이며
프로젝트 Google Cloud 와 할당량 프로젝트를 모두 지정해야 합니다. 결과는 다음과 유사합니다.
extensions:
googleclientauth:
project: ${GOOGLE_CLOUD_PROJECT}
quota_project: ${GOOGLE_CLOUD_PROJECT}
otlphttp 및 otlp_grpc/otlp_logs 내보내기 도구 추가
otlphttp 내보내기 도구를 사용하여 OTLP 형식의 측정항목 및 trace 데이터를 프로젝트로 전송하고 otlp_grpc/otlp_logs 내보내기 도구를 사용하여 로그 데이터를 전송합니다.
googleclientauth 확장 프로그램으로 두 내보내기 도구를 모두 구성해야 합니다.
결과는 다음과 유사합니다.
exporters:
# ... existing content ...
otlphttp:
encoding: proto
endpoint: https://telemetry.googleapis.com
auth:
authenticator: googleclientauth
otlp_grpc/otlp_logs:
auth:
authenticator: googleclientauth
balancer_name: pick_first
endpoint: telemetry.googleapis.com:443
otlp_grpc/otlp_logs 내보내기 도구의 경우 endpoint 필드를 host:port 형식을 사용하여 지정해야 합니다.
프로세서 추가
이 섹션에는 수집기에 추가해야 하는 프로세서가 나와 있습니다. 사용할 수 있는 다른 프로세서도 있습니다. 예를 들어 Google 기반의 OpenTelemetry Collector 수집기 구성에는 일반적으로 memory_limiter 프로세서와 측정항목 데이터를 변환하는 프로세서가 포함됩니다. 예를 보려면
GKE의 Google 기반 OpenTelemetry Collector를 참조하세요.
resource/gcp_project_id 프로세서 추가
Google Cloud 프로젝트에 관한 정보를 캡처하는 resource 프로세서를 추가합니다.
resource/gcp_project_id:
attributes:
- action: insert
value: ${GOOGLE_CLOUD_PROJECT}
key: gcp.project_id
resourcedetection 프로세서 추가
에서 실행하는 경우 Google Cloud프로세서를 추가하는 것이 좋습니다.
resourcedetection 이 프로세서는 아키텍처에 관한 정보를 자동으로 검색할 수 있습니다.
다음 구성은 표준 OpenTelemetry 환경 변수를 찾은 후 Google Cloud 메타데이터 서버를 쿼리하여 인프라에 관한 정보를 수집합니다.
resourcedetection:
detectors: ["env", "gcp"]
batch 프로세서 추가
원격 분석을 프로젝트로 Google Cloud 더 효율적으로 전송하려면
batch 프로세서를 사용하는 것이 좋습니다.
예를 들어 Google 기반의 OpenTelemetry Collector 수집기는 일괄 처리 프로세서에 다음 구성을 사용합니다.
batch:
send_batch_max_size: 200
send_batch_size: 200
timeout: 5s
metricstarttime 프로세서 추가
구성에 metricstarttime 프로세서를 추가합니다. 이 프로세서는 누적 측정항목에 시작 시간과 관찰 시간이 모두 포함되도록 합니다. 기본적으로 Prometheus 측정항목에는 현재 시간만 포함됩니다.
따라서 이 프로세서를 생략하고 애플리케이션에서 Prometheus 측정항목을 생성하는 경우 측정항목 데이터가 거부되거나 데이터 급증이 발생할 수 있습니다.
수집기가 Prometheus 측정항목을 수신하는 경우 이 프로세서를 추가해야 합니다.
processors:
# This processor ensures the start time is set for Prometheus metrics.
# Set in the pipeline before the k8sattributes processor, if used.
# No-op for OTLP metrics.
metricstarttime:
strategy: subtract_initial_point
변환 프로세서 추가
로그 데이터에서 계측 소스 및 버전을 유지하려면 다음 transform 프로세서를 추가하세요.
transform/otlp_grpc/preserve_instrumentation_source_version:
error_mode: ignore
log_statements:
- context: log
statements:
- set(attributes["instrumentation_source"], instrumentation_scope.name) where instrumentation_scope.name != ""
- set(attributes["instrumentation_version"], instrumentation_scope.version) where instrumentation_scope.version != ""
- set(attributes["service.name"], resource.attributes["service.name"]) where resource.attributes["service.name"] != nil
- set(attributes["service.namespace"], resource.attributes["service.namespace"]) where resource.attributes["service.namespace"] != nil
- set(attributes["service.instance.id"], resource.attributes["service.instance.id"]) where resource.attributes["service.instance.id"] != nil
서비스 파이프라인 업데이트
다음으로 otlp_grpc/otlp_logs 및 otlphttp 내보내기 도구를 사용하도록 수집기의 파이프라인을 업데이트합니다. 로그 및 trace 데이터의 경우 이러한 안내에 따라 현재 내보내기 도구가 적절한 OTLP 내보내기 도구로 대체됩니다. 측정항목 데이터의 경우 이러한 안내에 따라 이중 쓰기가 발생합니다. 이 접근 방식을 사용하면 OTLP 내보내기 도구가
측정항목 데이터를 프로젝트로 전송하는지 확인할 수 있습니다. Google Cloud 또한 원래 내보내기 도구의 데이터 스트림을 중지하기 전에 차트와 알림 정책을 업데이트할 수 있습니다.
수집기의 파이프라인 구성을 다음과 같이 변경합니다.
service항목에googleclientauth확장 프로그램을 추가합니다.로그 파이프라인의 경우
googlecloud/logging을otlp_grpc/otlp_logs로 바꾼 후 다음 프로세서를 파이프라인의 프로세서 목록에 추가합니다.resource/gcp_project_idtransform/otlp_grpc/preserve_instrumentation_source_versionresourcedetection(이 프로세서를 추가한 경우)batch
이 구성은 로그 데이터의 단일 쓰기를 수행합니다. 로그 데이터를 이중 쓰기하려면 내보내기 도구 목록에
otlp_grpc/otlp_logs내보내기 도구를 추가합니다.측정항목 파이프라인의 경우
googlemanagedprometheus내보내기 도구와 함께otlphttp내보내기 도구를 파이프라인의 내보내기 도구 목록에 추가한 후 다음 프로세서를 추가합니다.resource/gcp_project_idmetricstarttimeresourcedetection(이 프로세서를 추가한 경우)batch
이 구성은 측정항목 데이터의 이중 쓰기를 수행합니다. 측정항목 데이터 스트림을 검증하고 차트와 알림 정책을 업데이트한 후 Prometheus 내보내기 도구를 삭제합니다.
trace 파이프라인의 경우 현재 내보내기 도구를
otlphttp내보내기 도구로 바꾼 후 다음 프로세서를 추가합니다.resource/gcp_project_idresourcedetection(이 프로세서를 추가한 경우)batch
이 구성은 trace 데이터의 단일 쓰기를 수행합니다.
이러한 변경사항의 결과는 다음과 유사합니다.
service:
extensions: ["googleclientauth"]
pipelines:
logs:
receivers: ["otlp"]
processors:
- resourcedetection
- resource/gcp_project_id
- transform/otlp_grpc/preserve_instrumentation_source_version
- batch
exporters: ["otlp_grpc/otlp_logs"]
metrics:
receivers: ["otlp"]
processors:
- resourcedetection
- resource/gcp_project_id
- metricstarttime
- batch
exporters: ["googlemanagedprometheus", "otlphttp"]
traces:
receivers: ["otlp"]
processors:
- resourcedetection
- resource/gcp_project_id
- batch
exporters: ["otlphttp"]
앞의 스니펫은 로그, 측정항목, trace 데이터에 OTLP 수신기를 사용합니다. 수집기 구성은 다를 수 있습니다. 예를 들어 구조화된 로그 데이터를 쓰는 애플리케이션이 있는 경우 filelog 수신기가 적합합니다.
구성 검증
배포를 다시 시작한 후 otlphttp 및
otlp_grpc/otlp_logs 내보내기 도구가 데이터를 Google Cloud 프로젝트로 전송하는지 확인합니다.
구성을 확인하려면 다음을 수행하세요.
- 원격 분석 데이터 쓰기와 관련된 오류에 대해 로그 항목을 쿼리합니다.
- Cloud Logging API, Cloud Monitoring API, Telemetry API의 오류율을 봅니다.
- 측정항목 탐색기를 사용하여 시계열을 봅니다.
대시보드 및 알림 정책 이전
다음과 같이 차트와 대시보드를 업데이트합니다.
차트 또는 알림 정책으로 Cloud Logging API 또는 Cloud Monitoring API의 사용량을 모니터링하는 경우 Telemetry API의 사용량을 모니터링하기 위한 추가 차트 또는 알림 정책을 만듭니다.
측정항목 수신기에
otlp수신기가 포함되어 있거나 수집기가 UTF-8 문자로 Prometheus 측정항목을 스크래핑하는 경우 차트와 대시보드를 업데이트합니다.otlphttp내보내기 도구는googlemanagedprometheus내보내기 도구와 다른 측정항목을 생성합니다. 자세한 내용은 내보낸 측정항목 형식의 차이점을 참조하세요.수집기가 Prometheus 측정항목 데이터만 수신하는 경우 차트와 대시보드를 업데이트할 필요가 없습니다.
측정항목 파이프라인에
prometheus수신기가 포함되어 있으면 데이터 스트림 충돌이otlphttp및googlemanagedprometheus내보내기 도구에서 생성된 측정항목 간에 발생합니다. 이러한 충돌을 해결하려면googlemanagedprometheus내보내기 도구를 삭제합니다.
내보낸 측정항목 형식의 차이점
OTLP 및 googlemanagedprometheus 내보내기 도구에서 내보낸 측정항목 간의 다음과 같은 차이점으로 인해 측정항목 기반 차트 및 알림 정책을 업데이트해야 합니다.
Telemetry API를 사용하면 측정항목 이름에 마침표 (
.) 및 슬래시 (/) 문자를 사용할 수 있습니다.googlemanagedprometheus내보내기 도구는 이러한 문자의 모든 인스턴스를 밑줄 (_) 문자로 변환합니다. 예를 들어prometheus.googleapis.com/foo.bar/gauge라는 OTLP 측정항목은 OTLP 내보내기 도구에서 그대로 내보내지만googlemanagedprometheus내보내기 도구에서는prometheus.googleapis.com/foo_bar/gauge로 내보냅니다.측정항목이 수집되면 Cloud Monitoring은 이름을 기반으로 측정항목 설명자를 만듭니다. 수집 경로에서 마침표 (
.) 및 슬래시 (/) 문자를 처리하는 방식의 차이로 인해 결과 측정항목 설명자가googlemanagedprometheus내보내기 도구를 사용하여 수집된 측정항목과otlphttp내보내기 도구를 사용하여 수집된 측정항목 간에 다릅니다. 두 수집 경로를 모두 사용하는 경우 두 개의 측정항목 세트가 있습니다. 쿼리할 때 완전한 결과를 얻으려면 Prometheus 및 OTLP 버전의 측정항목에서 결과를 수동으로 통합해야 합니다.Telemetry API는 단위가 있는 경우 측정항목 이름에 단위를 추가하지 않으며 카운터에
_total서픽스를 추가하지 않습니다. 따라서 Telemetry API를 사용할 때prometheus.googleapis.com/foo/counter로 내보낸 측정항목은googlemanagedprometheus내보내기 도구에서prometheus.googleapis.com/foo_seconds_total/counter로 내보냅니다. 이 차이는_total및_ratio서픽스에도 적용됩니다.
측정항목 간의 차이점에 관한 자세한 내용은
googlemanagedprometheus 내보내기 도구와
Telemetry API의 차이점을 참조하세요.
변환 규칙은 UTF-8 문자가 포함된 측정항목에는 적용되지 않습니다. 따라서 새 측정항목 이름을 사용하거나 이전 측정항목 이름과 새 측정항목 이름을 결합하는 쿼리를 사용하도록 대시보드와 알림 정책을 다시 작성해야 합니다.
googlemanagedprometheus 내보내기 도구에서 수집한 것처럼 UTF-8 측정항목을 계속 작성하기 위해 이러한
변환을 다시 만드는 프로세서 규칙을 작성하지 않는 것이 좋습니다. 이렇게 하면 이전 버전과의 호환성이 유지되지만 이후 버전과의 호환성이 저하되고 UTF-8 측정항목 이름을 참조하는 오픈소스 애셋을 사용할 수 없습니다.
공급업체별 내보내기 도구 삭제
새 데이터 스트림을 검증하고 대시보드와 알림 정책을 업데이트한 후 수집기 구성에서 googlecloud/logging 및 googlemanagedprometheus 내보내기 도구를 삭제합니다. 구성에서 삭제된 내보내기 도구에서만 사용된 프로세서를 삭제해야 할 수도 있습니다.
내보내기 도구 목록과 서비스 파이프라인을 모두 업데이트해야 합니다.
exporters:
otlphttp: [...]
otlp_grpc/otlp_logs: [...]
...
service:
extensions: ["googleclientauth"]
pipelines:
logs:
receivers: ["otlp"]
processors: [...]
exporters: ["otlp_grpc/otlp_logs"]
metrics:
receivers: ["otlp"]
processors: [...]
exporters: ["otlphttp"]
traces:
receivers: ["otlp"]
processors: [...]
exporters: ["otlphttp"]
문제 해결
이 섹션에서는 수집기의 구성을 이전할 때 발생할 수 있는 실패를 해결하는 방법을 설명합니다.
측정항목 데이터 누락 또는 측정항목 데이터 급증
측정항목 데이터가 누락되었거나 급증이 포함되어 있는 경우 수집기의 구성에 metricstarttime 프로세서를 추가했는지 확인합니다.
자세한 내용은
metricstarttime 프로세서 추가를 참조하세요.
수집기 로그, 시스템 로그, Monitoring의 데이터 액세스 감사 로그를 검토할 수도 있습니다. 예를 들어 시계열에 쓰기가 실패하면 실패 이유가 포함된 데이터 액세스 감사 로그가 생성됩니다.
시계열 쓰기에 관한 오류 메시지
시계열에 데이터를 쓰려는 시도가 실패하면 시스템에서 오류 메시지를 생성합니다. 이러한 메시지를 사용하여 쓰기가 실패한 이유와 문제를 해결하는 방법을 파악할 수 있습니다.
값 불일치를 나타내는 오류 메시지:
"One or more TimeSeries could not be written: Value type DOUBLE does not match metric descriptor value type INT64."Telemetry API는 모든 측정항목의 값 유형을
DOUBLE로 설정하므로 이전에INT64target_info측정항목을 전송한 경우 이 오류가 발생합니다. 가장 좋은 장기적 해결책은INT64target_info측정항목의 측정항목 설명자를 삭제하는 것입니다. 측정항목 범위에서 이 설명자를 삭제하려면 이 Golang 스크립트를 사용하세요.시계열 데이터를 쓰는 여러 소스를 나타내는 오류 메시지:
"One or more TimeSeries could not be written: Points must be written in order. One or more of the points specified had an older end time than the most recent point."이 문제를 해결하려면 수집기의 구성에서
googlemanagedprometheus내보내기 도구를 삭제합니다. 자세한 내용은 공급업체별 내보내기 도구 삭제를 참조하세요.
다음 단계
수집기 기반 계측 샘플 개요 는 다운로드하여 설치할 수 있는 샘플 애플리케이션을 참조합니다. 각 샘플 애플리케이션에는 Telemetry API를 사용하여 측정항목 및 trace 데이터를 내보내는 완전한 수집기가 포함되어 있습니다.
Google Kubernetes Engine에 Google 기반의 OpenTelemetry Collector 배포에는 완전한 수집기 구성이 포함되어 있습니다.