Cloud Run에 Google 기반의 OpenTelemetry Collector 배포

이 문서에서는 Cloud Run에서 Google 기반의 OpenTelemetry Collector를 실행하여 계측된 애플리케이션에서 OTLP 로그, 측정항목, trace를 수집한 다음 이 데이터를 Google Cloud로 내보내는 방법을 보여줍니다.

시작하기 전에

Google 기반의 OpenTelemetry Collector를 실행하려면 다음 리소스가 필요합니다.

  • Cloud Monitoring API, Cloud Trace API, Cloud Logging API가 사용 설정된 Google Cloud 프로젝트

    • Google Cloud 프로젝트가 없으면 다음을 수행합니다.

      1. Google Cloud 콘솔에서 새 프로젝트로 이동합니다.

        새 프로젝트 만들기

      2. 프로젝트 이름 필드에서 프로젝트 이름을 입력한 후 만들기를 클릭합니다.

      3. 결제로 이동합니다.

        결제로 이동

      4. 페이지 상단에서 아직 선택하지 않았으면 바로 전에 만든 프로젝트를 선택합니다.

      5. 기존 결제 프로필을 선택하거나 새 결제 프로필을 만들라는 메시지가 표시됩니다.

      기본적으로 Monitoring API, Trace API, Logging API는 새 프로젝트에 사용 설정되어 있습니다.

    • Google Cloud 프로젝트가 이미 있는 경우 Monitoring API, Trace API, Logging API가 사용 설정되었는지 확인합니다.

      Enable the APIs

  • Cloud Run 서비스. Cloud Run 서비스가 없는 경우 서비스 계획 및 준비의 안내를 따르세요.

  • gcloud 설치. gcloud 설치에 대한 자세한 내용은 gcloud CLI 설치를 참조하세요.

Collector 권한 구성

기본적으로 Cloud Run 작업 및 서비스는 Compute Engine 기본 서비스 계정인 PROJECT_NUMBER-compute@developer.gserviceaccount.com을 사용합니다. 이 서비스 계정에는 일반적으로 이 문서에서 설명하는 측정항목 및 로그를 작성하는 데 필요한 Identity and Access Management(IAM) 역할이 포함되어 있습니다.

관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

또한 Cloud Run에 대해 사용자 관리형 서비스 계정을 구성할 수 있습니다. 사용자 관리형 서비스 계정에는 다음 역할도 포함되어야 합니다. Cloud Run의 서비스 계정에 대한 자세한 내용은 서비스 ID 소개를 참조하세요.

Collector 배포

Google 기반의 OpenTelemetry Collector를 Cloud Run의 사이드카로 설치하려면 먼저 Collector의 구성을 저장할 보안 비밀을 만듭니다.

gcloud secrets create SECRET_NAME --data-file=config.yaml --project=PROJECT_ID

그런 다음 Google 기반의 OpenTelemetry Collector를 service.yaml에 사이드카로 추가합니다.

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  annotations:
    run.googleapis.com/launch-stage: ALPHA
  name: google-otel-cloud-run-sample
spec:
  template:
    metadata:
      annotations:
        # [REQUIRED] set the collector as a parent to the app
        run.googleapis.com/container-dependencies: "{app:[collector]}"
        run.googleapis.com/secrets: 'SECRET_NAME:projects/PROJECT_ID/secrets/SECRET_NAME'
    spec:
      containers:
      - image: my-app
        name: app
        ports:
        - containerPort: 8080
        env:
        - name: "OTEL_EXPORTER_OTLP_ENDPOINT"
          value: "http://localhost:4317"
      - image: "us-docker.pkg.dev/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector/otelcol-google:0.129.0"
        args:
        - --config=/etc/otelcol-google/config.yaml
        name: collector
        startupProbe:
          httpGet:
            path: /
            port: 13133
          timeoutSeconds: 30
          periodSeconds: 30
        livenessProbe:
          httpGet:
            path: /
            port: 13133
          timeoutSeconds: 30
          periodSeconds: 30
        volumeMounts:
        - mountPath: /etc/otelcol-google/
          name: config
      volumes:
      - name: config
        secret:
          items:
          - key: latest
            path: config.yaml
          secretName: 'SECRET_NAME'

