운영 에이전트 및 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를 사용하여 측정항목을 가져온 것처럼 샘플 기반 가격 책정이 적용됩니다.
- 현재 가격 책정은 Cloud Monitoring 가격 책정 요약을 참조하세요.
- 샘플 수 계산과 비용 예측에 대한 자세한 내용은 수집된 샘플 기반의 가격 책정 예시를 참조하세요.
Monitoring API: Monitoring API를 사용하여 애플리케이션의 측정항목을 수집할 때는 데이터에 운영 에이전트와의 다른 통합의 데이터와 같은 볼륨 기반 가격 책정이 적용됩니다.
- 현재 가격 책정은 Cloud Monitoring 가격 책정 요약을 참조하세요.
- 수집량 및 예상 비용에 대한 자세한 내용은 수집된 바이트를 기반으로 한 가격 책정 예시를 참조하세요.

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

측정항목 구조

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: my-project와 같이 운영 에이전트가 실행 중인 Google Cloud 프로젝트의 식별자
- cluster: 운영 에이전트가 측정항목을 수집할 때 값은 항상 __gce__

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

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

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

다음 예시는 OpenTelemetry 측정항목 쌍의 측정항목 설명을 보여줍니다. 측정항목은 Go OpenTelemetry 측정항목 라이브러리를 사용하는 애플리케이션에서 생성됩니다. Prometheus API 탭에는 OTLP 수신자가 기본 Prometheus 측정항목 모드를 사용할 때 생성된 측정항목 설명이 표시됩니다. Monitoring API 탭에는 OTLP 수신자가 googlecloudmonitoring 측정항목 모드를 사용할 때 생성된 측정항목 설명이 표시됩니다.

측정항목을 만드는 애플리케이션에는 변경사항이 없습니다. 유일한 변경사항은 OTLP 수신자에 사용되는 측정항목 모드입니다.

애플리케이션은 64비트 부동 소수점 값을 기록하는 OTLP 게이지 측정항목 otlp.test.gauge를 만듭니다. 다음 탭에는 각 수집 API가 만드는 측정항목 설명이 표시됩니다.

Prometheus API

{
  "name": "projects/PROJECT_ID/metricDescriptors/prometheus.googleapis.com/otlp_test_gauge/gauge",
  "labels": [
    {
      "key": "instance_name"
    },
    {
      "key": "machine_type"
    }
  ],
  "metricKind": "GAUGE",
  "valueType": "DOUBLE",
  "type": "prometheus.googleapis.com/otlp_test_gauge/gauge",
  "monitoredResourceTypes": [
    "prometheus_target"
  ]
}

Monitoring API

{
  "name": "projects/PROJECT_ID/metricDescriptors/workload.googleapis.com/otlp.test.gauge",
  "labels": [
    {
      "key": "instrumentation_source"
    }
  ],
  "metricKind": "GAUGE",
  "valueType": "DOUBLE",
  "type": "workload.googleapis.com/otlp.test.gauge",
  "monitoredResourceTypes": [
    "gce_instance",
    ...many other types deleted...
  ]
}

애플리케이션은 증가하는 64비트 부동 소수점 값을 기록하는 OTLP 카운터 측정항목 otlp.test.cumulative를 만듭니다. 다음 탭에는 각 수집 API가 만드는 측정항목 설명이 표시됩니다.

Prometheus API

{
  "name": "projects/PROJECT_ID/metricDescriptors/prometheus.googleapis.com/otlp_test_cumulative/counter",
  "labels": [
    {
      "key": "instance_name"
    },
    {
      "key": "machine_type"
    }
  ],
  "metricKind": "CUMULATIVE",
  "valueType": "DOUBLE",
  "type": "prometheus.googleapis.com/otlp_test_cumulative/counter",
  "monitoredResourceTypes": [
    "prometheus_target"
  ]
}

Monitoring API

