Google Kubernetes Engine에 Google 기반의 OpenTelemetry Collector 배포

이 문서에서는 Google Kubernetes Engine에서 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

• Kubernetes 클러스터가 필요합니다. Kubernetes 클러스터가 없으면 GKE 빠른 시작 안내를 따릅니다.

• 다음 명령줄 도구:

  • gcloud
  • kubectl

  gcloud 및 kubectl 도구는 Google Cloud CLI의 일부입니다. 설치에 대한 자세한 내용은 Google Cloud CLI 구성요소 관리를 참조하세요. 설치한 gcloud CLI 구성요소를 보려면 다음 명령어를 실행하세요.

  gcloud components list
  

Collector 권한 구성

GKE 워크로드 아이덴티티를 사용 중지한 경우 이 섹션을 건너뛰어도 됩니다.

OpenTelemetry Collector의 kubernetes 서비스 계정에 원격 분석을 내보내는 데 필요한 권한이 있는지 확인하려면 관리자에게 OpenTelemetry Collector의 kubernetes 서비스 계정에 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

중요: 이러한 역할은 사용자 계정이 아닌 OpenTelemetry Collector의 kubernetes 서비스 계정에 부여해야 합니다. 올바른 주 구성원에게 역할을 부여하지 않으면 권한 오류가 발생할 수 있습니다.

• 모니터링 측정항목 작성자(roles/monitoring.metricWriter)
• Logging 로그 작성자(roles/logging.logWriter)
• Cloud Trace 에이전트(roles/cloudtrace.agent)

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

관리자는 커스텀 역할이나 다른 사전 정의된 역할을 통해 OpenTelemetry Collector의 kubernetes 서비스 계정에 필요한 권한을 부여할 수도 있습니다.

권한을 구성하려면 다음 add-iam-policy-binding 명령어를 사용합니다.

gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/logging.logWriter \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector
gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/monitoring.metricWriter \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector
gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/cloudtrace.agent \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector

명령어를 실행하기 전 다음 변수를 바꿉니다.

• PROJECT_ID: 프로젝트 식별자
• PROJECT_NUMBER: Google Cloud 프로젝트 번호

Collector 배포

Collector 파이프라인은 Self-Managed OTLP Kubernetes Ingestion 저장소에서 제공하는 검증된 예시에서 직접 배포할 수 있습니다. PROJECT_ID를 Google Cloud 프로젝트의 ID로 바꾼 후 다음 명령어를 사용하여 GitHub에서 직접 배포할 수 있습니다.

export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export PROJECT_NUMBER=PROJECT_NUMBER
kubectl kustomize https://github.com/GoogleCloudPlatform/otlp-k8s-ingest.git/k8s/base | envsubst | kubectl apply -f -

명령어를 실행하기 전 다음 변수를 바꿉니다.

• PROJECT_ID: 프로젝트 식별자
• PROJECT_NUMBER: 프로젝트의 숫자 식별자

Collector 구성

Google에서 빌드한 Collector와 함께 사용할 수 있는 OpenTelemetry Collector 구성이 제공됩니다. 이 구성은 일관된 GKE 및 Kubernetes 메타데이터가 연결된 대량의 OTLP 측정항목, 로그, trace를 전송하도록 설계되었습니다. 이 구성은 일반적인 수집 문제를 방지하도록 설계되었습니다. 구성을 추가할 수는 있지만 요소를 삭제하지 않는 것이 좋습니다.

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

제공된 Collector 구성

otlp-k8s-ingest 저장소에서 Kubernetes 환경의 Collector 구성을 찾을 수 있습니다.

# Copyright 2024 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

exporters:
  googlecloud:
    log:
      default_log_name: opentelemetry-collector
    user_agent: Google-Cloud-OTLP manifests:0.4.0 OpenTelemetry Collector Built By Google/0.128.0 (linux/amd64)
  googlemanagedprometheus:
    user_agent: Google-Cloud-OTLP manifests:0.4.0 OpenTelemetry Collector Built By Google/0.128.0 (linux/amd64)
  # The otlphttp exporter is used to send traces to Google Cloud Trace using OTLP http/proto
  # The otlp exporter could also be used to send them using OTLP grpc
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com
    # Use the googleclientauth extension to authenticate with Google credentials
    auth:
      authenticator: googleclientauth


extensions:
  health_check:
    endpoint: ${env:MY_POD_IP}:13133
  googleclientauth:


processors:
  filter/self-metrics:
    metrics:
      include:
        match_type: strict
        metric_names:
        - otelcol_process_uptime
        - otelcol_process_memory_rss
        - otelcol_grpc_io_client_completed_rpcs
        - otelcol_googlecloudmonitoring_point_count
  batch:
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  k8sattributes:
    extract:
      metadata:
      - k8s.namespace.name
      - k8s.deployment.name
      - k8s.statefulset.name
      - k8s.daemonset.name
      - k8s.cronjob.name
      - k8s.job.name
      - k8s.replicaset.name
      - k8s.node.name
      - k8s.pod.name
      - k8s.pod.uid
      - k8s.pod.start_time
    passthrough: false
    pod_association:
    - sources:
      - from: resource_attribute
        name: k8s.pod.ip
    - sources:
      - from: resource_attribute
        name: k8s.pod.uid
    - sources:
      - from: connection

  memory_limiter:
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  metricstransform/self-metrics:
    transforms:
    - action: update
      include: otelcol_process_uptime
      operations:
      - action: add_label
        new_label: version
        new_value: Google-Cloud-OTLP manifests:0.4.0 OpenTelemetry Collector Built By Google/0.128.0 (linux/amd64)

  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")

  # The relative ordering of statements between ReplicaSet & Deployment and Job & CronJob are important.
  # The ordering of these controllers is decided based on the k8s controller documentation available at
  # https://kubernetes.io/docs/concepts/workloads/controllers.
  # The relative ordering of the other controllers in this list is inconsequential since they directly
  # create pods.
  transform/aco-gke:
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["top_level_controller_type"], "ReplicaSet") where resource.attributes["k8s.replicaset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.replicaset.name"]) where resource.attributes["k8s.replicaset.name"] != nil
      - set(attributes["top_level_controller_type"], "Deployment") where resource.attributes["k8s.deployment.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.deployment.name"]) where resource.attributes["k8s.deployment.name"] != nil
      - set(attributes["top_level_controller_type"], "DaemonSet") where resource.attributes["k8s.daemonset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.daemonset.name"]) where resource.attributes["k8s.daemonset.name"] != nil
      - set(attributes["top_level_controller_type"], "StatefulSet") where resource.attributes["k8s.statefulset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.statefulset.name"]) where resource.attributes["k8s.statefulset.name"] != nil
      - set(attributes["top_level_controller_type"], "Job") where resource.attributes["k8s.job.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.job.name"]) where resource.attributes["k8s.job.name"] != nil
      - set(attributes["top_level_controller_type"], "CronJob") where resource.attributes["k8s.cronjob.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.cronjob.name"]) where resource.attributes["k8s.cronjob.name"] != nil

  # When sending telemetry to the GCP OTLP endpoint, the gcp.project_id resource attribute is required to be set to your project ID.
  resource/gcp_project_id:
    attributes:
    - key: gcp.project_id
      # MAKE SURE YOU REPLACE THIS WITH YOUR PROJECT ID
      value: ${GOOGLE_CLOUD_PROJECT}
      action: insert
  # The metricstarttime processor is important to include if you are using the prometheus receiver to ensure the start time is set properly.
  # It is a no-op otherwise.
  metricstarttime:
    strategy: subtract_initial_point

receivers:
  # This collector is configured to accept OTLP metrics, logs, and traces, and is designed to receive OTLP from workloads running in the cluster.
  otlp:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:4317
      http:
        cors:
          allowed_origins:
          - http://*
          - https://*
        endpoint: ${env:MY_POD_IP}:4318
  otlp/self-metrics:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:14317

service:
  extensions:
  - health_check
  - googleclientauth
  pipelines:
    logs:
      exporters:
      - googlecloud
      processors:
      - k8sattributes
      - resourcedetection
      - memory_limiter
      - batch
      receivers:
      - otlp
    metrics/otlp:
      exporters:
      - googlemanagedprometheus
      processors:
      - k8sattributes
      - memory_limiter
      - metricstarttime
      - resourcedetection
      - transform/collision
      - transform/aco-gke
      - batch
      receivers:
      - otlp
    metrics/self-metrics:
      exporters:
      - googlemanagedprometheus
      processors:
      - filter/self-metrics
      - metricstransform/self-metrics
      - k8sattributes
      - memory_limiter
      - resourcedetection
      - batch
      receivers:
      - otlp/self-metrics
    traces:
      exporters:
      - otlphttp
      processors:
      - k8sattributes
      - memory_limiter
      - resource/gcp_project_id
      - resourcedetection
      - batch
      receivers:
      - otlp
  telemetry:
    logs:
      encoding: json
    metrics:
      readers:
      - periodic:
          exporter:
            otlp:
              protocol: grpc
              endpoint: ${env:MY_POD_IP}:14317

내보내기 도구

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

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

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

프로세서

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

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

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

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

• k8sattributes: Kubernetes 리소스 속성을 원격 분석 라벨에 자동으로 매핑합니다.

• transform: Google Cloud모니터링 리소스의 라벨과 충돌하는 측정항목 라벨의 이름을 바꿉니다.

수신자

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

사용 가능한 구성요소

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

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

원격 분석 생성

이 섹션에서는 샘플 애플리케이션을 배포하고 이 애플리케이션을 Collector의 OTLP 엔드포인트로 가리키며Google Cloud에서 원격 분석을 보는 방법을 설명합니다. 샘플 애플리케이션은 trace, 로그, 측정항목을 Collector로 내보내는 소형 생성기입니다.

이미 OpenTelemetry SDK로 계측된 애플리케이션이 있으면 애플리케이션을 대신 Collector 엔드포인트로 가리킬 수 있습니다.

샘플 애플리케이션을 배포하려면 다음 명령어를 실행합니다.

kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/main/sample/app.yaml

Collector 엔드포인트에서 OpenTelemetry SDK를 사용하는 기존 애플리케이션을 가리키려면 OTEL_EXPORTER_OTLP_ENDPOINT 환경 변수를 http://opentelemetry-collector.opentelemetry.svc.cluster.local:4317로 설정합니다.

몇 분 후 애플리케이션에서 생성된 원격 분석이 Collector를 통해 각 신호의 Google Cloud 콘솔로 전송되기 시작합니다.

원격 분석 보기

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. 목록에 대시보드 추가를 클릭한 다음 대화상자를 완료합니다.

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

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