Collector 구성

Google 기반의 Collector와 함께 사용할 수 있는 OpenTelemetry Collector 구성이 제공됩니다. 이 구성은 대량의 OTLP 측정항목, 로그, trace를 전송하도록 설계되었습니다. 또한 일반적인 수집 문제가 방지되도록 설계되었습니다. 구성을 추가할 수는 있지만 요소를 삭제하지 않는 것이 좋습니다.

이 섹션에서는 제공된 구성과 내보내기 도구, 프로세서, 수신자, 기타 사용 가능한 구성요소와 같은 주요 구성요소를 설명합니다.

제공된 Collector 구성

opentelemetry-operations-collector 저장소의 google-built-opentelemetry-collector 디렉터리에서 Collector 구성을 찾을 수 있습니다.

receivers:
  # Open two OTLP servers:
  # - On port 4317, open an OTLP GRPC server
  # - On port 4318, open an OTLP HTTP server
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver
  otlp:
    protocols:
      grpc:
        endpoint: localhost:4317
      http:
        cors:
          # This effectively allows any origin
          # to make requests to the HTTP server.
          allowed_origins:
          - http://*
          - https://*
        endpoint: localhost:4318

processors:
  # The batch processor is in place to regulate both the number of requests
  # being made and the size of those requests.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/batchprocessor
  batch:
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  # The memorylimiter will check the memory usage of the collector process.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/memorylimiterprocessor
  memory_limiter:
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  # The resourcedetection processor is configured to detect GCP resources.
  # Resource attributes that represent the GCP resource the collector is
  # running on will be attached to all telemetry that goes through this
  # processor.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#gcp-metadata
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  transform/collision:
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

exporters:
  # The googlecloud exporter will export telemetry to different
  # Google Cloud services:
  # Logs -> Cloud Logging
  # Metrics -> Cloud Monitoring
  # Traces -> Cloud Trace
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlecloudexporter
  googlecloud:
    log:
      default_log_name: opentelemetry-collector

  # The googlemanagedprometheus exporter will send metrics to
  # Google Managed Service for Prometheus.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlemanagedprometheusexporter
  googlemanagedprometheus:

extensions:
  # Opens an endpoint on 13133 that can be used to check the
  # status of the collector. Since this does not configure the
  # `path` config value, the endpoint will default to `/`.
  #
  # When running on Cloud Run, this extension is required and not optional.
  # In other environments it is recommended but may not be required for operation
  # (i.e. in Container-Optimized OS or other GCE environments).
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/healthcheckextension
  health_check:
    endpoint: 0.0.0.0:13133

service:
  extensions:
  - health_check
  pipelines:
    logs:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - memory_limiter
      - batch
      exporters:
      - googlecloud
    metrics/otlp:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - transform/collision
      - memory_limiter
      - batch
      exporters:
      - googlemanagedprometheus
    traces:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - memory_limiter
      - batch
      exporters:
      - googlecloud
  # Internal telemetry for the collector supports both push and pull-based telemetry data transmission.
  # Leveraging the pre-configured OTLP receiver eliminates the need for an additional port.
  #
  # Docs:
  # https://opentelemetry.io/docs/collector/internal-telemetry/
  telemetry:
    metrics:
      readers:
        - periodic:
            exporter:
              otlp:
                protocol: grpc
                endpoint: localhost:4317

내보내기 도구

Collector 구성에는 다음 내보내기 도구가 포함됩니다.

  • 로그 및 trace용 googlecloud 내보내기 도구. 이 내보내기 도구는 기본 로그 이름으로 구성됩니다.

  • 측정항목용 googlemanagedprometheus 내보내기 도구. 이 내보내기 도구에는 구성이 필요하지 않지만 구성 옵션이 있습니다. googlemanagedprometheus 내보내기 도구의 구성 옵션에 대한 자세한 내용은 Google Cloud Managed Service for Prometheus 문서의 OpenTelemetry Collector 시작하기를 참조하세요.

