1. Opentelemetry Collector

Openteletry Collector는 구조적으로 수집(Receivers), 처리(Processors), **전송(Exporters)**이라는 세 가지 파트로 구성되지만, 우리 모니터링 시스템에서는 이 중에서도 “수집기(Receiver)” 역할이 가장 핵심적입니다. 특히 서버와 플랫폼에서 발생하는 리소스 데이터를 정확하게 가져오는 기능이 Collector의 중심 역할이라고 할 수 있습니다.

참조: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/dockerstatsreceiver https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver

이때 가장 중요한 구성 요소가 hostmetrics 리시버입니다. hostmetrics는 호스트 수준에서 얻을 수 있는 운영체제 레벨의 리소스 지표를 주기적으로 읽어 들이는 수집기로, 다음과 같은 핵심 메트릭을 제공합니다.

• CPU 사용률, 코어별 사용량
• 메모리 사용량 및 사용 가능한 메모리
• 디스크 사용량, 디스크 I/O
• 파일시스템의 용량 및 상태
• 네트워크 송수신 패킷, 트래픽량
• Load Average 등 시스템 부하 지표

즉, 서버 전체의 상태를 파악하는 데 필요한 기본 운영 정보는 대부분 hostmetrics로부터 얻을 수 있습니다.

또한 Collector는 단순히 호스트 리소스만 수집하는 도구가 아니라, 다양한 실행 환경에서 발생하는 데이터를 동일한 방식으로 수집할 수 있는 확장성을 제공합니다. 예를 들어:

• kubeletstats 리시버: Kubernetes 환경에서 Pod, Node, Container 단위의 리소스 메트릭을 수집
• docker_stats 리시버: Docker 컨테이너의 CPU·메모리·네트워크 사용량 수집
• kafka 리시버: Kafka 브로커 상태 및 큐 처리량 지표 수집
• aws 관련 리시버: EC2, ECS 등 클라우드 리소스 상태 수집
• elasticsearch 리시버: 클러스터 헬스 및 노드 상태 수집

이처럼 Opentelemetry Collector는 다양한 플랫폼과 시스템에서 발생하는 리소스 메트릭을 일관된 방식으로 받아들이는 수집 허브 역할을 하며, 우리 시스템에서는 특히 서버 및 플랫폼 기반 리소스 사용량 데이터를 안정적으로 가져오는 핵심 컴포넌트로 활용됩니다.

지금부터 주요 Receiver에 대해 설명하도록 하겠습니다.

1-1. Host Metrics Receiver 개요

Host Metrics Receiver는 Collector가 호스트 시스템의 리소스 상태를 직접 읽어 표준 OTel 메트릭으로 변환하는 구성 요소입니다. Collector를 **에이전트 모드(호스트 내부 설치)로 실행할 때 가장 효과적이며, CPU·메모리·디스크·네트워크 등 주요 시스템 정보를 다양한 운영체제에서 안정적으로 수집합니다.

또한 이 Receiver는 Host Entity Event(로그 기반 이벤트 데이터)를 생성할 수 있으나, 이 기능은 아직 실험적입니다.

1-2. 설정 예시

hostmetrics:
  collection_interval: 1m
  root_path: /host
  mute_process_exe_error: true
  mute_process_io_error: true
  mute_open_file_descriptors_error: true
  mute_process_name_error: true
  mute_process_user_error: true
  scrapers:
    cpu:
      metrics:
        system.cpu.utilization:
          enabled: true
        system.cpu.logical.count:
          enabled: true
        system.cpu.physical.count:
          enabled: true
        system.cpu.frequency:
          enabled: true
    disk:
    load:
    filesystem:
      metrics:
        system.filesystem.utilization:
          enabled: true
    memory:
      metrics:
        system.memory.utilization:
          enabled: true
        system.linux.memory.available:
          enabled: true
    network:
      metrics:
        system.network.conntrack.count:
          enabled: true
        system.network.conntrack.max:
          enabled: true
    paging:
      metrics:
        system.paging.utilization:
          enabled: true
    process:
      mute_process_all_errors: true
      mute_process_name_error: true
      mute_process_exe_error: true
      mute_process_io_error: true
      mute_process_user_error: true
      mute_process_cgroup_error: true
      metrics:
        process.open_file_descriptors:
          enabled: true
        process.context_switches:
          enabled: true
        process.cpu.utilization:
          enabled: true
        process.disk.operations:
          enabled: true
        process.memory.utilization:
          enabled: true
        process.paging.faults:
          enabled: true
        process.signals_pending:
          enabled: true
        process.threads:
          enabled: true

1-3. 기본 설정 구조

Host Metrics Receiver의 기본 구성 구조는 다음과 같습니다.

hostmetrics:
  collection_interval: <duration>  # 기본값: 1m
  initial_delay: <duration>        # 기본값: 1s
  root_path: <string>
  scrapers:
    <scraper-name>:
      metrics:
        <metric-name>:
          enabled: true/false

