운영 에이전트 및 OTLP(OpenTelemetry Protocol) 사용

이 문서에서는 OpenTelemetry를 사용하고 Compute Engine에서 실행하여 계측되는 애플리케이션에서 운영 에이전트와 OpenTelemetry Protocol(OTLP) 수신자를 사용하여 사용자 정의 측정항목과 trace를 수집하는 방법을 설명합니다.

이 문서는 다음과 같이 구성됩니다.

개요: OTLP 수신자의 사용 사례 설명
기본 요건: OTLP 수신자를 사용하기 위한 요건
OTLP 수신자를 사용하도록 에이전트 구성
수신자를 사용하여 측정항목 수집. 이 섹션에서는 Cloud Monitoring에서 OpenTelemetry 측정항목을 쿼리하는 방법을 설명합니다.
수신자를 사용하여 trace 수집. 이 섹션에서는 Cloud Trace에 데이터를 작성하도록 서비스 계정을 승인하는 방법을 설명합니다.

OTLP 수신자 사용 개요

운영 에이전트 OTLP 수신자를 사용하면 다음을 수행할 수 있습니다.

OpenTelemetry에 언어별 SDK 중 하나를 사용하여 애플리케이션을 계측합니다. 지원되는 언어에 대한 자세한 내용은 OpenTelemetry 계측을 참고하세요. OpenTelemetry SDK와 운영 에이전트를 함께 사용하면 다음 작업이 자동으로 수행됩니다.
- 애플리케이션에서 OTLP 측정항목을 수집하고 분석을 위해 해당 측정항목을 Cloud Monitoring으로 전송합니다.
- 애플리케이션에서 trace 데이터인 OTLP 스팬을 수집한 후 분석을 위해 해당 스팬을 Cloud Trace로 전송합니다.
OTLP에 대한 지원을 기본 제공하는 타사 애플리케이션 또는 이러한 지원 기능이 있는 플러그인(Nginx와 같은 애플리케이션)에서 trace를 수집합니다. 운영 에이전트의 OTLP 수신자는 이러한 trace를 수집할 수 있습니다. 예시를 보려면 OpenTelemetry nginx 모듈을 참고하세요.
OpenTelemetry 커스텀 계측을 사용합니다.
OpenTelemetry 자동 계측을 사용합니다.

수신자를 사용하여 측정항목, trace 또는 둘 다 수집할 수 있습니다. 운영 에이전트가 측정항목을 수집하면 차트, 대시보드, 알림 정책을 포함한 Cloud Monitoring의 기능을 사용하여 측정항목을 모니터링할 수 있습니다. 애플리케이션이 trace 데이터도 전송하는 경우 Cloud Trace를 사용하여 해당 데이터를 분석할 수 있습니다.

이점

운영 에이전트용 OTLP 플러그인을 사용하기 전에 애플리케이션에서 사용자 정의 측정항목과 trace를 수집하도록 계측하는 기본 방법은 다음과 같습니다.

Monitoring API 또는 Trace API를 구현하는 클라이언트 라이브러리 사용
이전 OpenCensus 라이브러리 사용

OTLP 수신자로 OpenTelemetry를 사용하면 다음을 포함한 여러 가지 이점이 있습니다.

OpenTelemetry가 OpenCensus를 대체합니다. OpenCensus 프로젝트가 보관처리됩니다. 자세한 내용은 OpenTelemetry란?을 참고하세요.
수집이 에이전트 수준에서 제어되므로 에이전트 구성이 변경되면 애플리케이션을 다시 배포할 필요가 없습니다.
애플리케이션에서 Google Cloud 사용자 인증 정보를 설정할 필요가 없습니다. 모든 승인은 에이전트 수준에서 처리됩니다.
애플리케이션 코드에 Google Cloud관련 모니터링 또는 추적 코드가 포함되지 않습니다. Monitoring API 또는 Trace API를 직접 사용할 필요가 없습니다.
애플리케이션이 운영 에이전트에 데이터를 푸시하고 애플리케이션이 비정상 종료되더라도 운영 에이전트가 수집한 데이터는 손실되지 않습니다.

제한사항

운영 에이전트 수신자가 노출한 OTLP 리스너는 gRPC 전송을 지원합니다. 주로 JavaScript 클라이언트에 사용되는 HTTP는 지원되지 않습니다. OpenTelemetry 프로토콜에 대한 자세한 내용은 프로토콜 세부정보를 참고하세요.

