Fluent Bit 이해하기: Tail, 로그 파서, SQL 스트림 처리
Fluent Bit 입력·필터·출력 설정부터 로그 파서 등록, Kubernetes 메타데이터, Tail 오프셋과 윈도우 기반 SQL 작업까지 실제 동작과 한계를 설명합니다.
Fluent Bit는 Fluentd 생태계의 경량 로그·텔레메트리 처리기입니다. 주로 C로 구현됐으며 호스트, Kubernetes 노드, 엣지 환경에서 사용할 수 있습니다. 다만 경량 설계가 고정된 메모리 상한을 뜻하지는 않습니다. 파일 수, 파싱 작업, 메타데이터 캐시, 전송 대기 데이터에 따라 자원 사용량이 달라집니다. 의존성도 빌드와 플러그인에 영향을 받습니다.
이 글의 클래식 설정과 SQL 예시는 Fluent Bit 3.2 공식 문서를 기준으로 합니다. 3.2가 최신 권장 버전이라는 뜻은 아닙니다. 레코드를 읽고, 구조화하고, 전달하는 동작을 설정과 연결해 살펴봅니다.
먼저 알아둘 핵심
- 경량 수집기에도 자원 예산은 필요합니다. 노드마다 배포할 때는 로그 처리량, 파일 수, 필터, 적체의 영향을 고려해야 합니다.
- 설정은 처리 단계별로 나뉩니다.
[INPUT],[FILTER],[OUTPUT]이 수집·가공·전송을 담당합니다. YAML도 지원하지만 배포한 버전의 옵션을 확인해야 합니다. - Kubernetes 메타데이터 연결에는 조건이 있습니다. tag와 파일 이름으로 대상을 식별하고, 캐시나 API Server·Kubelet 접근을 통해 추가 정보를 가져옵니다.
1. 설정으로 레코드의 이동 경로 보기
다음 내용을 /etc/fluent-bit/fluent-bit.conf에 저장합니다. 참조하는 파서 파일은 3절에서 정의합니다. 디렉터리가 미리 준비돼 있어야 하며, 실행 계정은 설정과 로그를 읽고 /var/lib/fluent-bit/의 DB에 쓸 수 있어야 합니다.
[SERVICE]
Flush 1
Log_Level info
Parsers_File /etc/fluent-bit/parsers-app.conf
[INPUT]
Name tail
Path /var/log/app/*.log
Tag app.*
Parser app_json
DB /var/lib/fluent-bit/tail-app.db
Mem_Buf_Limit 10MB
Refresh_Interval 5
[FILTER]
Name record_modifier
Match app.*
Record hostname ${HOSTNAME}
Record env production
[OUTPUT]
Name http
Match app.*
Host logs.example.com
Port 443
URI /ingest
Format json
tls On
INPUT이 레코드를 읽고 tag를 붙이면 FILTER와 OUTPUT이 Match로 처리 대상을 선택합니다. Tail의 Tag app.*에서 *는 읽는 파일의 절대 경로로 확장되고 슬래시는 점으로 바뀝니다. 모든 파일에 같은 문자열 tag가 붙는 것은 아닙니다.
Refresh_Interval은 파일 탐색 간격이고, Flush는 엔진이 데이터를 플러시하는 주기입니다. 1초로 설정했다고 백엔드에 1초 안에 도착한다는 보장은 없습니다. ${HOSTNAME}도 실행 환경이 해당 변수를 제공해야 치환됩니다. Tail 설정(영문)
HTTP 출력의 목적지를 바꾸기 전에는 엔드포인트, 인증, 페이로드 형식, 응답 처리 방식을 알려진 샘플로 확인합니다. Host와 URI만 바꿨다고 이관이 끝나지는 않습니다. 위 예시는 메모리 버퍼를 사용하며 Mem_Buf_Limit에 도달하면 입력이 일시 정지할 수 있습니다. Tail DB는 파일 읽기 위치를 저장하는 것이지, 미전송 레코드의 영속 큐가 아닙니다. 버퍼링과 저장소(영문)
같은 파일을 Guance로 수집하려면 DataKit의 로그 수집기(영문)에서 접근 가능한 logfiles를 설정하고, 애플리케이션에 맞게 source, Pipeline, 이벤트 시간 처리를 구성하는 방법도 있습니다. 이는 별도의 수집 경로입니다. Fluent Bit의 Tail DB, 파서 정의, SQL 작업을 그대로 재사용하지 않습니다. 읽기 시작 위치, 필드 매핑, 동시 수집으로 인한 중복도 따로 맞춰야 합니다.
2. 필요한 플러그인 선택하기
| 단계 | 자주 쓰는 플러그인 |
|---|---|
| 입력 | 파일용 tail, journal용 systemd, syslog, http, opentelemetry |
| 필터 | 포함·제외용 grep, 필드 추가용 record_modifier, 조건부 수정용 modify, 메타데이터용 kubernetes, 스크립트용 lua, 구조 변경용 nest |
| 출력 | http, file, Fluentd 등으로 전송하는 forward, kafka, es/opensearch, s3 |
플러그인 제공 여부는 버전, 플랫폼, 빌드에 따라 달라집니다. 모든 설치 패키지에 표의 기능이 전부 포함된다고 가정하면 안 됩니다.
Kubernetes 필터는 tag 등의 정보에서 Pod, 네임스페이스, 컨테이너를 식별한 뒤 캐시를 사용하거나 설정된 API Server·Kubelet에 접근해 추가 정보를 가져옵니다. 컨테이너 런타임에서 모든 메타데이터를 자동으로 읽어오는 방식은 아닙니다.
/var/log/containers/*.log를 읽는다면 호스트 로그 마운트, tag와 Kube_Tag_Prefix, Docker·CRI 로그 형식과 파서를 맞춰야 합니다. API 접근에는 서비스 계정, RBAC, 네트워크 조건도 필요합니다. 앞의 app.* 일반 파일 예시를 완전한 Kubernetes 설정으로 사용할 수는 없습니다.
메타데이터 보강과 애플리케이션 본문 파싱도 서로 다른 작업입니다. Merge_Log On은 log의 JSON 내용을 파싱하거나 설정한 파서를 사용해 필드를 병합할 수 있습니다. 기본 Keep_Log 동작은 원래 필드를 남깁니다. 따라서 log 필드가 있다는 사실만으로 파싱 실패를 판단할 수 없습니다. Kubernetes 필터와 Merge_Log(영문)
3. 로그 파서를 등록한 뒤 입력에 연결하기
로그 파서(log parser)는 정의를 작성하고 시작할 때 로드해야 사용할 수 있습니다. 아래 내용을 /etc/fluent-bit/parsers-app.conf에 저장합니다. 1절의 Parsers_File이 이 파일을 읽습니다.
[PARSER]
Name app_json
Format json
Time_Key time
Time_Format %Y-%m-%dT%H:%M:%S%z
Time_Keep On
[PARSER]
Name nginx
Format regex
Regex ^(?<remote>\S+) \S+ \S+ \[(?<time>[^\]]+)\] "(?<method>\S+) (?<path>\S+) \S+" (?<code>\d{3})(?:\s|$)
Time_Key time
Time_Format %d/%b/%Y:%H:%M:%S %z
Time_Keep On
Types code:integer
Tail 입력의 Parser app_json은 다음처럼 한 줄에 JSON 객체 하나가 있는 로그를 처리합니다.
{"time":"2026-11-05T10:00:00+0800","level":"error","pod_name":"checkout-7d8f","message":"upstream timeout"}
+0800은 %z에 대응합니다. 원본 시간 형식이 바뀌면 필드 이름뿐 아니라 Time_Format도 맞춰야 합니다. Time_Keep On은 시간 파싱 후에도 원래 시간 필드를 남깁니다.
Nginx 접근 로그에는 해당 INPUT에서 Parser nginx를 사용합니다. 05/Nov/2026:10:00:00 +0800은 두 번째 시간 형식에 맞습니다. 정규식은 요청 경로와 HTTP 프로토콜을 분리하고, code를 정수로 변환합니다.
Fluent Bit의 정규식은 Onigmo의 Ruby 모드와 이름 있는 캡처를 사용합니다. 다른 정규식 엔진의 문법을 그대로 쓸 수 있다고 가정하면 안 됩니다. 여러 줄의 스택 트레이스에는 multiline 설정도 필요합니다. JSON은 파싱 형식이며, 이름이 json인 파서가 있는지는 실제로 로드한 정의에 달려 있습니다. 파서 등록(영문) · 정규식과 시간 파싱(영문)
4. SQL 집계의 입력과 윈도우 지정하기
스트림 처리기는 들어오는 레코드를 필터링하고 집계할 수 있습니다. 다음 쿼리는 최상위 pod_name별로 5초 텀블링 윈도우 안의 오류 레코드 수를 셉니다.
SELECT pod_name, COUNT(*) AS errors
FROM TAG:'app.*'
WINDOW TUMBLING (5 SECOND)
WHERE level = 'error'
GROUP BY pod_name;
TAG:'app.*'은 tag 패턴으로 레코드를 선택합니다. STREAM:이름은 입력 스트림을 참조하며 기본 이름은 tail.0 같은 형태입니다. INPUT의 Alias로 이름을 지정할 수도 있습니다. tag 와일드카드를 그대로 STREAM:app.*로 쓰는 것은 올바르지 않습니다.
윈도우를 생략하면 집계는 현재 레코드 버퍼를 대상으로 수행됩니다. 일정한 5초 구간의 결과로 해석할 수는 없습니다.
다음 작업을 /etc/fluent-bit/streams.conf에 저장합니다.
[STREAM_TASK]
Name pod_errors
Exec SELECT pod_name, COUNT(*) AS errors FROM TAG:'app.*' WINDOW TUMBLING (5 SECOND) WHERE level = 'error' GROUP BY pod_name;
기존 [SERVICE]에 Streams_File /etc/fluent-bit/streams.conf를 추가한 뒤 fluent-bit -c /etc/fluent-bit/fluent-bit.conf 등으로 주 설정을 로드합니다. SERVICE 섹션을 하나 더 만들면 안 됩니다.
입력에는 앞서 제시한 JSON처럼 최상위 pod_name과 level이 이미 있어야 합니다. 일반 Tail 입력은 Pod 정보를 자동으로 붙이지 않습니다. Kubernetes 필터가 만든 중첩 필드도 이 최상위 키와 자동으로 같아지지 않습니다.
단독 SELECT는 결과를 표준 출력으로 보냅니다. 원래 출력을 대체하거나 원본 로그 전송량을 줄이지 않습니다. 파생 레코드를 주 파이프라인으로 돌려보내려면 CREATE STREAM ... WITH (tag='new-tag') AS SELECT ...를 사용하고 새 tag의 경로를 설정해야 합니다. 파생 레코드가 같은 작업에 다시 매칭되지 않도록 해야 합니다. 집계 대상은 해당 인스턴스가 실제로 처리한 레코드이며, 노드 간 집계나 백엔드 알림 이관까지 자동으로 수행하지는 않습니다. SQL과 윈도우(영문) · 스트림과 tag(영문)
자주 묻는 질문
Fluent Bit와 Fluentd는 어떤 관계인가요?
같은 생태계에 속하지만 서로 다른 처리기입니다. 순서대로 업그레이드해야 하는 두 세대 제품은 아닙니다. Fluent Bit는 주로 C, Fluentd는 Ruby와 C로 구현됐습니다. 노드의 Fluent Bit에서 중앙 Fluentd로 Forward 프로토콜을 통해 보내는 구성이 흔하지만, 둘 다 플러그인과 배포 구성에 따라 전달·집계 역할을 하거나 독립적으로 사용할 수 있습니다. 공식 프로젝트 관계 설명(영문)
설정은 어떻게 디버깅하나요?
먼저 OUTPUT을 stdout으로 바꿔 레코드와 tag를 확인하고, Log_Level debug로 파서 로딩·파싱·라우팅을 살펴봅니다. log는 입력에서 만들어진 필드이거나 애플리케이션의 정상 필드, 또는 Keep_Log가 남긴 값일 수도 있습니다. 알려진 샘플에서 필요한 필드, 유형, 이벤트 시간을 확인해야 합니다.
Tail이 같은 레코드를 다시 수집할 수 있나요?
가능합니다. DB는 추적 파일과 오프셋을 저장하지만, 상태를 영속화하고 파일 식별, 로테이션, 잘라내기, 읽기 시작 위치를 올바르게 다뤄야 합니다. 시작할 때 발견했고 저장된 오프셋이 없는 파일은 기본적으로 끝에서 읽습니다. 기존 내용을 읽으려면 Read_from_Head를 명시적으로 검토해야 합니다. Rotate_Wait는 로테이션 이후 기존 파일을 더 지켜보는 시간이고, Ignore_Older는 오래된 파일을 제외하는 조건입니다. 둘 다 중복 제거 스위치가 아닙니다.
파일 오프셋은 백엔드 저장 완료 확인이 아닙니다. 메모리 버퍼 유실, 입력 정지 중 파일 로테이션·삭제, 출력 재시도와 한도 때문에 누락이나 중복이 발생할 수 있습니다. 파일시스템 버퍼는 복구 능력을 높이지만 Tail DB만으로 exactly-once를 보장할 수는 없습니다. 원본 파일 보존, 버퍼, 재시도, 수신 측 의미를 함께 확인해야 합니다. Tail 상태와 로테이션(영문) · 출력 재시도(영문)
Lua 필터는 언제 쓰나요?
기본 필터로 표현하기 어려운 필드 마스킹이나 계산에 사용합니다. 필터 콜백 인터페이스, 사용 가능한 런타임, 자료형, 시간 정밀도 등의 제약은 여전히 있습니다. 무엇이든 할 수 있는 것은 아닙니다. 느리거나 블로킹하는 로직은 처리 속도에 영향을 주므로 예외와 필드 변경도 샘플로 확인해야 합니다. 기본 필터로 표현할 수 있다면 단순한 설정을 우선합니다. Lua 콜백과 한계(영문)