{
  "name": "projects/PROJECT_ID/metricDescriptors/workload.googleapis.com/otlp.test.cumulative",
  "labels": [
    {
      "key": "instrumentation_source"
    }
  ],
  "metricKind": "CUMULATIVE",
  "valueType": "DOUBLE",
  "type": "workload.googleapis.com/otlp.test.cumulative",
  "monitoredResourceTypes": [
    "gce_instance",
    ...many other types deleted...
  ]
}

다음 표에는 OTLP 측정항목을 수집하는 데 사용되는 API에서 적용하는 일부 형식의 차이점이 요약되어 있습니다.

	Prometheus API	Monitoring API
측정항목 도메인	`prometheus.googleapis.com`	`workload.googleapis.com`
OTLP 측정항목 이름	수집 중에 수정됨	제공된 대로 사용됨
모니터링 리소스	`prometheus_target`	`gce_instance`

수집 형식 및 쿼리

OTLP 수신자에 사용되는 측정항목 모드는 차트, 대시보드, 알림 정책을 빌드할 때 Cloud Monitoring에서 결과 측정항목을 쿼리하는 방법에 영향을 줍니다.

Cloud Monitoring에서 차트, 대시보드 또는 알림 정책을 구성할 때 구성에는 차트, 대시보드 또는 알림 정책이 작동하는 데이터에 대한 쿼리가 포함됩니다.

Cloud Monitoring은 측정항목 데이터를 쿼리하기 위해 다음 도구를 지원합니다.

측정항목 탐색기 같은 도구에 빌드된 쿼리 빌더 기반 인터페이스, 대시보드 빌더 인터페이스, 알림 정책 구성 인터페이스
모니터링 쿼리 언어(MQL): Cloud Monitoring과 관련된 텍스트 기반 쿼리 언어
Prometheus 쿼리 언어(PromQL): 오픈소스 Prometheus에서 사용되는 텍스트 기반 쿼리 언어

이러한 도구를 사용하여 OTLP 측정항목을 쿼리하는 방법은 다음 항목을 참조하세요.

Prometheus API를 사용하여 수집된 OTLP 측정항목 쿼리
Monitoring API를 사용하여 수집된 OTLP 측정항목 쿼리

Prometheus API를 사용하여 수집된 OTLP 측정항목 쿼리

이 섹션에서는 OTLP 수신자의 기본 측정항목 모드인 Prometheus API를 사용하여 수집된 OTLP 측정항목을 쿼리하는 방법을 설명합니다.

쿼리는 측정항목 구조에 설명된 OTLP 측정항목을 기반으로 합니다.

otlp.test.gauge: 64비트 부동 소수점 값을 기록하는 OTLP 게이지 측정항목
otlp.test.cumlative: 64비트 부동 소수점 값을 기록하는 OTLP 카운터 측정항목

이러한 측정항목은 이름으로 작동하는 다음 측정항목 유형을 사용하여 Cloud Monitoring에 수집됩니다.

prometheus.googleapis.com/otlp_test_gauge/gauge
prometheus.googleapis.com/otlp_test_cumulative/counter

Prometheus API를 사용하여 수집된 측정항목은 모니터링 리소스 유형 prometheus_target에 기록됩니다.

Google Cloud 콘솔을 사용하여 측정항목을 쿼리할 때 기본 쿼리가 어떻게 표시되는지 보여주는 탭입니다. 이 예시에서는 측정항목 탐색기를 사용하지만 대시보드 및 알림 정책의 원칙은 동일합니다.

쿼리 빌더 인터페이스

쿼리 빌더 인터페이스를 사용하여 측정항목 데이터를 쿼리하려면 검색이 사용 설정된 필드를 입력하여 측정항목 유형과 모니터링 리소스 유형을 지정합니다. 리소스 유형 수가 측정항목 유형보다 훨씬 적기 때문에 일반적으로 리소스 유형을 검색한 후 연결된 측정항목 메뉴를 사용하여 측정항목 유형을 찾는 것이 가장 효율적입니다.