OTLP 수신자는 로그를 수집하지 않습니다. 운영 에이전트 및 기타 수신자를 사용하여 로그를 수집할 수 있으며 로그 정보를 OTLP 스팬에 포함할 수 있지만 OTLP 수신자는 로그의 직접 수집을 지원하지 않습니다. 운영 에이전트를 사용하여 로그를 수집하는 방법에 대한 자세한 내용은 Logging 구성을 참고하세요.

기본 요건

OTLP 수신자 및 운영 에이전트를 사용하여 OTLP 측정항목 및 trace를 수집하려면 운영 에이전트 버전 2.37.0 이상을 설치해야 합니다.

이 문서에서는 OpenTelemetry SDK 중 하나를 사용하여 작성된 OpenTelemetry 기반 애플리케이션이 이미 있다고 가정합니다. 이 문서에서는 OpenTelemetry SDK 사용에 대해서는 다루지 않습니다. SDK 및 지원되는 언어에 대한 자세한 내용은 OpenTelemetry 계측을 참고하세요.

운영 에이전트 구성

OTLP 수신자를 사용하도록 운영 에이전트를 구성하려면 다음 안내를 따르세요.

OTLP 수신자를 포함하도록 운영 에이전트의 사용자 구성 파일을 수정합니다.
운영 에이전트를 다시 시작합니다.

다음 섹션에서는 각 단계를 설명합니다.

운영 에이전트 사용자 구성 파일 수정

OTLP 수신자의 구성 요소를 운영 에이전트의 사용자 구성 파일에 추가합니다.

Linux: /etc/google-cloud-ops-agent/config.yaml
Windows: C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml

에이전트 구성에 대한 일반적인 내용은 구성 모델을 참고하세요.

OTLP 수신자는 운영 에이전트에 대해 combined 구성 섹션을 도입합니다. 수신자를 사용하려면 측정항목 및 trace를 둘 다 사용하지 않는 경우에도 해당 서비스를 구성해야 합니다.

다음 섹션에서는 OTLP 수신자의 구성 단계를 설명합니다.

`combined` 수신자 섹션 추가

OTLP 측정항목 및 trace의 수신자를 combined 섹션에 배치합니다. combined 섹션에서는 프로세서 또는 서비스가 허용되지 않습니다. combined 섹션에 수신자와 이름이 같은 다른 수신자를 구성하면 안 됩니다. 다음 예시에서는 otlp를 수신자 이름으로 사용합니다.

OTLP의 최소 combined 구성은 다음과 같습니다.

combined:
  receivers:
    otlp:
      type: otlp

otlp 수신자에는 다음과 같은 구성 옵션이 있습니다.

type: (필수사항) otlp여야 합니다.
grpc_endpoint: (선택사항) OTLP 수신자가 리슨하는 gRPC 엔드포인트입니다. 기본값은 0.0.0.0:4317입니다.
metrics_mode: (선택사항) 기본값은 googlemanagedprometheus입니다. 즉, 수신자는 Managed Service for Prometheus에서도 사용하는 Prometheus API를 사용하여 OTLP 측정항목을 Prometheus 형식의 측정항목으로 보냅니다.

대신 Monitoring API를 사용하여 측정항목을 Cloud Monitoring 커스텀 측정항목으로 전송하려면 metrics_mode 옵션을 googlecloudmonitoring 값으로 설정하세요.

이 선택사항은 측정항목을 수집하는 방법과 청구를 위한 측정 방식에 영향을 미칩니다. 측정항목 형식에 대한 자세한 내용은 OTLP 측정항목 수집 형식을 참고하세요.

서비스에 OTLP 파이프라인 추가

OTLP 수신자는 측정항목과 trace를 수집할 수 있으므로 측정항목과 trace에 서비스를 정의해야 합니다. 측정항목 또는 trace를 수집하지 않으려면 빈 서비스를 만들면 됩니다. 다른 파이프라인이 이미 있는 경우 해당 파이프라인에 OTLP 파이프라인을 추가할 수 있습니다.

다음은 OTLP 수신자를 파이프라인에 포함한 metrics 및 traces 서비스입니다.

combined:
  receivers:
    otlp:
      type: otlp
