Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

GKE용 관리형 OpenTelemetry 배포

Autopilot Standard

이 문서에서는 GKE용 관리형 OpenTelemetry를 설정하여 GKE에서 실행되는 애플리케이션에서 OpenTelemetry 프로토콜 (OTLP) trace, 측정항목, 로그를 Google Cloud Observability로 전송하는 방법을 설명합니다.

GKE용 관리형 OpenTelemetry의 작동 방식에 관한 자세한 내용은 GKE용 관리형 OpenTelemetry를 참고하세요.

GKE용 관리형 OpenTelemetry를 사용하여 다음 작업을 할 수 있습니다.

관리형 수집기로 OpenTelemetry 프로토콜 (OTLP) trace, 측정항목, 로그를 전송하도록 GKE에서 실행되는 워크로드를 구성합니다.
GKE에서 실행되는 애플리케이션에서 OpenTelemetry 프로토콜 (OTLP) trace, 측정항목, 로그를 수신합니다.
해당 데이터를 Google Cloud Observability로 내보냅니다.

Collector 수준 필터링 및 제어가 필요한 경우 이 관리형 제품 대신 Google 기반의 OpenTelemetry Collector를 사용하세요.

시작하기 전에

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

Google Cloud CLI를 설치합니다.

참고: 이전에 gcloud CLI를 설치했으면 gcloud components update를 실행하여 최신 버전이 설치되어 있는지 확인하세요.

외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.

gcloud init

Google Cloud 프로젝트를 만들거나 선택합니다.

프로젝트를 선택하거나 만드는 데 필요한 역할

프로젝트 선택: 프로젝트를 선택하는 데는 특정 IAM 역할이 필요하지 않습니다. 역할이 부여된 프로젝트를 선택하면 됩니다.
프로젝트 만들기: 프로젝트를 만들려면 resourcemanager.projects.create 권한이 포함된 프로젝트 생성자 역할(roles/resourcemanager.projectCreator)이 필요합니다. 역할 부여 방법 알아보기

Google Cloud 프로젝트를 만듭니다.
```
gcloud projects create PROJECT_ID
```
PROJECT_ID를 만들려는 Google Cloud 프로젝트의 이름으로 바꿉니다.
생성한 Google Cloud 프로젝트를 선택합니다.
```
gcloud config set project PROJECT_ID
```
PROJECT_ID을 Google Cloud 프로젝트 이름으로 바꿉니다.

이 가이드를 완료하는 데 필요한 권한이 있는지 확인합니다.

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

GKE, 원격 분석 (OTLP), Cloud Logging, Cloud Monitoring, Cloud Trace API를 사용 설정합니다.

API 사용 설정에 필요한 역할