검색창에 'prometheus'를 입력하면 결과에는 표시 이름 'Prometheus 대상'으로 표시된 prometheus_target 모니터링 리소스와 리소스에 기록되는 측정항목 집합이 포함됩니다. 측정항목은 이름으로 분류되며, 두 측정항목 예시는 Otlp 카테고리로 표시됩니다. Prometheus/otlp_test_cumulative/counter 또는 Prometheus/otlp_test_gauge/gauge를 선택할 수 있습니다.

쿼리 빌더 사용에 대한 자세한 내용은 메뉴를 사용하여 쿼리 빌드를 참조하세요.

다음 스크린샷은 prometheus.googleapis.com/otlp_test_gauge/gauge 측정항목을 쿼리한 결과를 보여줍니다.

Prometheus API를 사용하여 수집된 OTLP 게이지 측정항목의 빌더 기반 측정항목 탐색기 차트

다음 스크린샷은 prometheus.googleapis.com/otlp_test_cumulative/counter 측정항목을 쿼리한 결과를 보여줍니다.

Prometheus API를 사용하여 수집된 OTLP 카운터 측정항목의 빌더 기반 측정항목 탐색기 차트

MQL

MQL을 사용하여 측정항목 데이터를 쿼리하려면 fetch 문을 사용하고 측정항목 유형과 모니터링 리소스 유형을 지정하세요. 둘 사이에는 ::을 사용합니다. 예시 측정항목에 대한 간단한 MQL 쿼리는 다음과 같습니다.

fetch prometheus.googleapis.com/otlp_test_gauge/gauge::prometheus_target
fetch prometheus.googleapis.com/otlp_test_cumulative/counter::prometheus_target

MQL 쿼리 만들기에 대한 자세한 내용은 샘플 MQL 쿼리를 참조하세요.

다음 스크린샷은 prometheus.googleapis.com/otlp_test_gauge/gauge 측정항목을 쿼리한 결과를 보여줍니다.

Prometheus API를 사용하여 수집된 OTLP 게이지 측정항목의 MQL 측정항목 탐색기 차트

다음 스크린샷은 prometheus.googleapis.com/otlp_test_cumulative/counter 측정항목을 쿼리한 결과를 보여줍니다.

Prometheus API를 사용하여 수집된 OTLP 카운터 측정항목의 MQL 측정항목 탐색기 차트

PromQL

PromQL을 사용할 때 Prometheus API로 수집된 측정항목 데이터를 쿼리하는 경우 원래 OTLP 측정항목 이름의 수정된 형식만 지정하면 됩니다. 프리픽스가 붙은 prometheus.googleapis.com/ 문자열이나 서픽스 유형을 지정할 필요가 없습니다.

모니터링 리소스 유형 하나에 대해서만 측정항목을 쓸 수 있는 경우 리소스를 지정할 필요가 없습니다. 측정항목 구조에 설명된 대로 Prometheus API를 사용하여 수집된 OTLP 측정항목은 prometheus_target 모니터링 리소스 유형에만 기록됩니다. 예시 측정항목에 대한 간단한 PromQL 쿼리는 다음과 같습니다.

otlp_test_gauge
otlp_test_cumulative

Prometheus API를 통해 수집된 측정항목을 Cloud Monitoring에서 PromQL을 사용하여 쿼리하는 방법에 대한 자세한 내용은 Cloud Monitoring의 Google Cloud Managed Service for Prometheus 데이터를 참조하세요. PromQL 언어에 대한 자세한 내용은 Prometheus 쿼리를 참조하세요.

다음 스크린샷은 prometheus.googleapis.com/otlp_test_gauge/gauge 측정항목을 쿼리한 결과를 보여줍니다.

Prometheus API를 사용하여 수집된 OTLP 게이지 측정항목의 PromQL 측정항목 탐색기 차트

다음 스크린샷은 prometheus.googleapis.com/otlp_test_cumulative/counter 측정항목을 쿼리한 결과를 보여줍니다.