프로세서

Collector 구성에는 다음 프로세서가 포함됩니다.

  • batch: 요청당 Google Cloud 최대 항목 수 또는 Google Cloud 최소 간격인 5초마다(둘 중 더 먼저 오는 값)에서 원격 분석 요청을 일괄 처리하도록 구성됩니다.

  • memory_limiter: 한도를 초과하면 데이터 포인트를 삭제하여 메모리 부족 비정상 종료가 방지되도록 Collector의 메모리 사용량을 제한합니다.

  • resourcedetection: project_id와 같은 Google Cloud 리소스 라벨을 자동으로 감지합니다.

수신자

Collector 구성에는 otlp 수신자만 포함됩니다. 애플리케이션을 계측하여 OTLP trace 및 측정항목을 Collector의 OTLP 엔드포인트로 전송하는 방법에 대한 자세한 내용은 계측 방법 선택을 참조하세요.

사용 가능한 구성요소

Google 기반의 OpenTelemetry Collector에는 대부분의 사용자가 Google Cloud Observability 내에서 풍부한 환경을 사용 설정하는 데 필요한 구성요소가 포함되어 있습니다. 사용 가능한 구성요소의 전체 목록은 opentelemetry-operations-collector 저장소의 구성요소를 참조하세요.

사용 가능한 구성요소의 변경 또는 추가를 요청하려면 opentelemetry-operations-collector 저장소에서 기능 요청을 여세요.

원격 분석 생성

원격 분석을 생성하려면 사이드카 Collector가 있는 Cloud Run 애플리케이션을 만듭니다. OpenTelemetry 사이드카를 사용하여 OTLP 측정항목 작성 문서에서는 Google 기반의 OpenTelemetry Collector를 사이드카로 사용하는 방법에 대한 튜토리얼을 제공합니다. 이 튜토리얼을 사용하여 Google 기반의 Collector로 원격 분석을 생성할 수 있습니다.

원격 분석 보기

Google 기반의 OpenTelemetry Collector는 계측된 애플리케이션의 측정항목, 로그, trace를 Google Cloud Observability로 전송합니다. Collector는 자체 모니터링 가능성 측정항목도 전송합니다. 다음 섹션에서는 이 원격 분석을 보는 방법을 설명합니다.

측정항목 보기

Google 기반의 OpenTelemetry Collector는 측정항목 탐색기를 사용하여 볼 수 있는 Prometheus 측정항목을 수집합니다. 수집되는 측정항목은 앱의 계측에 따라 달라지지만 Google 기반의 Collector는 자체 측정항목도 작성합니다.

Google 기반의 OpenTelemetry Collector에서 수집한 측정항목을 보려면 다음을 수행합니다.

  1. Google Cloud 콘솔에서  측정항목 탐색기 페이지로 이동합니다.

    측정항목 탐색기로 이동

    검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Monitoring인 결과를 선택합니다.

  2. Google Cloud 콘솔의 툴바에서 Google Cloud 프로젝트를 선택합니다. App Hub 구성의 경우 App Hub 호스트 프로젝트나 앱 지원 폴더의 관리 프로젝트를 선택합니다.
  3. 측정항목 요소에서 측정항목 선택 메뉴를 펼치고 필터 표시줄에 Prometheus Target을 입력한 후 하위 메뉴를 사용하여 특정 리소스 유형과 측정항목을 선택합니다.
    1. 활성 리소스 메뉴에서 Prometheus 대상을 선택합니다.
    2. 측정항목을 선택하려면 활성 측정항목 카테고리 및 활성 측정항목 메뉴를 사용합니다. Google 기반의 OpenTelemetry Collector에서 수집한 측정항목에는 prometheus.googleapis.com 프리픽스가 있습니다.
    3. 적용을 클릭합니다.
  4. 데이터를 보는 방법을 구성합니다.

    측정항목의 측정값이 누적되면 측정항목 탐색기는 측정된 데이터를 정렬 기간에 따라 자동으로 정규화하므로 차트에 비율이 표시됩니다. 자세한 내용은 종류, 유형, 변환을 참조하세요.

    counter 측정항목과 같이 정수 값 또는 Double 값이 측정되면 측정항목 탐색기가 모든 시계열을 자동으로 합산합니다. 이 동작을 변경하려면 집계 항목의 첫 번째 메뉴를 없음으로 설정합니다.

    차트 구성에 대한 자세한 내용은 측정항목 탐색기 사용 시 측정항목 선택을 참조하세요.

