OpenTelemetry 사이드카를 사용하여 OTLP 측정항목 작성

이 튜토리얼에서는 OpenTelemetry 사이드카를 사용해서 Google Cloud Managed Service For Prometheus에 커스텀 OTLP 측정항목을 보고하는 Cloud Run 서비스를 작성, 배포, 호출하는 방법을 보여줍니다.

Prometheus 측정항목을 보고하는 Cloud Run 서비스가 있으면 대신 Cloud Run용 Prometheus 사이드카를 사용하세요.

목표

OpenTelemetry 사이드카를 사용해서 Cloud Run에 대해 서비스를 작성, 빌드, 배포합니다.
커스텀 측정항목을 생성하고 이를 Google Cloud Managed Service For Prometheus에 보고합니다.

비용

이 문서에서는 비용이 청구될 수 있는 다음과 같은 Google Cloud 구성요소를 사용합니다.

프로젝트 사용량을 기준으로 예상 비용을 산출하려면 가격 계산기를 사용하세요. Google Cloud를 처음 사용하는 사용자는 무료 체험판을 사용할 수 있습니다.

시작하기 전에

Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

Google Cloud Console의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.

프로젝트 선택기로 이동

Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

Google Cloud Console의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.

프로젝트 선택기로 이동

Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

API Cloud Run, Cloud Monitoring, Artifact Registry, and Cloud Build 사용 설정
API 사용 설정

gcloud CLI를 설치하고 초기화합니다.
Google Cloud CLI를 업데이트합니다. gcloud components update

필요한 역할

튜토리얼을 완료하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

Cloud Build 편집자(roles/cloudbuild.builds.editor)
Cloud Run 관리자(roles/run.admin)
서비스 계정 만들기(roles/iam.serviceAccountCreator)
프로젝트 IAM 관리자(roles/resourcemanager.projectIamAdmin)
모니터링 측정항목 작성자(roles/monitoring.metricWriter)
서비스 계정 사용자(roles/iam.serviceAccountUser)
서비스 사용량 소비자(roles/serviceusage.serviceUsageConsumer)
스토리지 관리자(roles/storage.admin)

역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

Cloud Run 서비스 계정에는 모니터링 측정항목 작성자(roles/monitoring.metricWriter) 역할도 필요합니다. Compute Engine 기본 서비스 계정에는 기본적으로 이 역할이 포함되어 있지만 해당 권한을 변경했거나 다른 서비스 계정을 사용하는 경우 이를 추가해야 할 수 있습니다.

gcloud 기본값 설정

Cloud Run 서비스의 기본값으로 gcloud를 구성하려면 다음 안내를 따르세요.

기본 프로젝트를 설정합니다.
```
gcloud config set project PROJECT_ID
```
PROJECT_ID를 이 튜토리얼용으로 만든 프로젝트 이름으로 바꿉니다.
선택한 리전에 맞게 gcloud를 구성합니다.
```
gcloud config set run/region REGION
```
REGION을 지원되는 Cloud Run 리전 중 원하는 리전으로 바꿉니다.

Cloud Run 위치

Cloud Run은 리전을 기반으로 합니다. 즉, Cloud Run 서비스를 실행하는 인프라가 특정 리전에 위치해 있으며 해당 리전 내의 모든 영역에서 중복으로 사용할 수 있도록 Google이 관리합니다.

Cloud Run 서비스를 실행하는 리전을 선택하는 데 있어 중요한 기준은 지연 시간, 가용성 또는 내구성 요구사항입니다. 일반적으로 사용자와 가장 가까운 리전을 선택할 수 있지만 Cloud Run 서비스에서 사용하는 다른 Google Cloud 제품 위치도 고려해야 합니다. 여러 위치에서 Google Cloud 제품을 함께 사용하면 서비스 지연 시간과 비용에 영향을 미칠 수 있습니다.

Cloud Run은 다음 리전에서 사용할 수 있습니다.

등급 1 가격 적용