Prometheus API를 사용하여 수집된 OTLP 카운터 측정항목의 PromQL 측정항목 탐색기 차트

Monitoring API를 사용하여 수집된 OTLP 측정항목 쿼리

이 섹션에서는 Monitoring API를 사용하여 수집된 OTLP 측정항목을 쿼리하는 방법을 보여줍니다. OTLP 수신자의 metrics_mode 필드를 googlecloudmonitoring 값으로 설정하여 Cloud Monitoring API를 선택합니다.

쿼리는 측정항목 구조에 설명된 OTLP 측정항목을 기반으로 합니다.

otlp.test.gauge: 64비트 부동 소수점 값을 기록하는 OTLP 게이지 측정항목
otlp.test.cumlative: 64비트 부동 소수점 값을 기록하는 OTLP 카운터 측정항목

이러한 측정항목은 이름으로 작동하는 다음 측정항목 유형을 사용하여 Cloud Monitoring에 수집됩니다.

workload.googleapis.com/otlp.test.gauge
workload.googleapis.com/otlp.test.cumulative

Monitoring API를 사용하여 수집된 측정항목은 모니터링 리소스 유형 gce_instance에 기록됩니다.

쿼리 빌더 인터페이스

검색창에 'gce_instance'를 입력하면 결과에 표시 이름 'VM 인스턴스'와 리소스에 기록되는 측정항목 집합이 리소스 유형에 표시됩니다. 측정항목은 이름으로 분류되며, 두 측정항목 예시는 Otlp 카테고리로 표시됩니다. Workload/otlp_test_cumulative 또는 Workload/otlp_test_gauge 중에서 선택할 수 있습니다.

쿼리 빌더 사용에 대한 자세한 내용은 메뉴를 사용하여 쿼리 빌드를 참조하세요.

다음 스크린샷은 workload.googleapis.com/otlp.test.gauge 측정항목을 쿼리한 결과를 보여줍니다.

Monitoring API를 사용하여 수집된 OTLP 게이지 측정항목의 빌더 기반 측정항목 탐색기 차트

다음 스크린샷은 workload.googleapis.com/otlp.test.cumulative 측정항목을 쿼리한 결과를 보여줍니다.

Monitoring API를 사용하여 수집된 OTLP 카운터 측정항목의 빌더 기반 측정항목 탐색기 차트

MQL

fetch workload.googleapis.com/otlp.test.gauge::gce_instance
fetch workload.googleapis.com/otlp.test.cumulative::gce_instance

MQL 쿼리 만들기에 대한 자세한 내용은 샘플 MQL 쿼리를 참조하세요.

다음 스크린샷은 workload.googleapis.com/otlp.test.gauge 측정항목을 쿼리한 결과를 보여줍니다.

Monitoring API를 사용하여 수집된 OTLP 게이지 측정항목의 MQL 측정항목 탐색기 차트

다음 스크린샷은 workload.googleapis.com/otlp.test.cumulative 측정항목을 쿼리한 결과를 보여줍니다.

Monitoring API를 사용하여 수집된 OTLP 카운터 측정항목의 MQL 측정항목 탐색기 차트

PromQL

PromQL을 사용하여 Monitoring API로 수집된 측정항목 데이터를 쿼리하는 경우 측정항목 이름을 PromQL 규칙에 매핑해야 합니다. 기본 매핑 규칙에는 다음이 포함됩니다.

첫 번째 /를 :으로 바꿉니다.
다른 모든 특수 문자(. 및 기타 / 문자 포함)를 _로 바꿉니다.

매핑 규칙에 대한 자세한 내용은 Cloud Monitoring 측정항목을 PromQL에 매핑을 참조하세요.

예시 측정항목의 Monitoring 측정항목 유형은 다음과 같이 PromQL에 매핑됩니다.

workload_googleapis_com:otlp_test_gauge
workload_googleapis_com:otlp_test_cumulative

