Compute Engine에 Google 기반의 OpenTelemetry Collector 배포

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

시작하기 전에

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

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

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Compute Engine 인스턴스 Compute Engine 인스턴스가 없는 경우 Compute Engine 인스턴스 만들기 및 시작의 안내를 따르세요.
gcloud 설치. gcloud 설치에 대한 자세한 내용은 gcloud CLI 설치를 참고하세요.

Collector 권한 구성

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

기본 서비스 계정 대신 사용자 관리 서비스 계정을 사용하려면 동일한 역할을 할당해야 합니다. 자세한 내용은 서비스 계정을 참조하세요.

수집기 설치

Google 기반 OpenTelemetry Collector를 Compute Engine 인스턴스의 패키지로 설치하려면 다음 단계를 완료하세요.

Debian 및 Ubuntu

SSH 또는 유사한 도구를 사용하여 VM 인스턴스와의 터미널 연결을 열고 sudo 액세스 권한이 있는지 확인합니다.

다음 명령어를 실행하여 패키지 저장소를 설정합니다.

sudo mkdir -p /etc/apt/keyrings
sudo curl -o /etc/apt/keyrings/otelcol-google.asc https://packages.cloud.google.com/apt/doc/apt-key.gpg
cat <<EOF | sudo tee /etc/apt/sources.list.d/otelcol-google.list
deb [signed-by=/etc/apt/keyrings/otelcol-google.asc] https://us-apt.pkg.dev/projects/cloud-ops-agents-artifacts google-cloud-opentelemetry-collector-apt main
EOF

패키지 관리자를 새로고침하고 패키지를 설치합니다.
```
sudo apt update
sudo apt install otelcol-google
```
설치 후 Google 기반 OpenTelemetry Collector가 자동으로 시작됩니다.

CentOS, RHEL, Rocky Linux

SSH 또는 유사한 도구를 사용하여 VM 인스턴스와의 터미널 연결을 열고 sudo 액세스 권한이 있는지 확인합니다.

다음 명령어를 실행하여 패키지 저장소를 설정합니다.

cat <<EOF | sudo tee /etc/yum.repos.d/otelcol-google.repo
[otelcol-google]
name=Google Built OpenTelemetry Collector
baseurl=https://us-yum.pkg.dev/projects/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector-yum
autorefresh=0
enabled=1
type=rpm-md
gpgcheck=1
repo_gpgcheck=0
gpgkey=http://dl.google.com/linux/linux_signing_key.pub
EOF

패키지를 설치합니다.
```
sudo yum install otelcol-google
```
설치 후 Google 기반 OpenTelemetry Collector가 자동으로 시작됩니다.

SLES

SSH 또는 유사한 도구를 사용하여 VM 인스턴스와의 터미널 연결을 열고 sudo 액세스 권한이 있는지 확인합니다.

다음 명령어를 실행하여 패키지 저장소를 설정합니다.

cat <<EOF | sudo tee /etc/zypp/repos.d/otelcol-google.repo
[otelcol-google]
name=Google Built OpenTelemetry Collector
baseurl=https://us-yum.pkg.dev/projects/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector-yum
autorefresh=0
enabled=1
type=rpm-md
gpgkey=http://dl.google.com/linux/linux_signing_key.pub
EOF

패키지를 설치합니다.
```
sudo zypper install otelcol-google
```
설치 후 Google 기반 OpenTelemetry Collector가 자동으로 시작됩니다.

Windows

RDP 또는 유사한 도구를 사용하여 인스턴스에 연결하고 Windows에 로그인합니다.
PowerShell 아이콘을 마우스 오른쪽 버튼으로 클릭하고 관리자 권한으로 실행을 선택하여 관리자 권한이 있는 PowerShell 터미널을 엽니다.

다음 PowerShell 명령어를 실행하여 패키지 저장소를 설정합니다.