metrics:
  service:
    pipelines:
      otlp:
        receivers: [otlp]
traces:
  service:
    pipelines:
      otlp:
        receivers: [otlp]

OTLP 컬렉션에 metrics 또는 traces 서비스를 사용하지 않으려면 OTLP 수신자를 서비스의 파이프라인 밖에 둡니다. 파이프라인이 없더라도 서비스는 존재해야 합니다. 애플리케이션이 지정된 유형의 데이터를 전송하고 수신자를 포함하는 해당 파이프라인이 없으면 운영 에이전트는 데이터를 삭제합니다.

운영 에이전트 다시 시작

구성 변경사항을 적용하려면 운영 에이전트를 다시 시작해야 합니다.

Linux

에이전트를 다시 시작하려면 인스턴스에서 다음 명령어를 실행합니다.
```
sudo systemctl restart google-cloud-ops-agent
```
에이전트가 다시 시작되었는지 확인하려면 다음 명령어를 실행하고 '측정항목 에이전트' 및 'Logging 에이전트' 구성요소가 시작되었는지 확인합니다.
```
sudo systemctl status "google-cloud-ops-agent*"
```

Windows

RDP 또는 유사한 도구를 사용하여 인스턴스에 연결하고 Windows에 로그인합니다.
PowerShell 아이콘을 마우스 오른쪽 버튼으로 클릭하고 관리자 권한으로 실행을 선택하여 관리자 권한이 있는 PowerShell 터미널을 엽니다.
에이전트를 다시 시작하려면 다음 PowerShell 명령어를 실행합니다.
```
Restart-Service google-cloud-ops-agent -Force
```
에이전트가 다시 시작되었는지 확인하려면 다음 명령어를 실행하고 '측정항목 에이전트' 및 'Logging 에이전트' 구성요소가 시작되었는지 확인합니다.
```
Get-Service google-cloud-ops-agent*
```

OTLP 측정항목 수집

OTLP 수신자를 사용하여 OpenTelemetry 애플리케이션에서 측정항목을 수집할 때 수신자의 가장 먼저 선택해야 하는 구성 항목은 측정항목을 수집하는 데 사용할 API입니다.

otlp 수신자 구성에서 metrics_mode 옵션을 변경하거나 기본값을 사용하여 선택하면 됩니다. 선택에 따라 OTLP 측정항목이 Cloud Monitoring에 수집되는 방법과 데이터가 청구 목적으로 측정되는 방식에 영향을 줍니다.

metrics_mode 선택은 Monitoring에서 차트, 대시보드, 알림 정책을 만드는 기능에는 영향을 미치지 않습니다.

차트 및 대시보드 만들기에 대한 자세한 내용은 대시보드 및 차트 개요를 참고하세요.
알림 정책에 대한 자세한 내용은 알림 개요를 참고하세요.

다음 섹션에서는 측정항목 모드에서 사용하는 형식의 차이와 Monitoring에서 사용할 수집된 데이터를 쿼리하는 방법을 설명합니다.

OTLP 측정항목의 수집 형식

OTLP 수신자는 측정항목 데이터를 수집하는 데 사용되는 API를 지정하는 metrics_mode 옵션을 제공합니다. 기본적으로 수신자는 Prometheus API를 사용하며, metrics_mode 옵션의 기본값은 googlemanagedprometheus입니다. 측정항목은 Managed Service for Prometheus에서 사용하는 것과 동일한 API를 사용하여 수집됩니다.

대신 Cloud Monitoring API로 측정항목 데이터를 전송하도록 수신자를 구성할 수 있습니다. Monitoring API로 데이터를 전송하려면 다음 예시와 같이 metrics_mode 옵션 값을 googlecloudmonitoring으로 설정하세요.

combined:
  receivers:
    otlp:
      type: otlp
      metrics_mode: googlecloudmonitoring

사용하는 수집 형식에 따라 OTLP 측정항목의 Cloud Monitoring 매핑 방식이 결정됩니다. Monitoring에서 측정항목 형식의 측정항목에 대한 차트, 대시보드, 알림 정책을 만들 수 있지만 쿼리에서 측정항목을 다르게 참조할 수 있습니다.

수집 형식은 또한 데이터 수집에 사용되는 가격 책정 모델을 결정합니다.