주요 옵션

• collection_interval: 메트릭 수집 주기입니다.
• initial_delay: Collector 시작 후 첫 수집까지의 지연 시간입니다.
• root_path: 호스트 파일시스템이 컨테이너 내부 다른 경로에 마운트된 경우 사용하는 옵션입니다.
• scrapers: 수집할 시스템 영역을 지정하는 옵션입니다.

1-4. 지원되는 Scraper 목록

1-5. Scraper 상세 옵션

1-5-1. disk

특정 디스크만 선택하여 수집하거나 제외할 수 있습니다.

disk:
  include:
    devices: ["sda", "nvme0n1"]
    match_type: strict

1-5-2. filesystem

파일 시스템을 디바이스, 파일시스템 타입, 마운트 지점 등으로 필터링할 수 있습니다.

filesystem:
  include_devices:
    devices: ["sda1"]
    match_type: regexp
  include_fs_types:
    fs_types: ["ext4"]
  include_mount_points:
    mount_points: ["/", "/data"]
  include_virtual_filesystems: false

1-5-3. load

Load Average를 CPU 개수로 나눌지 설정할 수 있습니다.

load:
  cpu_average: true

1-5-4. network

network:
  include:
    interfaces: ["eth0", "ens*"]
    match_type: regexp

1-5-5. process

권한 문제로 인해 오류가 발생할 수 있으므로 다양한 mute 옵션을 제공합니다.

process:
  include:
    names: ["java", "nginx"]
  mute_process_all_errors: true

지원되는 오류 mute 옵션은 다음과 같습니다.

• mute_process_name_error
• mute_process_exe_error
• mute_process_io_error
• mute_process_user_error
• mute_process_cgroup_error

1-6. 고급 설정

1-6-1. 특정 메트릭만 선택하여 수집

필요한 메트릭만 수집하려는 경우에는 Receiver 설정에서 모든 메트릭을 활성화한 뒤, Filter Processor를 사용해 필요한 항목만 남기는 방법을 권장합니다.

1-6-2. Scraper별로 다른 수집 주기 사용

Scraper를 여러 hostmetrics 인스턴스로 분리하여 서로 다른 수집 주기를 지정할 수 있습니다.

receivers:
  hostmetrics:
    collection_interval: 30s
    scrapers:
      cpu:
      memory:

  hostmetrics/disk:
    collection_interval: 1m
    scrapers:
      disk:
      filesystem:

1-7. 컨테이너 내부에서 호스트 메트릭 수집 (Linux 전용)

Collector가 컨테이너 내부에서 실행될 경우 기본적으로 컨테이너 파일시스템만 보입니다. 따라서 호스트 파일시스템을 바인드 마운트하고 root_path를 지정해야 호스트의 실제 메트릭을 수집할 수 있습니다.

1-7-1. 바인드 마운트 예시

호스트 루트 전체 마운트:

docker run -v /:/hostfs ...

특정 경로만 마운트:

docker run -v /proc:/hostfs/proc

1-7-2. root_path 설정

hostmetrics:
  root_path: /hostfs

여러 hostmetrics 인스턴스를 사용할 경우, 모든 인스턴스에서 동일한 root_path를 사용해야 합니다.

1-8. Resource Attributes 설정

Hostmetrics는 Resource Attributes를 자동으로 설정하지 않습니다. 필요한 경우 환경 변수로 명시적으로 지정해야 합니다.

export OTEL_RESOURCE_ATTRIBUTES="service.name=my-service,service.instance.id=xxxx"

1-9. Entity Events (실험적 기능)

Hostmetrics는 Host EntityState 이벤트를 로그 형태로 생성할 수 있습니다. 기본 주기는 5분이며, metadata_collection_interval 옵션으로 조정할 수 있습니다.

1-10. Docker Stats Receiver 개요

Docker Stats Receiver는 Collector가 Docker Daemon의 Container Stats API를 주기적으로 호출하여 컨테이너 리소스 사용량을 메트릭으로 수집하는 Receiver입니다.

이 Receiver는 다음과 같은 특징을 가집니다.

• 대상: 로컬 Docker Daemon (기본 docker.sock)

• 수집 범위:

  • CPU 사용률 및 코어별 사용량
  • 메모리 사용량
  • 네트워크 I/O (패킷, 에러 등)
  • Block I/O(blkio) 관련 통계
  • 컨테이너 재시작 횟수, Uptime 등

• 요구 사항: Docker API 버전 1.22 이상

• 지원 플랫폼: Linux (darwin, windows는 미지원)

Host Metrics Receiver가 “호스트 OS 전체”를 보여준다면, Docker Stats Receiver는 각 Docker 컨테이너 단위의 상세 리소스 사용량을 제공한다는 점에서 서로 보완적인 관계입니다.

1-11. Docker Stats Receiver 설정 예시