googet addrepo otelcol-google `
    https://us-googet.pkg.dev/projects/cloud-ops-agents-artifacts/repos/google-cloud-opentelemetry-collector-googet

패키지를 설치합니다.
```
googet install otelcol-google
```
설치 후 Google 기반 OpenTelemetry Collector가 자동으로 시작됩니다.

Collector 배포

Google 기반의 OpenTelemetry Collector에는 원격 분석을 내보내지 않는 최소 구성이 기본적으로 포함되어 있습니다. 원격 분석을 내보내려면 수집기를 설치한 후 기본 구성을 재정의하여 수집기를 구성합니다. Collector 구성을 다음 파일에 입력합니다.

Linux: /etc/otelcol-google/config.yaml
Windows: C:\Program Files\Google\OpenTelemetry Collector\config.yaml

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: http://localhost:4317
                insecure: true

내보내기 도구

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 저장소에서 기능 요청을 여세요.

원격 분석 생성

오픈소스 telemetrygen 도구를 사용하여 구성을 테스트할 수 있습니다. 도구를 다운로드하고 실행하는 방법은 링크에 포함되어 있습니다. 이 도구를 실행하려면 Go 또는 Docker를 설치해야 합니다.

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

원격 분석 보기

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

측정항목 보기

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

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

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

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Monitoring인 결과를 선택합니다.
Google Cloud 콘솔의 툴바에서 Google Cloud 프로젝트를 선택합니다. App Hub 구성의 경우 App Hub 호스트 프로젝트나 앱 지원 폴더의 관리 프로젝트를 선택합니다.
측정항목 요소에서 측정항목 선택 메뉴를 펼치고 필터 표시줄에 Prometheus Target을 입력한 후 하위 메뉴를 사용하여 특정 리소스 유형과 측정항목을 선택합니다.
1. 활성 리소스 메뉴에서 Prometheus 대상을 선택합니다.
2. 측정항목을 선택하려면 활성 측정항목 카테고리 및 활성 측정항목 메뉴를 사용합니다. Google 기반의 OpenTelemetry Collector에서 수집한 측정항목에는 prometheus.googleapis.com 프리픽스가 있습니다.
3. 적용을 클릭합니다.
쿼리 결과에서 시계열을 삭제하는 필터를 추가하려면 필터 요소를 사용합니다.
데이터를 보는 방법을 구성합니다.
측정항목의 측정값이 누적되면 측정항목 탐색기는 측정된 데이터를 정렬 기간에 따라 자동으로 정규화하므로 차트에 비율이 표시됩니다. 자세한 내용은 종류, 유형, 변환을 참조하세요.

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

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

trace 보기

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

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

검색창을 사용하여 이 페이지를 찾을 수도 있습니다.
Google Cloud 콘솔의 툴바에서 Google Cloud 프로젝트를 선택합니다. App Hub 구성의 경우 App Hub 호스트 프로젝트 또는 관리 프로젝트를 선택합니다.
페이지의 테이블 섹션에서 행을 선택합니다.
trace 세부정보 패널의 Gantt 차트에서 스팬을 선택합니다.

trace 요청에 대한 정보가 표시된 패널이 열립니다. 이러한 세부정보에는 메서드, 상태 코드, 바이트 수, 호출자의 사용자 에이전트가 포함됩니다.
이 trace와 연결된 로그를 보려면 로그 및 이벤트 탭을 선택합니다.

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

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

로그 보기

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

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

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.
계측된 앱에서 로그 항목을 찾습니다. 세부정보를 보려면 로그 항목을 펼칩니다.
trace 메시지가 있는 로그 항목에서 Traces를 클릭한 후 trace 세부정보 보기를 선택합니다.

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

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

Collector 관찰 및 디버그

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

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

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

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

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Monitoring인 결과를 선택합니다.
대시보드 템플릿을 클릭합니다.
OpenTelemetry Collector 대시보드를 검색합니다.
(선택사항) 대시보드를 미리 보려면 대시보드를 선택합니다.
목록에 대시보드 추가를 클릭한 다음 대화상자를 완료합니다.

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

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

Compute Engine에 Google 기반의 OpenTelemetry Collector 배포 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

Collector 권한 구성

수집기 설치

Debian 및 Ubuntu

CentOS, RHEL, Rocky Linux

SLES

Windows

Collector 배포

Collector 구성

제공된 Collector 구성

내보내기 도구

프로세서

수신자

사용 가능한 구성요소

원격 분석 생성

원격 분석 보기

측정항목 보기

trace 보기

로그 보기

Collector 관찰 및 디버그

Compute Engine에 Google 기반의 OpenTelemetry Collector 배포