asia-east1(타이완)
asia-northeast1(도쿄)
asia-northeast2(오사카)
europe-north1(핀란드) 낮은 CO₂
europe-southwest1(마드리드)
europe-west1(벨기에) 낮은 CO₂
europe-west4(네덜란드)
europe-west8(밀라노)
europe-west9(파리) 낮은 CO₂
me-west1(텔아비브)
us-central1(아이오와) 낮은 CO₂
us-east1(사우스캐롤라이나)
us-east4(북 버지니아)
us-east5(콜럼버스)
us-south1(댈러스)
us-west1(오리건) 낮은 CO₂

등급 2 가격 적용

africa-south1(요하네스버그)
asia-east2(홍콩)
asia-northeast3(대한민국 서울)
asia-southeast1(싱가포르)
asia-southeast2 (자카르타)
asia-south1(인도 뭄바이)
asia-south2(인도 델리)
australia-southeast1(시드니)
australia-southeast2(멜버른)
europe-central2(폴란드 바르샤바)
europe-west10(베를린)
europe-west12(토리노)
europe-west2(영국 런던) 낮은 CO₂
europe-west3(독일 프랑크푸르트) 낮은 CO₂
europe-west6(스위스 취리히) 낮은 CO₂
me-central1(도하)
me-central2(담맘)
northamerica-northeast1(몬트리올) 낮은 CO₂
northamerica-northeast2(토론토) 낮은 CO₂
southamerica-east1(브라질 상파울루) 낮은 CO₂
southamerica-west1(칠레 산티아고) 낮은 CO₂
us-west2(로스앤젤레스)
us-west3(솔트레이크시티)
us-west4(라스베이거스)

Cloud Run 서비스를 이미 만들었다면 Google Cloud 콘솔의 Cloud Run 대시보드에서 리전을 확인할 수 있습니다.

Artifact Registry 이미지 저장소 만들기

샘플 서비스 이미지를 호스팅하기 위해 Artifact Registry Docker 저장소를 만듭니다.

gcloud artifacts repositories create run-otel \
    --repository-format=docker \
    --location=REGION \
    --project=PROJECT_ID

다음을 바꿉니다.

PROJECT_ID를 이 튜토리얼에 만든 프로젝트 이름을 바꿉니다.
REGION REGION을 선택한 지원되는 Cloud Run 리전으로 바꿉니다.

코드 샘플 검색

사용할 코드 샘플을 검색하려면 다음 안내를 따르세요.

샘플 앱 저장소를 로컬 머신에 클론합니다.
Go
```
git clone https://github.com/GoogleCloudPlatform/golang-samples.git
```
또는 zip 파일로 샘플을 다운로드하고 압축을 풀 수 있습니다.
Cloud Run 샘플 코드가 포함된 디렉터리로 변경합니다.
Go
```
cd golang-samples/run/custom-metrics/
```

코드 검토

이 튜토리얼의 코드는 다음과 같이 구성됩니다.

새로 추가되는 요청을 처리하고 sample_sidecar_counter라는 측정항목을 생성하는 서버

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"os"

	"go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc"
	"go.opentelemetry.io/otel/metric"
	sdkmetric "go.opentelemetry.io/otel/sdk/metric"
	"go.opentelemetry.io/otel/sdk/resource"
	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
)

var counter metric.Int64Counter

func main() {
	ctx := context.Background()
	shutdown := setupCounter(ctx)
	defer shutdown(ctx)

	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
		log.Printf("defaulting to port %s", port)
	}

	http.HandleFunc("/", handler)
	log.Fatal(http.ListenAndServe(":"+port, nil))
}

func handler(w http.ResponseWriter, r *http.Request) {
	counter.Add(context.Background(), 100)
	fmt.Fprintln(w, "Incremented sidecar_sample_counter metric!")
}