모니터링 리소스 유형 하나에 대해서만 측정항목을 쓸 수 있는 경우 리소스를 지정할 필요가 없습니다. 측정항목 예시는 gce_instance 모니터링 리소스 유형에 대해 작성되지만 측정항목 구조에 설명된 대로 gce_instance는 가능한 측정항목 유형 중 하나일 뿐입니다. 따라서 이러한 측정항목의 PromQL 쿼리에는 gce_instance 리소스 유형에 대한 필터가 포함되어야 합니다. 필터를 포함하려면 매핑된 측정항목 이름의 끝에 {monitored_resource="gce_instance"} 문자열을 추가하세요.

Cloud Monitoring에서 PromQL을 사용하는 방법에 대한 자세한 내용은 Cloud Monitoring의 PromQL을 참조하세요. PromQL 언어에 대한 자세한 내용은 Prometheus 쿼리를 참조하세요.

예시 측정항목에 대한 간단한 PromQL 쿼리는 다음과 같습니다.

workload_googleapis_com:otlp_test_gauge{monitored_resource="gce_instance"}
workload_googleapis_com:otlp_test_cumulative{monitored_resource="gce_instance"}

다음 스크린샷은 workload.googleapis.com/otlp.test.gauge 측정항목을 쿼리한 결과를 보여줍니다.

Monitoring API를 사용하여 수집된 OTLP 게이지 측정항목의 PromQL 측정항목 탐색기 차트

다음 스크린샷은 workload.googleapis.com/otlp.test.cumulative 측정항목을 쿼리한 결과를 보여줍니다.

Monitoring API를 사용하여 수집된 OTLP 카운터 측정항목의 PromQL 측정항목 탐색기 차트

Cloud Monitoring에서 측정항목 사용 및 진단 보기

Cloud Monitoring 측정항목 관리 페이지에서는 관측 가능성에 영향을 주지 않고 청구 가능 측정항목에 지출하는 금액을 제어하는 데 도움이 되는 정보를 제공합니다. 측정항목 관리 페이지에서는 다음 정보를 보고합니다.

측정항목 도메인 및 개별 측정항목의 바이트 기반 및 샘플 기반 청구에 대한 수집량
측정항목의 라벨 및 카디널리티에 대한 데이터
알림 정책 및 커스텀 대시보드의 측정항목 사용
측정항목 쓰기 오류의 비율

측정항목 관리 페이지를 보려면 다음을 수행합니다.

Google Cloud 콘솔에서 측정항목 관리 페이지로 이동합니다.
측정항목 관리로 이동

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Monitoring인 결과를 선택합니다.
툴바에서 기간을 선택합니다. 기본적으로 측정항목 관리 페이지에는 이전 1일 동안 수집된 측정항목에 대한 정보가 표시됩니다.

측정항목 관리 페이지에 대한 자세한 내용은 측정항목 사용량 보기 및 관리를 참조하세요.

OTLP trace 수집

운영 에이전트가 trace를 수집하도록 구성했지만 Cloud Trace에서 애플리케이션을 실행할 때 trace가 없으면 에이전트가 사용하는 Compute Engine 서비스 계정에 추가 역할을 부여해야 할 수 있습니다. 기본적으로 서비스 계정은 측정항목 및 로그를 작성하는 데 필요한 역할을 가져오지만 trace는 가져오지 않습니다.

다음 섹션에서는 서비스 계정에 필요한 Cloud Trace 승인을 부여하는 방법을 설명합니다.

서비스 계정에 부여된 역할 확인

서비스 계정에 부여된 역할을 보려면 다음 gcloud projects get-iam-policy 명령어를 실행합니다.

gcloud projects get-iam-policy PROJECT_ID --format="table(bindings.role)" --flatten="bindings[].members" --filter="bindings.members:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com"

다음과 같은 출력이 표시되어야 합니다.

ROLE
roles/logging.logWriter
roles/monitoring.metricWriter

