Beats

학습 목표

Beats가 Elastic Stack에서 가벼운 수집기로 어떤 역할을 하는지 설명할 수 있다.

Filebeat로 파일·컨테이너 로그를 읽어 Elasticsearch 또는 Logstash로 보낼 수 있다.

Metricbeat로 호스트·컨테이너 메트릭을 수집하는 패턴을 설명할 수 있다.

module이 input·파싱·필드·대시보드를 묶어 주는 방식을 설명할 수 있다.

output.elasticsearch vs output.logstash 선택 기준을 말할 수 있다.

문제 상황

• 앱 로그는 /var/log에 쌓이는데 중앙 검색은 Elasticsearch — 누가 파일을 읽어 보내는지 모름
• tail -f + curl로 ES에 넣다가 재시작 시 로그 유실 — 읽은 위치 registry 없음
• Nginx access log grok을 매번 손으로 짜다 필드명이 팀마다 다름 — module 미사용
• Pod마다 Filebeat 깔았더니 CPU·메모리도 보고 싶다 — Metricbeat module 별도
• Filebeat가 ES에 직접 넣는데 파싱 실패 document가 index에 섞임 — processor·pipeline 분리 필요
• Logstash 없이 가볍게 시작하고 싶은데, 나중에 복잡한 transform이 생김 — output 경로 설계 필요
• 2~5편에서 index·mapping·query는 봤지만 document가 호스트에서 어떻게 들어오는지는 비어 있음

앞 편에서 Elasticsearch 저장·검색·집계를 봤다. 이번 편은 Beats로 source에서 ES(또는 Logstash)까지 수집. Logstash·ingest pipeline 심화는 7·8편, data stream은 9편이다.

1. Beats란?

Beats — 서버·컨테이너·네트워크 장비에서 데이터를 가볍게 뽑아 Elastic Stack으로 보내는 단일 목적 에이전트 모음.

Beat	수집 대상	흔한 용도
Filebeat	파일·stdin·container log	앱·Nginx·syslog 로그
Metricbeat	메트릭 (CPU·disk·HTTP check)	호스트·K8s·서비스 헬스
Packetbeat	네트워크 패킷	L7 프로토콜 분석
Auditbeat	감사·무결성	보안·컴플라이언스
Heartbeat	uptime·TCP/HTTP ping	가용성 모니터링

• Elastic Agent — Beats·Fleet·integration을 하나의 에이전트로 통합 (19편 Fleet)
• Beats는 독립 바이너리 — Agent 도입 전·소규모·단일 목적에 여전히 많이 씀
• 공통 구조 — input → processor → output; 상태는 registry(Filebeat) 등에 저장

Host / Pod
  Filebeat  ──► log lines as documents
  Metricbeat ──► metric documents
        │
        ▼
  Elasticsearch  (또는 Logstash → ES)

2. Filebeat

파일 끝을 따라가며 새 줄을 읽어 document로 만든다.