API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할 (roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기

gcloud services enable container.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Google Cloud CLI를 설치합니다.

참고: 이전에 gcloud CLI를 설치했으면 gcloud components update를 실행하여 최신 버전이 설치되어 있는지 확인하세요.

외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.

gcloud init

Google Cloud 프로젝트를 만들거나 선택합니다.

프로젝트를 선택하거나 만드는 데 필요한 역할

프로젝트 선택: 프로젝트를 선택하는 데는 특정 IAM 역할이 필요하지 않습니다. 역할이 부여된 프로젝트를 선택하면 됩니다.
프로젝트 만들기: 프로젝트를 만들려면 resourcemanager.projects.create 권한이 포함된 프로젝트 생성자 역할(roles/resourcemanager.projectCreator)이 필요합니다. 역할 부여 방법 알아보기

Google Cloud 프로젝트를 만듭니다.
```
gcloud projects create PROJECT_ID
```
PROJECT_ID를 만들려는 Google Cloud 프로젝트의 이름으로 바꿉니다.
생성한 Google Cloud 프로젝트를 선택합니다.
```
gcloud config set project PROJECT_ID
```
PROJECT_ID을 Google Cloud 프로젝트 이름으로 바꿉니다.

이 가이드를 완료하는 데 필요한 권한이 있는지 확인합니다.

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

GKE, 원격 분석 (OTLP), Cloud Logging, Cloud Monitoring, Cloud Trace API를 사용 설정합니다.

API 사용 설정에 필요한 역할

gcloud services enable container.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

요구사항

GKE용 관리 OpenTelemetry를 사용하려면 다음 요구사항을 충족해야 합니다.

클러스터에 GKE 버전 1.34.1-gke.2178000 이상이 있어야 합니다.
버전 551.0.0 이상으로 사용 설정된 gcloud CLI
Terraform을 사용하여 GKE 인프라를 프로비저닝하는 경우 버전 v7.17.0 이상의 terraform-provider-google-beta 제공업체를 사용해야 합니다.

필요한 역할

GKE 관리 OpenTelemetry를 사용 설정하고 사용하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

Kubernetes Engine 클러스터 관리자 (roles/container.clusterAdmin)
모니터링 뷰어 (roles/monitoring.viewer)
로그 뷰어(roles/logging.viewer)
Cloud Trace 사용자(roles/cloudtrace.user)

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

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

비용

GKE용 관리 OpenTelemetry 사용과 관련된 비용에 대한 자세한 내용은 결제를 참고하세요.

클러스터에서 GKE용 관리형 OpenTelemetry 사용 설정

GKE용 관리 OpenTelemetry를 설정하려면 다음을 수행해야 합니다.

클러스터에서 GKE용 관리형 OpenTelemetry를 사용 설정합니다.
모니터링 중인 애플리케이션이 관리형 수집기의 엔드포인트로 신호를 전송하도록 구성합니다.

GKE용 관리형 OpenTelemetry를 사용 설정하면 다음 객체가 클러스터에 배포됩니다.

gke-managed-otel 네임스페이스 내에 배포된 GKE 관리 OpenTelemetry 수집기 배포 로그, 측정항목, 트레이스를 위한 클러스터 내 관리 OpenTelemetry Collector HTTP 엔드포인트는 http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318입니다.
워크로드의 자동 구성을 설정하는 데 사용할 수 있는 커스텀 리소스 정의 instrumentations.telemetry.googleapis.com

커스텀 리소스에 대한 자세한 내용은 Kubernetes 문서의 커스텀 리소스를 참고하세요.

새 클러스터에서 사용 설정

새 클러스터에서 GKE용 관리 OpenTelemetry를 사용 설정하려면 다음 단계를 따르세요.

gcloud

Autopilot 클러스터의 경우 다음 명령어를 사용합니다.

gcloud beta container clusters create-auto CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION \
  --cluster-version=VERSION

다음을 바꿉니다.

CLUSTER_NAME: 클러스터의 이름입니다.
PROJECT_ID: Google Cloud 프로젝트 ID
LOCATION: 리전 또는 영역입니다.
VERSION: 버전. 1.34.1-gke.2178000 이상이어야 합니다.

Standard 클러스터의 경우 다음 명령어를 사용합니다.

gcloud beta container clusters create CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION \
  --cluster-version=VERSION

다음을 바꿉니다.

CLUSTER_NAME: 클러스터의 이름입니다.
PROJECT_ID: Google Cloud 프로젝트 ID
LOCATION: 리전 또는 영역입니다.
VERSION: 버전. 1.34.1-gke.2178000 이상이어야 합니다.

콘솔

Autopilot 클러스터의 경우 다음을 수행합니다.
1. Google Cloud 콘솔에서 Autopilot 클러스터 만들기 페이지로 이동합니다.
  Autopilot 클러스터 만들기로 이동
2. 탐색 패널에서 고급 설정을 클릭합니다.
3. 작업 섹션에서 관리형 OpenTelemetry 사용 설정을 선택합니다.
4. 저장을 클릭합니다.
Standard 클러스터의 경우 다음을 수행합니다.
1. Google Cloud 콘솔에서 Kubernetes 클러스터 만들기 페이지로 이동합니다.
  Kubernetes 클러스터 만들기로 이동
2. 탐색 패널에서 기능을 클릭합니다.
3. 작업 섹션에서 관리형 OpenTelemetry 사용 설정을 선택합니다.
4. 저장을 클릭합니다.

Terraform

Terraform을 사용하여 새 클러스터에서 GKE용 관리형 OpenTelemetry를 사용 설정하려면 다음 예시를 참고하세요.

terraform {
  required_providers {
    google-beta = {
      source  = "hashicorp/google-beta"
      version = ">= 7.17.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  provider = google-beta
  location = "us-west1"

  initial_node_count = 1
  release_channel {
    channel = "RAPID" # The default rapid version already has the feature available.
  }

  managed_opentelemetry_config {
    scope = "COLLECTION_AND_INSTRUMENTATION_COMPONENTS"
  }
}

Terraform 사용에 대한 자세한 내용은 GKE에 대한 Terraform 지원을 참조하세요.

기존 클러스터에서 사용 설정

기존 클러스터에서 GKE용 관리형 OpenTelemetry를 사용 설정하려면 다음 단계를 따르세요.

gcloud

클러스터 버전이 1.34.1-gke.2178000 이상인지 확인합니다. 기존 클러스터를 업그레이드하는 방법에 대한 자세한 내용은 Standard 클러스터 업그레이드 및 Autopilot 클러스터 업그레이드를 참고하세요.
다음 명령어를 사용하여 GKE용 관리형 OpenTelemetry를 사용 설정합니다.
```
gcloud beta container clusters update CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION
```
다음을 바꿉니다.
- CLUSTER_NAME: 클러스터의 이름입니다.
- PROJECT_ID: Google Cloud 프로젝트 ID
- LOCATION: 리전 또는 영역입니다.

콘솔

클러스터 버전이 1.34.1-gke.2178000 이상인지 확인합니다. 기존 클러스터를 업그레이드하는 방법에 대한 자세한 내용은 Standard 클러스터 업그레이드 및 Autopilot 클러스터 업그레이드를 참고하세요.
Google Cloud 콘솔에서 Kubernetes 클러스터 페이지로 이동합니다.

Kubernetes 클러스터로 이동
클러스터 이름을 클릭합니다.
기능 목록에서 Managed OpenTelemetry 옵션을 찾습니다. 사용 중지됨으로 표시되면 수정 수정을 클릭한 후 관리형 OpenTelemetry 사용 설정을 선택합니다.
변경사항 저장을 클릭합니다.

Terraform

기존 클러스터에서 GKE용 관리형 OpenTelemetry를 사용 설정하려면 다음 예와 같이 기존 google_container_cluster 리소스에 managed_opentelemetry_config 블록을 추가합니다.

terraform {
  required_providers {
    google-beta = {
      source  = "hashicorp/google-beta"
      version = ">= 7.17.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  provider = google-beta
  location = "us-west1"

  initial_node_count = 1
  release_channel {
    channel = "RAPID" # The default rapid version already has the feature available.
  }

  managed_opentelemetry_config {
    scope = "COLLECTION_AND_INSTRUMENTATION_COMPONENTS"
  }
}

Terraform 사용에 대한 자세한 내용은 GKE에 대한 Terraform 지원을 참조하세요.

관리형 OpenTelemetry 수집기를 사용하도록 애플리케이션 구성

관리형 수집기의 엔드포인트로 신호를 전송할 수 있도록 애플리케이션을 구성해야 합니다. 애플리케이션이 구성되면 관리형 OpenTelemetry 수집기는 수집기가 사용 설정된 클러스터에서 실행되는 애플리케이션으로부터 신호를 수신합니다. 애플리케이션의 신호에는 trace, 측정항목, 로그가 포함됩니다.

OpenTelemetry 신호를 전송하려면 애플리케이션이 이미 OpenTelemetry 측정항목을 생성하도록 계측되어 있어야 합니다. 자세한 내용은 지원되는 워크로드를 참고하세요.

관리형 수집기 엔드포인트로 신호를 전송하도록 애플리케이션을 수동으로 구성하거나 자동 구성을 사용할 수 있습니다. 자동 구성이 수동 변경사항을 재정의할 수 있으므로 동일한 워크로드에 두 방법을 모두 함께 사용하는 것은 권장하지 않습니다. 이 조합을 사용하면 구성 변경사항을 추적하기가 더 어려워질 수 있습니다.

다음 섹션에서는 자동 구성을 사용하여 수집기에 신호를 전송하도록 애플리케이션을 구성하는 방법을 설명합니다.

자동 구성 설정

자동 구성은 환경 변수를 사용하여 관리형 수집기의 엔드포인트에 신호를 전송하도록 워크로드를 구성합니다.

포드에 환경 변수를 자동으로 삽입하려면 Instrumentation 커스텀 리소스를 사용합니다. 환경 변수에는 OpenTelemetry 구성이 있으며 네임스페이스의 일치하는 라벨이 있는 일부 포드 또는 네임스페이스의 모든 포드에 삽입할 수 있습니다.

그런 다음 애플리케이션이 네임스페이스에 배포되면 GKE는 구성을 사용하여 워크로드가 실행되는 포드에 환경 변수를 자동으로 삽입합니다.

Instrumentation 커스텀 리소스를 구성하려면 다음 단계를 따르세요.
1. 다음 Instrumentation 매니페스트를 otlp-auto-config-namespace.yaml이라는 파일에 저장합니다.
```
apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: NAMESPACE
  name: NAME
spec:
  selector:
    matchLabels:
      KEY: VALUE
  autoInstrumentationConfig:
    configInjection:
      enabled: true
  otelSDKConfig:
    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "TRACE_RATIO"
    meter_provider:
      readers:
      - periodic:
          interval: METRICS_INTERVAL
```
  다음을 바꿉니다.
  - NAMESPACE: 자동 계측의 타겟으로 지정할 포드가 포함된 네임스페이스입니다. default를 사용하여 기본 네임스페이스를 타겟팅합니다.
  - NAME: 매니페스트 파일의 이름입니다. 이 예시에서 이름은 otlp-auto-config-namespace.yaml입니다.
  - (선택사항) 타겟팅할 포드에 연결된 라벨입니다. 빈 선택기가 지정되면 ({}) 네임스페이스의 모든 포드가 타겟팅됩니다.
    - KEY: 라벨의 키
    - VALUE: 라벨의 값
  - TRACE_RATIO: 수집할 추적 데이터의 비율입니다. 지정하지 않으면 기본값은 1.0입니다. 자세한 내용은 트레이스 샘플링 레이트 수정을 참고하세요.
  - METRICS_INTERVAL: 수집할 모니터링 데이터의 간격(밀리초)입니다. 기본값은 30000입니다. 값은 음수가 아니어야 하며 최솟값은 5,000ms, 최댓값은 300,000ms, 5,000ms의 배수여야 합니다. 자세한 내용은 측정항목 내보내기 간격 수정을 참고하세요.
2. 설정을 수정하려면 다음 섹션에서 구성을 수정하세요.
3. 다음 명령어를 실행하여 구성을 적용합니다.
```
kubectl apply -f otlp-auto-config-namespace.yaml
```
환경 변수를 자동으로 삽입하려면 구성이 적용된 클러스터의 네임스페이스에 애플리케이션을 배포해야 합니다.
- 아직 네임스페이스에서 실행되지 않는 워크로드에 구성을 적용하려면 다음 명령어를 사용하여 워크로드를 배포합니다.
```
kubectl apply -f DEPLOYMENT_NAME -n NAMESPACE
```
  다음을 바꿉니다.
  - DEPLOYMENT_NAME: 배포 이름입니다.
  - NAMESPACE: 네임스페이스입니다.
- 네임스페이스에서 이미 실행 중인 워크로드에 구성을 적용하려면 다음 명령어를 사용하여 워크로드를 다시 배포합니다.
```
kubectl rollout restart deployment DEPLOYMENT_NAME -n NAMESPACE
```
  다음을 바꿉니다.
  - DEPLOYMENT_NAME: 배포 이름입니다.
  - NAMESPACE: 네임스페이스입니다.

클러스터에 구성을 적용하면 GKE가 클러스터에 배포될 때 모든 워크로드를 자동으로 구성합니다. 워크로드는 워크로드가 실행되는 포드에 환경 변수를 삽입하여 계측됩니다.

이러한 환경 변수로 구성된 워크로드가 관리형 수집기가 배포된 클러스터에서 실행되면 워크로드가 실행될 때 관리형 수집기에 OpenTelemetry 신호를 전송합니다. 이러한 신호는 Google Cloud Observability에서 확인할 수 있습니다.

신호 보기에 대한 자세한 내용은 원격 분석 보기를 참고하세요. 예를 들어 샘플 원격 분석 생성을 참고하세요.

구성 수정

구성을 수정하려면 다음을 수행해야 합니다.

Instrumentation 매니페스트 파일을 수정합니다.
수정된 구성을 적용합니다.
수정된 구성을 적용한 후 클러스터의 해당 네임스페이스에서 애플리케이션을 다시 배포하거나 다시 시작합니다.

이 단계에 대한 자세한 내용은 구성 만들기 및 배포 섹션의 안내를 따르세요.

데이터 수집량 또는 빈도 수정

추적 샘플링 레이트를 수정하여 수집되는 추적 데이터의 양을 수정할 수 있습니다.

측정항목 내보내기 간격 수정을 통해 모니터링 데이터가 Cloud Monitoring으로 전송되는 빈도를 수정할 수 있습니다.

수집되는 로깅 데이터의 양이나 빈도는 수정할 수 없습니다. 하지만 로깅, 측정항목 또는 추적 데이터의 수집을 모두 사용 중지할 수는 있습니다. 자세한 내용은 수집할 신호 유형 선택하기를 참고하세요.

트레이스 샘플링 레이트 수정

워크로드에서 많은 양의 추적 데이터를 생성할 수 있습니다. 자신의 상황에 맞게 데이터를 수집하고 저장하는 비용과 데이터가 유용하기 위해 필요한 세부정보 수준 간의 균형을 결정하는 것이 중요합니다.

기본 OpenTelemetry SDK 동작은 always_on이며 이는 비율 1과 동일합니다.

다음은 추적 샘플링 비율 구성의 예입니다. 이 예에서 비율은 0.25이므로 추적 데이터는 25%의 비율로 수집됩니다. 이 비율 숫자를 수정하여 샘플링 비율을 변경합니다.

    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "0.25"

측정항목 내보내기 간격 수정

측정항목 내보내기 간격은 Cloud Monitoring의 그래프에 표시되는 데이터의 세부사항을 결정합니다.

다음은 측정항목 내보내기 간격 구성의 예시입니다. 이 예에서 내보내기 간격은 30,000ms입니다.

측정항목 내보내기 간격은 OpenTelemetry SDK에서 연속된 두 측정항목 내보내기 사이의 지연 간격을 지정하는 데 사용됩니다.

이 간격의 값은 음수가 아니어야 하며 최솟값은 5,000ms, 최댓값은 300,000ms, 5,000ms의 배수여야 합니다. 값은 밀리초로 표현됩니다.

meter_provider:
  readers:
  - periodic:
      interval: 30000

수집할 신호 유형 선택

수집하지 않을 신호 유형을 사용 중지하여 워크로드에서 수집되는 신호 유형을 제어할 수 있습니다. 신호 유형은 트레이스, 측정항목, 로그입니다.

워크로드가 실행되는 컨테이너의 환경 변수를 사용하여 신호 유형을 사용 중지합니다. Instrumentation 커스텀 리소스를 수정한 다음 컨테이너에 워크로드를 다시 배포하여 환경 변수를 수정합니다.

다음 예는 추적 데이터만 수집하도록 구성된 Instrumentation 매니페스트 파일입니다. meter_provider 및 logger_provider이 null로 설정되어 있어 로그 및 측정항목 수집이 사용 중지됩니다.

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: otlp-auto-config-disable-metrics-logs
spec:
  selector:
    matchLabels: # Update the labels to match your workloads
      app: telemetrygen-app
  autoInstrumentationConfig:
    configInjection:
      enabled: true
  otelSDKConfig:
    meter_provider: null
    logger_provider: null

멀티모달 프롬프트 및 대답 데이터 수집

GKE용 관리형 OpenTelemetry를 구성하여 멀티모달 프롬프트 및 응답 데이터를 수집할 수 있습니다.

이 기능은 LangGraph ReAct 에이전트와 에이전트 개발 키트 (ADK) 프레임워크로 빌드된 생성형 AI 에이전트에 사용할 수 있습니다.

GKE용 관리 OpenTelemetry가 멀티모달 프롬프트 및 응답 데이터를 수집하도록 구성하려면 다음 단계를 따르세요.

멀티모달 프롬프트 및 대답 수집 섹션의 안내에 따라 Google Cloud 프로젝트와 사용 중인 SDK를 구성합니다.
멀티모달 프롬프트와 대답을 수집하는 데 사용할 Cloud Storage 버킷을 만들거나 식별합니다. 자세한 내용은 버킷 만들기를 참고하세요.
애플리케이션에서 사용하는 서비스 계정에 Cloud Storage 버킷에 대한 storage.objects.create 권한을 부여합니다.

이 권한을 사용하면 애플리케이션이 Cloud Storage 버킷에 객체를 작성할 수 있습니다. 이러한 객체는 에이전트형 애플리케이션이 만들고 수신하는 프롬프트와 대답을 저장합니다. 자세한 내용은 버킷에 IAM 정책 설정 및 관리를 참고하세요.

Instrumentation 커스텀 리소스에서 promptsResponses.uploadBasePath 필드를 구성합니다. 예를 들면 다음과 같습니다.

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: prompts-responses
spec:
  selector: {}
  promptsResponses:
    uploadBasePath: gs://BUCKET_NAME

BUCKET_NAME을 Cloud Storage 버킷 이름으로 바꿉니다.

Instrumentation 커스텀 리소스가 업데이트되고 워크로드가 다시 시작되면 프롬프트와 응답을 구성하는 환경 변수가 워크로드의 컨테이너에 삽입됩니다.

수집할 수 있는 미디어 유형과 멀티모달 프롬프트 및 대답을 탐색하는 방법에 관한 자세한 내용은 멀티모달 프롬프트 및 대답 수집 및 보기를 참고하세요.

워크로드 자동 구성 사용 중지

지정된 구성으로 워크로드의 자동 계측을 사용 중지하려면 클러스터에서 Instrumentation 커스텀 리소스를 삭제합니다. 이렇게 하려면 다음 명령어를 사용합니다.

kubectl delete instrumentations.telemetry.googleapis.com INSTRUMENTATION_NAME -n NAMESPACE

다음을 바꿉니다.

INSTRUMENTATION_NAME: Instrumentation 커스텀 리소스의 이름입니다.
NAMESPACE: 자동 구성을 사용 중지하려는 포드가 포함된 네임스페이스입니다.

나중에 사용할 수 있도록 자동 계측 구성을 유지하면서 환경 변수 자동 삽입을 일시적으로 사용 중지하려면 autoInstrumentationConfig.configInjection.enabled를 false로 설정하고 업데이트된 커스텀 리소스를 적용합니다.

다음은 자동 환경 변수 삽입이 일시적으로 사용 중지된 맞춤 리소스의 예입니다.

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: otlp-auto-config-example
spec:
  selector:
    matchLabels: # Update the labels to match your workloads
      app: telemetrygen-app
  autoInstrumentationConfig:
    configInjection:
      enabled: false # disable environment variables config injection
  otelSDKConfig:
  ... # preserve OpenTelemetry configuration for future use

커스텀 리소스를 삭제하거나 자동 구성 삽입을 사용 중지하도록 업데이트한 후에는 GKE가 Instrumentation 커스텀 리소스의 타겟이 되는 새 워크로드를 자동으로 계측하지 않습니다.

이전에 커스텀 리소스에 의해 계측된 워크로드에서 관리형 수집기로 OTLP 신호 내보내기를 중지하려면 변경사항을 적용하기 위해 워크로드를 다시 시작해야 합니다. 이렇게 하려면 다음 명령어를 사용하세요.

kubectl rollout restart deployment DEPLOYMENT_NAME -n NAMESPACE

다음을 바꿉니다.

DEPLOYMENT_NAME: 배포 이름입니다.
NAMESPACE: 네임스페이스입니다.

원격 분석 보기

구성된 워크로드가 GKE에서 실행되고 GKE용 관리 OpenTelemetry가 사용 설정된 경우 OpenTelemetry 신호가 Google Cloud Observability로 전송됩니다.

Google Cloud Observability에서 데이터를 보는 방법에 대한 자세한 내용은 다음을 참고하세요.

샘플 원격 분석 생성

이 섹션에서는 샘플 애플리케이션을 배포하고 이 애플리케이션을 관리형 OpenTelemetry Collector의 OTLP 엔드포인트로 가리키는 방법을 설명합니다. 그런 다음 Google Cloud에서 원격 분석을 볼 수 있습니다.

샘플 애플리케이션은 trace, 로그, 측정항목을 클러스터 내 관리 OpenTelemetry Collector HTTP 엔드포인트로 내보내는 소형 생성기입니다. OTLP 엔드포인트는 애플리케이션 내에 하드코딩되어 http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318를 가리킵니다.

이미 OpenTelemetry SDK로 계측된 애플리케이션이 있으면 애플리케이션을 Collector 엔드포인트로 가리키거나 애플리케이션의 자동 계측을 구성하여 애플리케이션에서 원격 분석을 생성할 수 있습니다.

샘플 애플리케이션을 배포하려면 다음 단계를 따르세요.

관리형 OpenTelemetry를 사용 설정한 클러스터에 연결합니다. 자세한 내용은 kubectl 명령어의 기본 클러스터 설정을 참고하세요.
다음 명령어를 실행합니다.
```
kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/main/sample/gke-app.yaml
```
몇 분 후 애플리케이션에서 생성된 원격 분석이 수집기를 통해 각 신호의 Google Cloud 백엔드로 전송되기 시작합니다.
1. Google Cloud 콘솔에서 데모 애플리케이션의 로그, 측정항목, 트레이스를 확인하여 원격 분석이 수집되었는지 확인합니다.
2. 측정항목을 보려면 다음 안내를 따르세요.
  1. Google Cloud 콘솔에서 측정항목 탐색기 페이지로 이동합니다.
    
    측정항목 탐색기로 이동
  2. 측정항목 탐색기에서 다음 PromQL 쿼리를 실행합니다.
```
sum(avg_over_time({"__name__"="gen","namespace"="opentelemetry-demo","job"="telemetrygen"}[1h]))
```
3. 트레이스를 보려면 다음 단계를 따르세요.
  1. Google Cloud 콘솔에서 Trace 탐색기 페이지로 이동합니다.
    
    trace 탐색기로 이동
  2. 스팬 이름이 lets-go인 추적 스팬을 필터링합니다.
4. 로그를 보려면 다음 단계를 따르세요.
  1. Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.
    
    로그 탐색기로 이동
  2. 다음 쿼리를 실행합니다.
```
resource.type="k8s_pod"
resource.labels.namespace_name="opentelemetry-demo"
```

GKE용 관리형 OpenTelemetry 사용 중지

클러스터에서 GKE용 관리형 OpenTelemetry를 사용 중지할 수 있습니다. 수집기를 사용 중지하면 관리형 OpenTelemetry 수집기가 클러스터에서 삭제되고 새로운 원격 분석 데이터가 수집되지 않습니다.

GKE용 관리형 OpenTelemetry를 사용 중지하려면 다음 단계를 따르세요.

gcloud

클러스터에서 GKE용 관리형 OpenTelemetry를 사용 중지하려면 다음 gcloud 명령어를 실행합니다.

  gcloud beta container clusters update CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=NONE \
  --location=LOCATION

다음을 바꿉니다.

CLUSTER_NAME: 클러스터의 이름입니다.
PROJECT_ID: Google Cloud 프로젝트 ID
LOCATION: 리전 또는 영역입니다.

콘솔

콘솔에서 클러스터 목록으로 이동합니다.

Kubernetes 클러스터로 이동
관리형 OpenTelemetry 수집기를 사용 중지할 클러스터를 선택합니다.
클러스터 세부정보의 관리형 OpenTelemetry 옆에 있는 수정 아이콘을 선택합니다.
체크박스를 선택 해제하여 기능을 사용 중지합니다.

Terraform

GKE용 관리 OpenTelemetry를 사용 중지하려면 google_container_cluster 리소스에서 managed_opentelemetry_config 블록을 업데이트하여 범위를 NONE로 설정합니다.

Terraform 구성 파일을 업데이트합니다.

resource "google_container_cluster" "default" {
  provider = google-beta
  name     = "CLUSTER_NAME"
  location = "LOCATION"
  project  = "PROJECT_ID"

  # ... other configuration ...

  managed_opentelemetry_config {
    scope = "NONE"
  }
}

Terraform 구성을 적용합니다.
```
terraform apply
```

다음을 바꿉니다.

CLUSTER_NAME: 클러스터의 이름입니다.
LOCATION: 리전 또는 영역입니다.
PROJECT_ID: Google Cloud 프로젝트 ID

GKE용 관리 OpenTelemetry를 사용 중지해도 Instrumentation 커스텀 리소스 정의와 Instrumentation 커스텀 리소스는 클러스터에서 삭제되지 않습니다. 관리형 OpenTelemetry를 다시 사용 설정하면 Instrumentation 커스텀 리소스에 보존된 구성을 사용합니다.

GKE용 관리 OpenTelemetry에서 이미 수집한 원격 분석 데이터가 있는 경우 수집기를 사용 중지해도 이 데이터에는 영향을 미치지 않습니다. 기존 데이터는 Google Cloud Observability에 계속 저장되며 새로운 원격 분석 데이터는 수집되지 않습니다.

문제 해결

Autopilot 파트너 권한이 있는 워크로드

Autopilot 파트너 권한 워크로드로 자동 구성을 사용하려고 하면 해당 워크로드 포드가 거부될 수 있습니다.

OpenTelemetry 구성 삽입은 GKE Autopilot 파트너의 권한이 있는 워크로드에서 지원되지 않습니다. Instrumentation 커스텀 리소스를 사용하여 이러한 워크로드를 타겟팅하여 OpenTelemetry 환경 변수 삽입을 사용 설정하면 워크로드가 Autopilot 권한 워크로드 허용 목록과 일치하지 않을 수 있습니다. 즉, 구성이 삽입된 포드가 GKE Autopilot에 의해 거부됩니다.

Google Cloud 콘솔에 로그, 측정항목 또는 트레이스가 표시되지 않음

데이터가 표시되지 않는 이유는 다양합니다. 이러한 이유에는 데이터를 볼 수 있는 권한이 누락되었거나 데이터 수집을 방해하는 잘못된 구성이 포함됩니다.

일반적인 문제를 해결하기 위해 취할 수 있는 단계는 다음과 같습니다.

프로젝트에서 모든 필수 API가 사용 설정되어 있는지 확인합니다.
Instrumentation 커스텀 리소스가 워크로드가 실행되는 네임스페이스와 일치하는 네임스페이스와 워크로드의 라벨과 일치하는 선택기를 사용하여 올바르게 구성되어 있는지 확인합니다.
워크로드의 포드를 검사하여 환경 변수가 올바르게 삽입되었는지 확인합니다.
OpenTelemetry Collector의 컨테이너 로그를 확인하여 Collector에 오류가 있는지 확인합니다. 이렇게 하려면 다음 명령어를 실행하세요.
```
kubectl logs -n gke-managed-otel -l app=opentelemetry-collector -c opentelemetry-collector
```

원격 분석 신호 사용 중지가 작동하지 않음

Instrumentation 커스텀 리소스를 사용하여 원격 분석 신호를 사용 중지하는 경우 커스텀 리소스를 적용하고 워크로드를 재배포해야 합니다.

커스텀 리소스를 적용할 때는 Instrumentation 커스텀 리소스를 업데이트할 때 kubectl apply 명령어에서 서버 측 적용을 사용합니다.

원격 분석 신호 사용 중지에 관한 자세한 내용은 수집할 신호 유형 선택을 참고하세요.

OpenTelemetry 삽입 변수가 워크로드에 표시되지 않음

변수는 워크로드가 아닌 워크로드 포드의 컨테이너에 삽입됩니다. ReplicaSet 또는 Deployment와 같은 소유자 객체가 아닌 포드를 확인합니다.

예를 들어 이전 섹션 원격 분석 생성에서 사용된 기본 네임스페이스의 샘플 워크로드에 변수가 올바르게 삽입되었는지 확인하려면 다음 단계를 따르세요.

다음 명령어를 실행합니다.

kubectl get pods -n default -l app=telemetrygen-app -o yaml

포드의 spec.containers[*].env를 살펴봅니다.
동일한 네임스페이스에 Instrumentation 객체가 있는지 확인하고 포드를 타겟팅하며 구성 삽입 기능이 사용 설정되어 있는지 확인합니다. 이렇게 하려면 다음 명령어를 실행하세요.
```
kubectl get instrumentations.telemetry.googleapis.com -n default -o yaml
```

변수는 포드가 생성될 때만 컨테이너에 삽입됩니다. Kubernetes API는 환경 변수와 같은 기존 포드의 사양에서 대부분의 필드를 수정할 수 없기 때문입니다. Instrumentation 객체를 만들기 전에 생성된 워크로드에 구성이 적용되도록 하려면 워크로드를 다시 시작하세요. 예를 들어 telemetry-gen-app라는 배포의 경우 다음 명령어를 실행합니다.

kubectl rollout restart deployment -n default telemetry-gen-app

Cloud Trace의 과도한 trace 데이터

Cloud Trace에서 수집하는 데이터를 줄이려면 추적 ID 비율이 있는 상위 기반 샘플러를 구성하여 추적의 일부만 샘플링하면 됩니다.

예를 들어 Instrumentation 객체에 다음을 추가합니다.

spec:
  otelSDKConfig:
    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "0.01"

기본 OpenTelemetry SDK 동작은 'always_on' 추적이며 이는 비율 1과 동일합니다.

환경 변수가 구성과 일치하지 않음

Instrumentation 객체를 업데이트한 경우 구성 수정 섹션에 설명된 대로 포드를 다시 시작했는지 확인합니다.

포드의 구성이 잘못된 경우 포드가 Instrumentation 객체에 의해 올바르게 타겟팅되었는지, 동일한 포드를 타겟팅하는 Instrumentation 객체가 여러 개 있는지 확인합니다.

kubectl get instrumentations --all-namespaces \
-o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,SELECTOR:.spec.selector

kubectl get pod -n ${NAMESPACE:?} ${POD_NAME:?} --show-labels

빈 선택기는 네임스페이스의 모든 포드를 타겟팅합니다.

포드가 생성될 때 여러 계측이 동일한 포드를 타겟팅하는 경우 마지막으로 업데이트된 계측이 적용됩니다.

`kubectl logs` 명령어는 출력을 반환하지 않습니다.

로그가 애플리케이션에서 OpenTelemetry 수집기로 직접 스트리밍되면 로그가 컨테이너 런타임의 표준 로깅 경로를 우회합니다. 이는 로그에 OpenTelemetry를 사용할 때의 일반적인 시나리오입니다. 기본적으로 내보내기 도구는 stdout 및 stderr 스트림 대신 otlp 엔드포인트로 로그를 전송합니다.

이 경우 컨테이너 런타임이 캡처할 수 있도록 로그가 stdout 또는 stderr 스트림에 작성되지 않으므로 kubectl logs 명령어는 해당 애플리케이션의 출력을 표시하지 않습니다. 대신 로깅 출력은 Cloud Logging에서 확인할 수 있습니다.

OpenTelemetry SDK를 사용하고 stdout 스트림으로 로그를 전송하려면 로그 내보내기 도구를 사용하여 이를 구성하면 됩니다. 자세한 내용은 로그 내보내기 도구 - 표준 출력을 참고하세요.

다음 단계

GKE용 관리형 OpenTelemetry의 작동 방식에 관한 자세한 내용은 GKE용 관리형 OpenTelemetry를 참고하세요.
GKE용 관리형 OpenTelemetry의 자체 배포 대안은 Google 기반 OpenTelemetry Collector를 참고하세요.

GKE용 관리형 OpenTelemetry 배포 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

요구사항

필요한 역할

비용

클러스터에서 GKE용 관리형 OpenTelemetry 사용 설정

새 클러스터에서 사용 설정

gcloud

콘솔

Terraform

기존 클러스터에서 사용 설정

gcloud

콘솔

Terraform

관리형 OpenTelemetry 수집기를 사용하도록 애플리케이션 구성

자동 구성 설정

구성 수정

데이터 수집량 또는 빈도 수정

트레이스 샘플링 레이트 수정

측정항목 내보내기 간격 수정

수집할 신호 유형 선택

멀티모달 프롬프트 및 대답 데이터 수집

워크로드 자동 구성 사용 중지

원격 분석 보기

샘플 원격 분석 생성

GKE용 관리형 OpenTelemetry 사용 중지

gcloud

콘솔

Terraform

문제 해결

Autopilot 파트너 권한이 있는 워크로드

Google Cloud 콘솔에 로그, 측정항목 또는 트레이스가 표시되지 않음

원격 분석 신호 사용 중지가 작동하지 않음

OpenTelemetry 삽입 변수가 워크로드에 표시되지 않음

Cloud Trace의 과도한 trace 데이터

환경 변수가 구성과 일치하지 않음

kubectl logs 명령어는 출력을 반환하지 않습니다.

다음 단계

GKE용 관리형 OpenTelemetry 배포

`kubectl logs` 명령어는 출력을 반환하지 않습니다.