Grafana Agent를 활용한 데이터 수집 파이프라인 구축 가이드

Grafana Agent는 지표(Metrics), 로그(Logs), 트레이스(Traces)를 효율적으로 수집, 가공 및 라우팅하는 경량화된 에이전트입니다. River 구성 언어를 통해 데이터 흐름을 선언적으로 정의하며, Docker 컨테이너를 통해 빠르게 배포하고 검증할 수 있습니다.

시스템 아키텍처 및 주요 특징

최적화된 리소스 사용량: 단일 바이너리로 동작하며, 메모리 및 CPU 프로파일이 경량화되어 에지 서버부터 클라우드 환경까지 유연하게 배포 가능합니다.
통합 신호 처리: 단일 구성 파일에서 메트릭, 로그, 트레이스를 병렬로 관리하며 데이터 타입 간 상호 참조가 지원됩니다.
컴포넌트 기반 파이프라인: 각 처리 단위를 독립적인 노드로 분리하여, 의존성 그래프 기반의 실시간 상태 모니터링이 가능합니다.
내장 진단 인터페이스: HTTP 서버를 활성화하면 구성 구문 검증, 컴포넌트 실행 상태, 데이터 전파 경로를 시각적으로 확인할 수 있습니다.

환경 준비 및 컨테이너 실행

실습 환경에는 Docker 런타임이 사전 설치되어 있어야 합니다. 에이전트의 Flow 모드를 활성화하여 선언형 구성을 로드합니다.

기본 구성 파일 정의

작업 디렉토리에 flow_config.river를 생성하고 메트릭 수집 및 로컬 파일 출력을 설정합니다.

// 로깅 레벨 및 출력 형식 지정
logging {
  level  = "warn"
  format = "json"
}

// 타겟 엔드포인트 폴링 설정
prometheus.scrape "app_monitor" {
  targets = [
    { "__address__" = "localhost:9090" },
    { "__address__" = "host.docker.internal:8080" },
  ]
  forward_to = [prometheus.remote_write.file_sink.receiver]
}

// 로컬 파일 시스템으로 샘플 데이터 기록
prometheus.remote_write "file_sink" {
  endpoint {
    url = "file:///var/log/agent_data/metrics.json"
  }
}

Docker 컨테이너 구동

아래 명령어를 실행하여 구성 파일을 마운트하고 HTTP 관리 포트를 개방합니다.

docker run -d \
  --name agent-flow \
  -e AGENT_MODE=flow \
  -v "$(pwd)/flow_config.river:/config/pipeline.river" \
  -p 3311:3311 \
  -v "$(pwd)/output:/var/log/agent_data" \
  grafana/agent:latest \
  run --server.http.listen-addr="0.0.0.0:3311" /config/pipeline.river

http://localhost:3311에 접속하면 내장된 Flow UI가 렌더링되며, 정의된 컴포넌트들의 상태와 데이터 흐름 그래프가 실시간으로 표시됩니다.

컴포넌트 동작 원리

Flow 모드는 데이터를 처리하는 각 단위를 컴포넌트로 추상화합니다. 주요 구성 요소의 역할은 다음과 같습니다.

prometheus.scrape: 지정된 타겟 URL을 주기적으로 요청하여 Prometheus 형식의 메트릭을 추출합니다.
prometheus.remote_write: 스크래핑된 데이터를 원격 엔드포인트로 HTTPS 또는 파일 프로토콜을 통해 푸시합니다.
otelcol.receiver.otlp: OpenTelemetry 표준을 따르는 gRPC/HTTP 신호를 수신하는 진입점 역할을 합니다.
otelcol.processor.batch: 수신된 신호를 시간 또는 크기 기준으로 묶어 네트워크 부하를 완화하고 처리 효율을 높입니다.

OTLP 통합 처리 파이프라인 설계

다음 구성은 OTLP 프로토콜을 통해 유입된 신호를 타입별로 분기하여 각각의 백엔드로 전달하는 전체 흐름을 구현합니다.

// OTLP 신호 수신 설정
otelcol.receiver.otlp "primary_ingest" {
  grpc { endpoint = "0.0.0.0:4319" }
  http { endpoint = "0.0.0.0:4321" }

  output {
    metrics = [otelcol.processor.batch.queue_handler.input]
    logs    = [otelcol.processor.batch.queue_handler.input]
    traces  = [otelcol.processor.batch.queue_handler.input]
  }
}

// 배칭 및 처리 로직 정의
otelcol.processor.batch "queue_handler" {
  send_batch_size = 512
  timeout         = "10s"

  output {
    metrics = [otelcol.exporter.prometheus.p_backend.input]
    logs    = [otelcol.exporter.loki.l_backend.input]
    traces  = [otelcol.exporter.otlp.t_backend.input]
  }
}

// 메트릭 전송 엔드포인트
otelcol.exporter.prometheus "p_backend" {
  endpoint { url = "http://prometheus:9090/api/v1/write" }
}

// 로그 전송 엔드포인트
otelcol.exporter.loki "l_backend" {
  endpoint { url = "http://loki:3100/loki/api/v1/push" }
}

// 트레이스 전송 엔드포인트
otelcol.exporter.otlp "t_backend" {
  client { endpoint = "http://tempo:4317" }
}

수신된 데이터는 queue_handler를 거쳐 버퍼링된 후, 각 데이터 타입에 적합한 익스포터로 분기됩니다. 모든 컴포넌트는 input 및 output 필드를 통해 명시적으로 연결되며, UI 대시보드에서 의존성 체인을 검증할 수 있습니다.

운영 환경 고급 설정

프로덕션 배포 시에는 데이터 수집 소스의 다양화와 상태 저장소 경로를 체계적으로 관리해야 합니다.

다양한 수집 소스 연동: loki.source.file을 이용한 로그 파일 테일링, discovery.kubernetes를 통한 클러스터 노드/팟 자동 탐색, prometheus.exporter.node 기반 OS 레벨 메트릭 수집을 지원합니다.
상태 저장소 경로 분리: 에이전트는 실행 중 생성된 체크포인트, 캐시, 내부 상태를 유지하기 위해 로컬 디렉토리를 사용합니다. CLI 인수를 통해 영구 저장 볼륨을 매핑하면 데이터 유실을 방지할 수 있습니다.

grafana-agent run --storage.path=/mnt/persistent/agent-state flow_config.river

태그: grafana-agent river-config OpenTelemetry prometheus-scrape docker-containers

8월 28일 07:47에 게시됨

괴물 클럽