Promtail
Promtail은 Grafana Loki 시스템을 위해 특별히 설계된 에이전트(Agent)이자 로그 수집기(Log Collector)이다. 로컬 시스템이나 컨테이너 등에서 발생하는 로그 파일을 읽어들여 Grafana Loki 인스턴스로 전송하는 역할을 수행한다.
주요 특징 및 기능은 다음과 같다:
- 서비스 디스커버리 (Service Discovery): Prometheus와 동일한 서비스 디스커버리 메커니즘을 공유한다. 이를 통해 Kubernetes 파드(Pod), EC2 인스턴스, 컨테이너 등의 로그 타겟을 동적으로 식별하고 수집 대상을 자동화한다.
- 레이블링 (Labeling): 수집된 로그 스트림에 Prometheus 메트릭과 동일한 형태의 레이블(메타데이터)을 부여한다. 메트릭(Prometheus)과 로그(Loki)가 동일한 레이블 체계를 공유하게 되므로, 시스템 장애 발생 시 메트릭에서 로그로 자연스럽게 화면을 전환하며 원인을 분석할 수 있다.
- 파이프라인 단계 (Pipeline Stages): 로그를 서버로 전송하기 전에 정규 표현식(Regex)이나 JSON 파싱 등을 통해 로그 내용을 분석하고 특정 필드를 추출하거나 필터링할 수 있는 데이터 처리 파이프라인을 지원한다.
- 꼬리 읽기 (Tailing): 파일 시스템에 기록되는 로그 파일의 끝(Tail)을 실시간으로 추적하여 새롭게 추가되는 로그 라인만 지속적으로 서버에 푸시(Push)한다.
분산 환경에서 로그를 수집하여 중앙 서버로 전송하는 목적으로 자주 사용되는 Elastic 스택의 Filebeat와의 비교는 다음 표와 같다.
| 비교 항목 | Promtail | Filebeat |
|---|---|---|
| 주요 목적 | Grafana Loki로의 로그 수집 및 전송 | Elasticsearch 또는 Logstash로의 로그 전송 |
| 대상 생태계 | Grafana 및 Prometheus 통합 모니터링 환경 | Elastic (ELK) 스택 환경 |
| 메타데이터 구조 | Prometheus 형식의 키-값 레이블(Label) 할당 | 개별 로그 이벤트에 구조화된 필드(Fields) 추가 |
| 타겟 탐색 방식 | Prometheus의 Service Discovery 아키텍처 활용 | Beats Autodiscover 모듈 활용 |
| 데이터 처리 역량 | Pipeline stages를 통한 파싱 및 레이블 추출 | Processors를 통한 필드 추가, 삭제, 필터링 |
출처:
- Grafana Labs Official Documentation (grafana.com/docs/loki/latest/clients/promtail/)
- GitHub, “grafana/loki” repository (github.com/grafana/loki/tree/main/clients/pkg/promtail)
Entities
- Promtail
- Grafana Loki
- Prometheus
- Filebeat
- Elasticsearch
- Logstash
- Kubernetes
- Service Discovery
- Pipeline Stages
- Tailing
추가 기록 (2026-08-29T03:24:57.577836+00:00)
타겟 탐색 및 구성 (Service Discovery & Scrape Configs) 상세
Prometheus의 코드를 공유하므로, Kubernetes API, AWS EC2, Consul 등의 클라우드 인프라와 연동하여 동적으로 생성되고 삭제되는 리소스를 자동으로 탐지한다. 발견된 타겟 정보에 기반하여 어떤 로그 파일(__path__)을 수집할지 결정하며, 수집 과정에서 불필요한 대상을 제외(Relabeling)할 수도 있다.
포지션 추적 (Positions)
Promtail은 자신이 읽고 있는 로그 파일의 마지막 오프셋(Byte offset) 정보를 로컬 시스템의 positions.yaml 파일에 주기적으로 기록한다. 이 메커니즘을 통해 Promtail 프로세스가 비정상 종료되거나 재시작되더라도, 로그의 중복 수집이나 누락 없이 이전에 읽었던 위치부터 정확히 수집을 재개할 수 있다.
파이프라인 단계의 세부 유형
로그 라인이 Loki로 전송되기 전에 거치는 데이터 가공 단계이다. 파이프라인은 크게 세 가지 유형의 스테이지로 나뉜다.
- 파싱 스테이지 (Parsing Stages): 로그 원문에서 특정 필드를 추출한다. JSON 파서, 정규식(Regex) 파서, Logfmt 파서 등을 사용하여 비정형 문자열을 구조화된 키-값 쌍으로 분리한다.
- 변환 스테이지 (Transform Stages): 추출된 데이터를 조작한다. 템플릿(Template) 기능을 통해 여러 필드의 값을 결합하거나 특정 문자열 형태로 가공한다.
- 액션 스테이지 (Action Stages): 가공된 데이터를 실제 로직에 적용한다. 추출된 값을 Loki의 레이블(Labels)로 변환하거나, 로그의 타임스탬프(Timestamp)를 실제 발생 시간으로 덮어쓰고, 로그 발생 횟수에 기반해 Prometheus 메트릭(Metrics)을 자체적으로 생성하기도 한다.
Kubernetes 배포 아키텍처 비교
Kubernetes 환경에서 Promtail을 운영할 때 주로 고려되는 두 가지 배포 아키텍처 방식의 비교는 다음 표와 같다.
| 비교 항목 | DaemonSet (데몬셋) 패턴 | Sidecar (사이드카) 패턴 |
|---|---|---|
| 동작 방식 | 각 물리/가상 노드(Node)당 1개의 Promtail만 실행 | 단일 애플리케이션 파드(Pod) 내에 Promtail 컨테이너를 함께 배치 |
| 로그 수집 경로 | 호스트의 컨테이너 로그 디렉터리(/var/log/pods) 마운트 | 애플리케이션 파드 내부의 공유 볼륨(EmptyDir 등) 마운트 |
| 리소스 효율성 | 높음 (노드 내 모든 로그를 하나의 에이전트가 처리) | 낮음 (파드 개수만큼 에이전트 프로세스가 중복 실행됨) |
| 주요 사용 사례 | 일반적인 클러스터 전체의 중앙 집중식 표준 로그 수집 | 특정 애플리케이션의 커스텀 로그 파일 수집 및 강력한 테넌트 격리 |