다음 섹션에서는 가격 책정, Prometheus API에서 수집한 측정항목과 Monitoring API에서 수집한 동일한 측정항목 간의 구조적 차이, 쿼리의 측정항목을 참조하는 방법을 설명합니다.

가격 책정 및 할당량

사용하는 수집 형식에 따라 OTLP 측정항목의 요금이 청구되는 방식이 결정됩니다.

Prometheus API: Prometheus API를 사용하여 애플리케이션의 측정항목을 수집할 때는 Managed Service for Prometheus를 사용하여 측정항목을 가져온 것처럼 샘플 기반 가격 책정이 적용됩니다.
Monitoring API: Monitoring API를 사용하여 애플리케이션의 측정항목을 수집할 때는 데이터에 운영 에이전트와의 다른 통합의 데이터와 같은 볼륨 기반 가격 책정이 적용됩니다.

OTLP 수신자를 사용하여 수집된 측정항목은 Cloud Monitoring에 수집될 때 '커스텀' 측정항목 유형으로 간주되며 커스텀 측정항목의 할당량 및 한도가 적용됩니다.

현재 가격은 Google Cloud Observability 가격 책정을 참고하세요.

측정항목 구조

Cloud Monitoring은 측정항목 설명이라는 스키마를 사용하여 측정항목 데이터의 형식을 설명합니다. 측정항목 설명에는 측정항목 이름, 측정항목 값의 데이터 유형, 각 값이 이전 값과 관련되는 방식, 값과 연결된 라벨이 포함됩니다. Prometheus API를 사용하여 측정항목을 수집하도록 OTLP 수신자를 구성하는 경우 생성되는 측정항목 설명은 Monitoring API를 사용할 때 생성된 측정항목 설명과 다릅니다.

Prometheus API: Prometheus API를 사용하여 애플리케이션의 측정항목을 수집할 때 각 측정항목은 표준 OpenTelemetry-to-Prometheus 변환을 사용하여 변환되어 Cloud Monitoring 모니터링 리소스 유형에 매핑됩니다.

변환에는 다음 변경사항이 포함됩니다.
- OTLP 측정항목 이름에는 prometheus.googleapis.com/ 문자열이 프리픽스로 추가됩니다.
- OTLP 측정항목 이름에 마침표(.)와 같은 영숫자가 아닌 문자는 밑줄(_)로 바뀝니다.
- OTLP 측정항목 이름은 /gauge 또는 /counter와 같은 측정항목 종류를 나타내는 문자열로 서픽스됩니다.
OTLP 리소스의 값으로 채워진 다음 라벨이 측정항목에 추가됩니다.
- instance_name: host.name 리소스 속성 값
- machine_type: host.type 리소스 속성 값
측정항목 측정으로 기록된 모니터링 리소스는 일반적인 prometheus_target 유형입니다. 생성된 Prometheus 시계열에는 prometheus_target 리소스의 다음 라벨이 포함되며 여기에는 OTLP 리소스의 값으로 채워집니다.
- location: cloud.availability_zone 리소스 속성 값
- namespace: host.id 리소스 속성 값
prometheus_target 리소스 유형에는 다음 라벨도 포함됩니다.
- project_id: 운영 에이전트가 실행 중인 Google Cloud 프로젝트의 식별자(예: my-project)입니다.
- cluster: 운영 에이전트가 측정항목을 수집할 때 값은 항상 __gce__

수신되는 OTLP 데이터에 라벨 값에 사용된 리소스 속성이 없으면 운영 에이전트를 실행하는 VM에 대한 정보에서 값을 가져옵니다. 이러한 동작으로 인해 해당 리소스 속성이 없는 OTLP 데이터는 운영 에이전트 Prometheus 수신자가 수집하는 데이터와 동일한 라벨이 표시됩니다.

Monitoring API: Monitoring API를 사용하여 애플리케이션의 측정항목을 수집할 때 각 측정항목은 다음과 같이 처리됩니다.

OTLP 측정항목 이름에 custom.googleapis.com과 같이 이 문자열 또는 다른 유효한 측정항목 도메인이 이미 포함되어 있지 않는 한 OTLP 측정항목 이름에 workload.googleapis.com/ 문자열이 프리픽스로 추가됩니다. '워크로드' 도메인을 사용하는 것이 좋습니다.
측정항목 측정으로 기록된 모니터링 리소스는 Compute Engine 가상 머신 유형 gce_instance입니다.