func setupCounter(ctx context.Context) func(context.Context) error {
	serviceName := os.Getenv("K_SERVICE")
	if serviceName == "" {
		serviceName = "sample-cloud-run-app"
	}
	r, err := resource.Merge(
		resource.Default(),
		resource.NewWithAttributes(
			semconv.SchemaURL,
			semconv.ServiceName(serviceName),
		),
	)
	if err != nil {
		log.Fatalf("Error creating resource: %v", err)
	}

	exporter, err := otlpmetricgrpc.New(ctx,
		otlpmetricgrpc.WithInsecure(),
	)
	if err != nil {
		log.Fatalf("Error creating exporter: %s", err)
	}
	provider := sdkmetric.NewMeterProvider(
		sdkmetric.WithReader(sdkmetric.NewPeriodicReader(exporter)),
		sdkmetric.WithResource(r),
	)

	meter := provider.Meter("example.com/metrics")
	counter, err = meter.Int64Counter("sidecar-sample-counter")
	if err != nil {
		log.Fatalf("Error creating counter: %s", err)
	}
	return provider.Shutdown
}

서비스의 작동 환경을 정의하는 Dockerfile입니다.

FROM golang:1.21 as builder
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o sample-app

FROM alpine:3
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/sample-app /sample-app
CMD ["/sample-app"]

이 샘플은 또한 커스텀 OpenTelemetry Collector를 빌드하기 위해 collector 하위 디렉터리 아래의 파일을 포함합니다.

OpenTelemetry Collector의 구성 파일

receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  # automatically detect Cloud Run resource metadata
  resourcedetection:
    detectors: [env, gcp]
    timeout: 2s
    override: false

  resource:
    attributes:
      # add instance_id as a resource attribute
    - key: service.instance.id
      from_attribute: faas.id
      action: upsert
      # parse service name from K_SERVICE Cloud Run variable
    - key: service.name
      value: ${env:K_SERVICE}
      action: insert

exporters:
  googlemanagedprometheus: # Note: this is intentionally left blank

extensions:
  health_check:

service:
  extensions: [health_check]
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch, memory_limiter, resourcedetection, resource]
      exporters: [googlemanagedprometheus]

업스트림 Collector 이미지에 제공된 구성을 번들로 연결하는 Dockerfile

FROM otel/opentelemetry-collector-contrib:0.75.0

COPY collector-config.yaml /etc/otelcol-contrib/config.yaml

코드 제공

코드 제공은 Cloud Build로 컨테이너 이미지를 빌드하고, Artifact Registry에 컨테이너 이미지를 업로드하고, 컨테이너 이미지를 Cloud Run에 배포하는 세 단계로 구성됩니다.

코드를 제공하려면 다음 안내를 따르세요.

샘플 서비스 컨테이너를 빌드하고 Artifact Registry에 게시합니다.
```
gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/run-otel/sample-metrics-app
```
성공하면 ID, 생성 시간, 이미지 이름이 포함된 성공 메시지가 표시됩니다. 이미지는 Artifact Registry에 저장되며 원하는 경우 다시 사용할 수 있습니다.
Collector 컨테이너를 빌드하고 Artifact Registry에 게시합니다.
```
gcloud builds submit collector --tag REGION-docker.pkg.dev/PROJECT_ID/run-otel/otel-collector-metrics
```
성공하면 ID, 생성 시간, 이미지 이름이 포함된 성공 메시지가 표시됩니다. 이미지는 Artifact Registry에 저장되며 원하는 경우 다시 사용할 수 있습니다.

애플리케이션 배포

YAML

다음 항목으로 service.yaml이라는 새 파일을 만듭니다.

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE-NAME
  annotations:
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/container-dependencies: "{app:[collector]}"
    spec:
      containers:
      - image: REGION-docker.pkg.dev/PROJECT_ID/run-otel/sample-metrics-app
        name: app
        ports:
        - containerPort: CONTAINER_PORT
        env:
        - name: "OTEL_EXPORTER_OTLP_ENDPOINT"
          value: "http://localhost:4317"
      - image: REGION-docker.pkg.dev/PROJECT_ID/run-otel/otel-collector-metrics
        name: collector
        startupProbe:
          httpGet:
            path: /
            port: 13133

다음을 바꿉니다.
- CONTAINER_PORT를 서비스 인그레스 컨테이너가 리슨하는 포트로 바꿉니다. 기본적으로 8080입니다.
- SERVICE-NAME을 서비스 이름을 바꿉니다(예: custom-metrics-sample-service).