trace 보기

trace 데이터를 보려면 다음을 수행합니다.

  1. Google Cloud 콘솔에서 Trace 탐색기 페이지로 이동합니다.

    Trace 탐색기로 이동

    검색창을 사용하여 이 페이지를 찾을 수도 있습니다.

  2. Google Cloud 콘솔의 툴바에서 Google Cloud 프로젝트를 선택합니다. App Hub 구성의 경우 App Hub 호스트 프로젝트 또는 앱 지원 폴더의 관리 프로젝트를 선택합니다.
  3. 페이지의 테이블 섹션에서 행을 선택합니다.

  4. trace 세부정보 패널의 Gantt 차트에서 스팬을 선택합니다.

    trace 요청에 대한 정보가 표시된 패널이 열립니다. 이러한 세부정보에는 메서드, 상태 코드, 바이트 수, 호출자의 사용자 에이전트가 포함됩니다.

  5. 이 trace와 연결된 로그를 보려면 로그 및 이벤트 탭을 선택합니다.

    탭에는 개별 로그가 표시됩니다. 로그 항목의 세부정보를 보려면 로그 항목을 펼칩니다. 로그 보기를 클릭하고 로그 탐색기를 사용하여 로그를 볼 수도 있습니다.

Cloud Trace 탐색기 사용에 대한 자세한 내용은 trace 찾기 및 탐색을 참조하세요.

로그 보기

로그 탐색기에서 로그를 검사할 수 있으며 연결된 trace가 있는 경우 이를 볼 수도 있습니다.

  1. Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.

    로그 탐색기로 이동

    검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

  2. 계측된 앱에서 로그 항목을 찾습니다. 세부정보를 보려면 로그 항목을 펼칩니다.

  3. trace 메시지가 있는 로그 항목에서 Traces를 클릭한 후 trace 세부정보 보기를 선택합니다.

    trace 세부정보 패널이 열리고 선택한 trace가 표시됩니다.

로그 탐색기 사용에 대한 자세한 내용은 로그 탐색기를 사용하여 로그 보기를 참조하세요.

Collector 관찰 및 디버그

Google 기반의 OpenTelemetry Collector는 성능을 모니터링하고 OTLP 수집 파이프라인의 지속적인 업타임을 보장하는 데 도움이 되는 자체 모니터링 가능성 측정항목을 자동으로 제공합니다.

Collector를 모니터링하려면 Collector의 샘플 대시보드를 설치합니다. 이 대시보드는 업타임, 메모리 사용량, Google Cloud Observability에 대한 API 호출을 포함하여 Collector의 여러 측정항목에 대한 유용한 정보를 한번에 제공합니다.

대시보드를 설치하려면 다음을 수행합니다.

  1. Google Cloud 콘솔에서 대시보드 페이지로 이동합니다.

    대시보드로 이동

    검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Monitoring인 결과를 선택합니다.

  2. 대시보드 템플릿을 클릭합니다.
  3. OpenTelemetry Collector 대시보드를 검색합니다.
  4. (선택사항) 대시보드를 미리 보려면 대시보드를 선택합니다.

  5. 목록에 대시보드 추가를 클릭한 다음 대화상자를 완료합니다.

    이 대화상자에서 대시보드 이름을 선택하고 대시보드에 라벨을 추가할 수 있습니다.

대시보드 설치에 대한 자세한 내용은 대시보드 템플릿 설치를 참조하세요.