# code/filebeat.example.yml (발췌)
filebeat.inputs:
  - type: log
    paths:
      - /var/log/order-api/*.json
    json.keys_under_root: true
    fields:
      service: order-api
    fields_under_root: true

개념	역할
input	어떤 경로·형식을 읽을지
harvester	파일 하나당 읽기 루프 (open → read → send)
registry	파일 inode·offset 저장 — 재시작 후 이어 읽기
prospector (구) / input	어떤 파일을 감시할지

• json.keys_under_root — JSON 로그 한 줄을 필드로 펼침 (2편 document 모델)
• fields — service, env 등 공통 태그 부여
• multiline — 스택 트레이스를 한 document로 합침 (7편 Logstash와 역할 분담)
• container input — Docker·K8s stdout 경로 수집
• 읽은 document는 bulk로 output에 전송 — 5편 routing으로 shard에 분산

registry가 중요한 이유

없을 때	registry 있을 때
재시작 시 처음부터 또는 끝만	마지막 offset부터
로테이션 후 중복·누락	inode·path 추적으로 안정
수동 offset 관리	Filebeat가 상태 파일 유지

• registry 경로 — filebeat.registry (data path 하위)
• 삭제하면 전체 재전송 — 디스크·중복 document 주의

3. Metricbeat

주기적으로 metricset을 수집해 document로 보낸다.

# code/metricbeat.example.yml (발췌)
metricbeat.modules:
  - module: system
    period: 10s
    metricsets:
      - cpu
      - memory
      - network

개념	설명
module	수집 대상 종류 (system, docker, nginx, …)
metricset	module 안 지표 묶음 (cpu, memory, …)
period	수집 주기
hosts	대상 주소 (예: Docker socket)

• document 예 — metricset.name: cpu, system.cpu.total.pct
• 로그(Filebeat)와 같은 index에 넣지 않는 경우가 많음 — metrics-* index 분리
• Kibana Metrics UI·대시보드와 연동 — 10~11편
• Prometheus가 있는 환경 — Metricbeat vs Prometheus exporter 역할 중복 검토 (Observability 시리즈)

4. Module

module — 특정 소프트웨어용 input·변수·ingest pipeline·필드·대시보드 번들.

# code/nginx-module.example.yml (발췌)
- module: nginx
  access:
    enabled: true
    var.paths: ["/var/log/nginx/access.log*"]

layer	제공
fileset	access / error 등 하위 단위
var	경로·포트 등 사용자 변수
ingest pipeline	ES에 자동 등록되는 파싱 (8편)
index template	필드 mapping 힌트 (3편)
Kibana	대시보드 import

filebeat modules enable nginx
filebeat setup   # pipeline · template · dashboard (권한 필요)

• 직접 grok 대신 module — 표준 필드명 (url.path, http.response.status_code)
• filebeat setup — ES·Kibana에 부가 객체 생성 — prod는 IaC·Git으로 관리 권장
• module 없는 커스텀 JSON 로그 — input + processor만으로 충분한 경우 많음

5. Output — Elasticsearch vs Logstash

output	적합
elasticsearch	JSON 로그 그대로·ingest pipeline(8편)·단순 파이프라인
logstash	복잡 grok·외부 enrich·여러 sink 버퍼
kafka	버퍼·재처리·다중 consumer (대규모)
console	로컬 디버그

# ES 직접
output.elasticsearch:
  hosts: ["https://es.example.com:9243"]
  index: "logs-order-prod-%{+yyyy.MM.dd}"
  api_key: "${ES_API_KEY}"

# Logstash 경유
output.logstash:
  hosts: ["logstash.internal:5044"]

	ES 직접	Logstash 경유
구성	Beat + ES	Beat + LS + ES
파싱	Beat processor + ingest pipeline	Logstash filter
부하	호스트에 Beat만	LS 중앙 집약
장애	ES down 시 Beat backoff	LS가 버퍼 가능

• Elastic Cloud — HTTPS + API key·deployment endpoint (16편)
• index 이름 — logs-%{+yyyy.MM.dd} 일별 vs data stream (9편)
• setup.ilm.enabled — 자동 ILM 정책 — prod는 13편 정책과 맞출지 결정

6. Processor

Beat 내부에서 document를 가공한다 (ingest pipeline 전 단계).

processor	용도
add_host_metadata	hostname·IP
add_cloud_metadata	AWS·GCP region 등
drop_event	noise 로그 제거
rename / convert	필드 정리
decode_json_fields	문자열 JSON 파싱

processors:
  - add_host_metadata: {}
  - drop_event:
      when:
        regexp:
          message: "^healthcheck ok$"

• ingest pipeline(8편)과 역할 분담
  • Beat — host·cloud 메타, 가벼운 drop
  • ingest — 공통 파싱·enrich (모든 Beat가 동일 규칙)
• 3편 mapping — processor로 넣은 필드도 타입 맞아야 검색·집계 가능

7. 실무 체크리스트

#	질문
1	Filebeat registry 볼륨이 Pod 재시작 후에도 유지되는가
2	JSON 로그는 한 줄 한 document인가, multiline 설정이 필요한가
3	module로 표준화할 수 있는 소스(Nginx, system)인가
4	output이 ES 직접인지 Logstash인지 팀에 문서화됐는가
5	index·data stream 이름과 ILM이 13편 정책과 맞는가
6	service·env 공통 필드가 4·5편 쿼리·집계에 쓰이는가

정리

• Beats — Filebeat(로그)·Metricbeat(메트릭) 등 가벼운 shipper
• Filebeat — harvester + registry로 파일 안정 수집
• module — 파싱·mapping·대시보드 번들
• output — ES 직접 vs Logstash — 파싱 복잡도로 선택
• processor — 호스트 메타·노이즈 제거; 공통 파싱은 ingest pipeline

다음에 다룰 것

• Logstash
• input·filter·output, grok, multiline, codec

---

해당 내용은 Elastic Beats Reference (Filebeat, Metricbeat, Modules) 를 기반으로 합니다.