Fluentd 입문: 로그 수집, 라우팅과 플러그인
Fluentd의 태그 매칭과 플러그인, 파일 버퍼를 설명합니다. HTTP 출력과 Forward의 재시도 및 수신 확인도 살펴봅니다.
Fluentd 설정 검사를 통과해도 로그가 엉뚱한 곳으로 갈 수 있습니다. Nginx 액세스 로그 전용 규칙 앞에 <match **>를 놓으면, 범위가 넓은 규칙이 해당 이벤트를 먼저 받습니다. 수신처를 바꿀 때는 주소와 규칙 순서를 함께 확인해야 합니다.
Fluentd는 CNCF 졸업 프로젝트이며, 주로 Ruby로 구현된 확장형 로그 수집기입니다. 이 글에서는 Nginx 로그가 입력에서 출력까지 흐르는 경로를 살펴보고, 파일 출력을 HTTP로 바꿀 때 확인할 조건을 설명합니다. 예시는 Fluentd 1.x와 수신처의 공식 문서를 바탕으로 작성했습니다. CNCF 프로젝트(영문) · Fluentd 소스 코드(영문)
먼저 알아둘 내용
- 태그로 경로를 고릅니다.
<source>가 이벤트를 내보내면 일치하는<filter>가 가공하고, 처음 일치한<match>가 출력 대상을 정합니다. - 플러그인의 요구 사항을 확인합니다. 외부 플러그인을 쓰려면 Fluentd와 Ruby 버전, 의존성, 대상 시스템의 호환성을 확인해야 합니다.
- 장애 중 쌓일 양을 계산합니다. 디스크에 데이터가 남아 있으면 파일 버퍼의 대기 청크를 재시작 후 복구할 수 있습니다. 장애가 길어지면 큐와 디스크의 여유가 줄어듭니다.
- 알고 있는 이벤트로 수신처를 검증합니다. 운영 경로를 바꾸기 전에 본문 형식, 필드 타입, 이벤트 시각, 재시도 동작을 확인합니다.
Nginx 액세스 로그를 태그로 라우팅하기
<source>
@type tail
path /var/log/nginx/access.log
pos_file /var/log/fluentd/nginx.pos
tag access.nginx
<parse>
@type nginx
</parse>
</source>
<filter access.nginx>
@type record_transformer
<record>
hostname "#{Socket.gethostname}"
env "production"
</record>
</filter>
<match access.**>
@type file
path /var/log/aggregated/nginx
</match>
입력은 Nginx 액세스 파일을 읽고 access.nginx 태그가 붙은 이벤트를 내보냅니다. 필터가 수집기의 호스트 이름과 환경 필드를 더하면 access.** 규칙이 파일로 보냅니다. 같은 라우팅 범위에서는 일치하는 필터를 순서대로 적용하고 처음 일치한 출력에서 경로가 결정됩니다. 구체적인 출력을 넓은 패턴보다 앞에 두고 필요한 필터는 해당 출력보다 앞에 배치합니다. 여러 수신처에 보낼 때는 out_copy 등으로 분기를 명시합니다. 설정과 매칭 순서(영문)
pos_file에는 입력이 읽은 위치가 기록됩니다. 이 상태가 유지되면 재시작 후 이어서 읽을 수 있습니다. 시작할 때 이미 존재하는 파일에 저장 위치가 없으면 기본적으로 끝에서부터 읽습니다. 기존 줄까지 읽으려면 read_from_head true를 설정합니다. tail 입력마다 위치 파일을 따로 쓰고, 서비스 계정에는 로그 읽기와 위치 파일 및 출력 디렉터리 쓰기 권한이 필요합니다. 수신처에 기록됐는지는 읽기 위치와 별도로 확인합니다. tail 입력(영문)
내장 nginx 파서는 로그에서 추출한 시각을 이벤트 시각으로 사용합니다. 실제 log_format이 파서 패턴과 다르면 형식에 맞춰 조정합니다. 파일 출력은 기본적으로 시간 구간별로 모아 쓰므로, 새로운 출력 파일이 바로 생기지 않을 수 있습니다. Nginx 파서(영문) · file 출력(영문)
입력, 필터, 출력에 맞는 플러그인 고르기
| 단계 | 주요 플러그인 |
|---|---|
| 입력 | in_tail은 파일을 읽고, in_http는 HTTP 요청을 받습니다. in_syslog는 UDP/TCP syslog를 받고, in_exec는 외부 명령의 출력을 읽습니다. |
| 필터 | record_transformer는 필드를 수정하고, grep은 패턴으로 레코드를 거릅니다. parser는 기존 레코드의 문자열 필드를 파싱하고, 외부 fluent-plugin-geoip는 IP 지리 정보를 보강합니다. |
| 출력 | out_file은 파일에 쓰고, out_http는 HTTP 요청으로 보냅니다. out_forward는 Forward로 전송하며, 외부 fluent-plugin-opensearch는 @type opensearch로 설정합니다. |
parser 필터에 도착하는 이벤트는 이미 나뉘어 있습니다. 여러 줄의 스택 트레이스가 한 이벤트여야 한다면 여러 줄을 조립할 수 있는 입력에서 처리합니다. 외부 플러그인은 Fluentd가 실제로 사용하는 Ruby 환경에 설치하고 의존성을 확인합니다. parser 필터(영문) · 플러그인 관리(영문) · GeoIP 플러그인(영문) · OpenSearch 플러그인(영문)
수신처 장애 때 버퍼가 감당할 수 있는 범위
같은 태그를 HTTP로 보내려면 앞의 파일 출력 블록을 아래 설정으로 교체합니다. 한 줄에 JSON 레코드 하나를 보내는 예시이며, json_array가 지원되는 Fluentd 1.10.4 이상이 필요합니다. 실제 수신처가 기대하는 본문 형식과 응답 동작에 맞춰야 합니다.
<match access.**>
@type http
endpoint https://logs.example.com/ingest
json_array false
retryable_response_codes [503]
<format>
@type json
</format>
<buffer>
@type file
path /var/log/fluentd/buffer/http
flush_mode interval
flush_interval 5s
total_limit_size 512m
overflow_action throw_exception
retry_max_interval 30s
retry_forever true
</buffer>
</match>
파일 버퍼는 아직 보내지 못한 청크를 디스크에 보관합니다. retry_forever는 재시도 가능한 실패에 대해 시간과 횟수 제한을 해제합니다. 이 예시에서는 HTTP 503을 명시했고, 잘못된 본문 때문에 400이 온다면 보통 형식을 먼저 고쳐야 합니다. 디스크가 유지되면 재시작 후 청크를 복구할 수 있지만, 장애가 계속되면 큐가 찹니다. 512m은 이 버퍼 인스턴스의 한도입니다. 입력 속도와 큐 한도도 적체 가능 시간을 좌우하며 파일 시스템 공간은 따로 확보해야 합니다. HTTP 출력(영문) · 버퍼 설정(영문)
out_forward는 가중치에 따라 여러 수신 노드로 분산하고 장애 시 다른 노드로 보낼 수 있습니다. 복제가 필요하면 별도 분기를 설정합니다. 기본값은 ACK를 기다리지 않습니다. require_ack_response true를 켜면 대상 in_forward의 확인 응답을 기다려 해당 구간에서 최소 한 번 전송 방식을 사용합니다. 청크는 수신됐지만 ACK가 유실되면 다시 보내면서 중복이 생길 수 있습니다. 이후 저장이나 인덱싱 여부는 따로 확인해야 합니다. Forward 출력(영문)
Fluent Bit를 어디에 배치할까
특정 플러그인과 변환 규칙이 필요한 파이프라인에는 Fluentd를 고려할 수 있습니다. Fluent Bit는 자원이 제한된 곳에서도 수집할 수 있도록 설계됐으며 Kubernetes에서 DaemonSet으로 실행할 수 있습니다. 각 노드의 Fluent Bit가 Forward로 Fluentd 집계 계층에 보내는 구성도 가능합니다. 노드에서 필요한 가공과 출력이 가능하다면 곧바로 목적지로 보낼 수 있습니다. 플러그인, 버퍼, 입력량을 맞춘 상태에서 실제 CPU와 메모리 사용량을 비교합니다. Fluent Bit 공식 비교(영문) · Forward 상호 운용(영문)
기존 Fluentd 로그를 새 수신처로 보내기
입력과 필터를 유지한 채 출력 계약부터 확인합니다. Guance DataKit의 Log Streaming 수집기는 /v1/write/logstreaming에서 로그를 받습니다. 배포 방식에 맞춰 수집기를 활성화하고, Fluentd HTTP 출력을 접근 가능한 주소로 설정합니다. URL에는 예를 들어 ?source=nginx&service=web을 붙입니다. 기본 텍스트 모드에는 json_array false로 줄 단위 JSON을 보낼 수 있습니다. JSON 키를 필드로 쓰려면 Pipeline이나 수집기 설정의 json_as_fields를 사용합니다. type=influxdb에는 InfluxDB 라인 프로토콜이 필요합니다. DataKit Log Streaming(영문)
식별자가 정해진 샘플 이벤트를 사용해 양쪽에서 조회되는 결과를 비교합니다. 태그와 이벤트 시각은 레코드와 별도이므로 일반 JSON으로 보낼 때 보존할 값을 필드로 명시하고 수신처 규칙에 맞춰 매핑합니다. 이벤트 시각, 여러 줄 로그, 필드 타입, 중복 처리 기준을 확인합니다. 격리된 환경에서 수신이 잠시 끊겼을 때 적체가 늘어나는지, 복구 후 비워지는지, 재전송이 중복을 만드는지 살펴본 뒤 운영 경로를 바꿉니다.
자주 묻는 질문
태그와 레코드 필드는 어떻게 다른가요?
태그는 라우팅에 쓰이는 메타데이터이며 필드는 레코드의 내용입니다. JSON 필드를 읽는 수신처에서 태그로 검색하려면 record_transformer로 ${tag}를 별도 필드에 넣습니다. record_transformer(영문)
버퍼 디렉터리가 가득 차면 어떻게 되나요?
설정한 버퍼 한도에 도달하는 경우와 파일 시스템에 쓰기 공간이 없는 경우를 구분합니다. overflow_action에는 예외를 내는 throw_exception, 대기하는 block, 가장 오래된 청크를 버리는 drop_oldest_chunk가 있습니다. 디스크 용량은 별도로 관리해야 합니다. in_tail이 BufferOverflowError를 받으면 읽기와 위치 파일 갱신을 멈췄다가 오류가 해소되면 재개합니다. 그동안 로테이션된 파일이 삭제되면 읽지 못한 로그를 잃을 수 있습니다. 버퍼 한도(영문) · tail 버퍼 초과 동작(영문)
Fluentd의 처리량을 제한하는 요소는 무엇인가요?
파싱과 필터에 드는 CPU, 버퍼 디스크 I/O, 네트워크, 수신처가 청크를 받아들이는 속도를 나누어 봅니다. 인스턴스 하나의 처리 한도는 구성에 따라 달라집니다. 플러그인이 지원하면 워커를 늘리거나 여러 인스턴스로 입력을 나눌 수 있습니다. 이벤트 크기, 파싱 규칙, 부하와 ACK 조건을 같게 두고 비교합니다. 멀티 워커(영문)
설정 변경은 어떻게 적용하나요?
실행 환경에서 fluentd --dry-run -c fluent.conf로 설정과 플러그인 로딩을 확인합니다. Linux의 fluent-package는 일반적으로 /etc/fluent/fluentd.conf를 사용합니다. 이전 패키지 td-agent는 지원이 종료됐습니다. systemctl reload fluentd가 동작하려면 설치된 서비스 유닛에서 reload를 지원해야 합니다. Unix에서는 supervisor에 SIGHUP을 보내면 워커를 재시작하며 설정을 다시 읽습니다. 이때 메모리 버퍼를 내보내는 데 실패하면 재시도하지 않으므로 플러그인과 버퍼 동작을 먼저 확인합니다. 설정 경로(영문) · 명령 옵션(영문) · 시그널 동작(영문)
함께 읽기
- Vector 구성과 설정(중국어 간체)
- Fluent Bit의 구조와 사용법(중국어 간체)
- Fluentd와 Fluent Bit 비교(중국어 간체)
- 로그 수집기 선택 가이드(중국어 간체)
문서 확인일 2026년 11월 6일.