아래는 Docker Stats Receiver에서 주요 메트릭을 활성화한 설정 예시입니다.

docker_stats:
  endpoint: unix:///var/run/docker.sock # 기본값 (Linux)
  collection_interval: 1m               # 기본값 10s
  initial_delay: 1s                     # 기본값 1s
  timeout: 5s                           # 기본값 5s
  api_version: "1.25"                   # 기본값 "1.25"
  metrics:
    container.cpu.utilization:
      enabled: true
    container.cpu.limit:
      enabled: true
    container.cpu.shares:
      enabled: true
    container.cpu.throttling_data.periods:
      enabled: true
    container.cpu.usage.percpu:
      enabled: true
    container.cpu.usage.system:
      enabled: true
    container.restarts:
      enabled: true
    container.uptime:
      enabled: true
    container.network.io.usage.rx_errors:
      enabled: true
    container.network.io.usage.tx_errors:
      enabled: true
    container.network.io.usage.rx_packets:
      enabled: true
    container.network.io.usage.tx_packets:
      enabled: true
    container.blockio.io_merged_recursive:
      enabled: true
    container.blockio.io_queued_recursive:
      enabled: true
    container.blockio.io_service_time_recursive:
      enabled: true
    container.blockio.io_serviced_recursive:
      enabled: true
    container.blockio.io_time_recursive:
      enabled: true
    container.blockio.io_wait_time_recursive:
      enabled: true
    container.blockio.sectors_recursive:
      enabled: true
    container.blockio.io_service_bytes_recursive:
      enabled: true

1-12. Docker Stats 기본 설정 구조

Docker Stats Receiver의 기본 구조는 다음과 같습니다.

docker_stats:
  endpoint: <string>
  collection_interval: <duration>
  initial_delay: <duration>
  timeout: <duration>
  api_version: <string>
  container_labels_to_metric_labels:
    <container-label>: <metric-label>
  env_vars_to_metric_labels:
    <ENV_VAR_NAME>: <metric-label>
  excluded_images:
    - <string/regexp/glob>
  metrics:
    <metric-name>:
      enabled: true/false

주요 옵션

• endpoint

  • Docker Daemon에 접근하기 위한 주소입니다.
  • 기본값(Linux): unix:///var/run/docker.sock

• collection_interval

  • 컨테이너 메트릭 수집 주기입니다. (기본값: 10s)

• initial_delay

  • Receiver가 시작된 후 첫 수집까지 대기하는 시간입니다. (기본값: 1s)

• timeout

  • Docker API 요청 타임아웃입니다. (기본값: 5s)

• api_version

  • Docker Client API 버전입니다. (기본값: "1.25", 문자열로 입력해야 합니다.)

• container_labels_to_metric_labels

  • Docker 컨테이너의 label 값을 메트릭 라벨에 매핑합니다.

• env_vars_to_metric_labels

  • 컨테이너 환경 변수 값을 메트릭 라벨에 매핑합니다.

• excluded_images

  • 수집 대상에서 제외할 이미지 이름 패턴 목록입니다.

• metrics

  • 개별 메트릭 활성/비활성 설정입니다.

1-13. excluded_images 옵션

excluded_images는 특정 컨테이너 이미지를 모니터링 대상에서 제외하고 싶을 때 사용합니다. 문자열, 정규식, Glob, 부정(!) 패턴을 모두 지원합니다.

docker_stats:
  excluded_images:
    - undesired-container
    - /.*test.*/          # 정규식
    - another-*-container # glob 패턴
    - !important-*        # 부정 패턴

• 문자열: 정확한 이미지 이름 일치
• 정규식: /pattern/ 형식, 양쪽에 / 필요
• Glob: *, ?, [] 등이 포함된 단순 패턴
• 부정(!): !를 앞에 붙여 “일치하지 않는 것만 제외”라는 의미로 사용할 수 있습니다.

1-14. Docker Stats 메트릭 개요

대표적인 메트릭은 다음과 같습니다.

1-14-1. CPU 관련

1-14-2. 네트워크 관련

1-14-3. BlockIO 관련

ScraperV2부터 BlockIO 메트릭은 operation 속성을 사용하는 구조로 변경되었습니다.

이때, operation=read/write 와 같은 속성으로 읽기/쓰기 유형을 구분합니다.

1-14-4. 기타 컨테이너 상태

1-15 주의 사항

Docker Stats Receiver 를 도커로 기동 시, 아래와 같이 docker.sock 및 docker/containers 경로를 마운트 해줘야 합니다.

  opentelemetry-collector:
    image: otel/opentelemetry-collector-contrib:0.119.0
    container_name: opentelemetry-collector
    network_mode: host
    user: "0:0"
    command: [ "--config=/etc/Opentelemetry/otel.yaml" ]
    volumes:
      - ./etc/Opentelemetry:/etc/Opentelemetry
      - /:/host:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /var/lib/docker/containers:/var/lib/docker/containers:ro
    restart: always