출력에 roles/cloudtrace.agent 또는 roles/cloudtrace.admin이 포함된 경우 서비스 계정에 trace를 작성할 수 있는 충분한 권한이 있다는 의미입니다. 이러한 역할 중 하나를 서비스 계정에 부여하려면 다음 섹션을 참조하세요.

서비스 계정에 Cloud Trace 역할 부여

서비스 계정의 경우 일반적으로 Cloud Trace 에이전트 역할 roles/cloudtrace.agent가 적합합니다. 서비스 계정에 이 역할을 부여하려면 다음 gcloud projects add-iam-policy-binding 명령어를 실행하세요.

gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role="roles/cloudtrace.agent"

그 다음 gcloud projects get-iam-policy 명령어를 실행하여 변경사항이 적용되었는지 확인할 수 있습니다.

gcloud projects get-iam-policy PROJECT_ID --format="table(bindings.role)" --flatten="bindings[].members" --filter="bindings.members:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com"

이제 출력에 roles/cloudtrace.agent가 포함됩니다.

ROLE
roles/cloudtrace.agent
roles/logging.logWriter
roles/monitoring.metricWriter

IAM 역할 관리에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

운영 에이전트에서 Cloud Trace에 데이터를 쓰도록 사용하는 서비스 계정을 승인한 후 OpenTelemetry 기반 애플리케이션을 실행하면 trace가 Cloud Trace에 표시됩니다.

trace 세부정보 창에 표시된 OTLP trace

OTLP 수신자 사용 중지

운영 에이전트를 사용하여 OTLP 측정항목과 trace를 모두 수집하는 경우, 측정항목 또는 trace 중 하나만 수집을 사용 중지하려면 다음 안내를 따르세요.

사용자 구성 파일 config.yaml 중 하나를 변경하여 측정항목 또는 trace 수집을 중지합니다.
- metrics 서비스에서 otlp 파이프라인을 삭제합니다.
- traces 서비스에서 otlp 파이프라인을 삭제합니다.
운영 에이전트를 다시 시작합니다.

운영 에이전트의 OTLP 측정항목 및 trace 수집을 중지하려면 다음을 수행합니다.

사용자 구성 파일에서 OTLP 구성을 삭제합니다.
- otlp 수신자를 포함하는 전체 combined 섹션을 삭제합니다.
- metrics 서비스에서 otlp 파이프라인을 삭제합니다.
- 전체 traces 서비스를 삭제합니다.
운영 에이전트를 다시 시작합니다.

다음 단계

애플리케이션 측정항목 및 trace가 수집되면 Google Cloud 콘솔을 사용하여 데이터를 모니터링하고 분석할 수 있습니다.

대시보드 정보 및 만들 수 있는 차트 유형에 대한 자세한 내용은 대시보드 및 차트를 참조하세요.
알림 정책에 대한 자세한 내용은 알림 정책 사용을 참조하세요.
trace 데이터 분석에 관한 자세한 내용은 trace 찾기 및 탐색을 참조하세요.

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

OTLP 수신자 사용 개요

이점

제한사항

기본 요건

운영 에이전트 구성

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

combined 수신자 섹션 추가

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

운영 에이전트 다시 시작

Linux

Windows

OTLP 측정항목 수집

OTLP 측정항목의 수집 형식

가격 책정 및 할당량

측정항목 구조

Prometheus API

Monitoring API

Prometheus API

Monitoring API

수집 형식 및 쿼리

Prometheus API를 사용하여 수집된 OTLP 측정항목 쿼리

쿼리 빌더 인터페이스

MQL

PromQL

Monitoring API를 사용하여 수집된 OTLP 측정항목 쿼리

쿼리 빌더 인터페이스

MQL

PromQL

Cloud Monitoring에서 측정항목 사용 및 진단 보기

OTLP trace 수집

서비스 계정에 부여된 역할 확인

서비스 계정에 Cloud Trace 역할 부여

OTLP 수신자 사용 중지

다음 단계

`combined` 수신자 섹션 추가