다음 명령어를 사용하여 새 서비스를 만듭니다.
```
gcloud run services replace service.yaml
```
이 명령어는 서비스 URL을 반환합니다. 이 URL을 사용해서 사용해 보기의 샘플 애플리케이션을 사용해 봅니다.

사용해 보기

코드 제공의 gcloud run 명령어의 URL을 사용해서 서비스에 연결하여 몇 가지 샘플 측정항목을 생성합니다. 이 명령어를 여러 번 실행하여 더 흥미로운 데이터를 생성해볼 수 있습니다.

curl -H \
"Authorization: Bearer $(gcloud auth print-identity-token)" \
SERVICE_URL

SERVICE_URL을 서비스 URL로 바꿉니다.

그런 후 Google Cloud 콘솔의 Cloud Monitoring 섹션 내에 있는 측정항목 탐색기로 이동하고 sidecar_sample_counter 측정항목을 선택합니다.

측정항목 탐색기 UI에 표시된 커스텀 측정항목

또한 PromQL을 사용해서 측정항목을 쿼리할 수 있습니다. 예를 들어 아래 쿼리는 Cloud Run 인스턴스 ID를 기반으로 측정항목을 필터링합니다.

sidecar_sample_counter{instance="INSTANCE_ID"}

INSTANCE_ID를 서비스의 인스턴스 ID로 바꿉니다(인스턴스 로그 또는 메타데이터 서버에서 확인 가능).

이 쿼리는 아래 항목과 같은 차트를 생성합니다.

PromQL에서 쿼리된 커스텀 측정항목

삭제

이 튜토리얼용으로 새 프로젝트를 만든 경우 이 프로젝트를 삭제합니다. 기존 프로젝트를 사용한 경우 이 튜토리얼에 추가된 변경사항은 제외하고 보존하려면 튜토리얼용으로 만든 리소스를 삭제합니다.

프로젝트 삭제

비용이 청구되지 않도록 하는 가장 쉬운 방법은 튜토리얼에서 만든 프로젝트를 삭제하는 것입니다.

프로젝트를 삭제하려면 다음 안내를 따르세요.

주의: 프로젝트를 삭제하면 다음과 같은 효과가 발생합니다.

프로젝트의 모든 항목이 삭제됩니다. 이 문서의 태스크에 기존 프로젝트를 사용한 경우 프로젝트를 삭제하면 프로젝트에서 수행한 다른 작업도 삭제됩니다.
커스텀 프로젝트 ID가 손실됩니다. 이 프로젝트를 만들 때 앞으로 사용할 커스텀 프로젝트 ID를 만들었을 수 있습니다. appspot.com URL과 같이 프로젝트 ID를 사용하는 URL을 보존하려면 전체 프로젝트를 삭제하는 대신 프로젝트 내에서 선택한 리소스만 삭제합니다.

여러 아키텍처, 튜토리얼, 빠른 시작을 살펴보려는 경우 프로젝트를 재사용하면 프로젝트 할당량 한도 초과를 방지할 수 있습니다.

Google Cloud 콘솔에서 리소스 관리 페이지로 이동합니다.
리소스 관리로 이동
프로젝트 목록에서 삭제할 프로젝트를 선택하고 삭제를 클릭합니다.
대화상자에서 프로젝트 ID를 입력한 후 종료를 클릭하여 프로젝트를 삭제합니다.

튜토리얼 리소스 삭제

이 튜토리얼에서 배포한 Cloud Run 서비스를 삭제합니다.
```
gcloud run services delete SERVICE-NAME
```
여기서 SERVICE-NAME은 선택한 서비스 이름입니다.

Google Cloud 콘솔에서 Cloud Run 서비스를 삭제할 수도 있습니다.
튜토리얼 설정 중에 추가한 gcloud 기본 리전 구성을 삭제합니다.
```
 gcloud config unset run/region
```
프로젝트 구성을 삭제합니다.
```
 gcloud config unset project
```
이 튜토리얼에서 만든 다른 Google Cloud 리소스를 삭제합니다.
- Artifact Registry Docker 저장소 삭제

다음 단계

trace 및 로그 예시를 포함하여 더 많은 예시는 GitHub에서 확인할 수 있습니다.