Vector 로그 수집 가이드: VRL, 라우팅, 디스크 버퍼

Vector에서 Nginx 액세스 로그를 수집하고 VRL로 필드를 가공합니다. HTTP 재시도와 디스크 버퍼, 파일 체크포인트의 동작 범위를 살펴봅니다.

모범 사례
로그 이벤트 수집과 데이터 분석을 보여 주는 그림

Nginx는 계속 액세스 로그를 쓰는데, 설정을 바꾼 뒤 502 그래프가 평평해졌습니다. 먼저 수집기가 어떤 이벤트를 내보내는지 확인합니다. 파서가 status를 추출하지 못하면 로그는 저장돼도 502를 집계하는 쿼리에는 잡히지 않습니다.

Vector는 Rust로 작성된 옵저버빌리티 데이터 파이프라인입니다. source는 이벤트를 받고, transform은 내용을 바꾸고, sink는 결과를 전송합니다. 이 글에서는 파일의 한 줄이 Vector Remap Language(VRL)를 거쳐 출력되는 과정부터 수신처가 느려졌을 때의 버퍼와 재시도까지 살펴봅니다. 메트릭과 트레이스를 다룰 때는 구성 요소별로 지원하는 데이터 타입을 확인해야 합니다. Vector의 OpenTelemetry source는 트레이스도 받지만 트레이스 지원은 실험 단계입니다. OpenTelemetry source

액세스 로그 한 줄을 출력까지 따라가기

다음 설정을 vector.toml로 저장하고 작업 디렉터리에 ./vector-data를 만듭니다. Vector를 실행하는 계정에는 이 디렉터리의 쓰기 권한과 Nginx 로그 파일의 읽기 권한이 필요합니다. vector validate vector.toml로 검증한 뒤 vector --config vector.toml로 실행합니다. 새 파일에 read_from = "end"를 적용했다면 Vector가 파일을 감시하기 시작한 뒤 테스트 로그를 추가합니다. 체크포인트가 있는 파일은 저장된 위치부터 읽습니다.

# vector.toml
data_dir = "./vector-data"

[sources.nginx_access]
type = "file"
include = ["/var/log/nginx/access.log"]
read_from = "end"

[transforms.parse_nginx]
type = "remap"
inputs = ["nginx_access"]
source = '''
fields, err = parse_regex(.message, r'^(?<ip>\S+) \S+ \S+ \[(?<time>[^\]]+)\] "(?<method>[A-Z]+) (?<path>[^" ]+)[^"]*" (?<status>\d{3}) (?<size>\d+|-)')
if err == null {
  . |= fields
  .status = to_int!(.status)
  if .size == "-" {
    del(.size)
  } else {
    .size = to_int!(.size)
  }
} else {
  .parse_error = true
}
'''

[sinks.console]
type = "console"
inputs = ["parse_nginx"]
encoding.codec = "json"

inputs가 각 구성 요소의 앞단을 지정합니다. file source는 원래 줄을 message에 담고, parse_nginx는 필요한 필드를 추출합니다. 상태 코드와 알 수 있는 응답 크기는 정수로 바꿉니다. 크기가 -인 경우에는 size를 생략해 0바이트 응답과 구분합니다. 이 예제는 Nginx의 시각을 문자열로 남깁니다. 이벤트 발생 시각을 기준으로 그래프를 그리려면 그 값을 파싱해 수신처가 사용하는 시간 필드에 넣어야 합니다.

192.0.2.10 - - [09/Nov/2026:10:00:00 +0800] "GET /checkout HTTP/1.1" 502 128

이 줄을 추가하면 console 출력에 path = "/checkout", 숫자형 status = 502, size = 128이 나타납니다. 형식이 맞지 않는 줄에는 parse_error = true가 붙고 원래 메시지가 남으므로 따로 집계할 수 있습니다. 운영 로그에 인증 정보나 개인정보가 들어갈 수 있다면 console에서는 합성 데이터를 사용하고, 파싱하지 못한 이벤트를 어디로 보낼지 외부 sink를 열기 전에 정합니다. File source

VRL로 내보낼 필드 지정하기

별도의 입력에서 로그 레벨과 비밀번호를 담은 JSON 문자열이 message로 들어온다고 가정합니다. 파싱된 객체에서만 비밀번호를 지우면 원래 문자열에는 그대로 남습니다. 수신처에 정규화한 로그 레벨과 상태만 필요하다면, 허용한 필드로 이벤트 전체를 다시 구성합니다.

parsed = parse_json!(.message)
level = downcase(string!(parsed.level))
if !includes(["trace", "debug", "info", "warn", "error", "fatal"], level) {
  level = "unknown"
}
status = if includes(["error", "fatal"], level) { "error" } else { level }
. = {"level": level, "status": status}

입력이 잘못되면 parse_json!과 string!은 해당 이벤트의 VRL 실행을 중단합니다. 이후 이벤트를 어떻게 처리할지는 remap 설정에 따릅니다. 이 마스킹 경로에서는 drop_on_error = true와 drop_on_abort = true를 명시하고 폐기 건수를 모니터링합니다. 오류 시 수정하지 않은 원본이 그대로 전달되는 설정도 있기 때문입니다. 이 예제는 레벨 값 여섯 가지만 허용하고 다른 문자열은 unknown으로 바꿉니다. 나머지 필드는 모두 제외합니다. 타임스탬프나 상관관계 ID가 필요하면 타입과 값을 확인한 뒤 허용 목록에 넣습니다. JSON 처리 규칙과 앞의 Nginx 파서는 서로 다른 입력에 연결합니다. Remap transform · VRL 오류

수신처가 느려질 때 필요한 버퍼

첫 번째 설정에 다음 HTTP sink를 추가합니다. URI를 실제 수신처로 바꾸고 인증 방식과 요청 형식을 확인합니다. 이 구성에서는 console과 HTTP가 모두 parse_nginx의 출력을 받습니다. 로컬에서 검증을 마쳤다면 불필요한 console sink는 제거할 수 있습니다.

[sinks.platform]
type = "http"
inputs = ["parse_nginx"]
uri = "https://logs.example.com/"
encoding.codec = "json"
buffer.type = "disk"
buffer.max_size = 5368709120
buffer.when_full = "block"

디스크 버퍼는 최대 5 GiB를 사용합니다. 데이터 디렉터리를 쓰기 가능한 영구 스토리지에 두면, 디스크에 동기화된 이벤트는 Vector를 재시작한 뒤 이어서 전송할 수 있습니다. 버퍼가 차면 block이 앞단에 백프레셔를 전달합니다. 수집이 밀리는 동안 로테이션된 파일이 사라지거나, 디스크 장애가 발생하거나, 동기화 전에 프로세스가 종료되면 데이터가 유실될 수 있습니다.

HTTP 429나 503은 재시도할 수 있습니다. 400을 받았다면 요청 내용이나 엔드포인트를 확인해야 합니다. 수신처가 이미 기록한 뒤 응답이 도달하지 않으면 재전송으로 중복이 생길 수 있습니다. 실제 버퍼 유입량과 견뎌야 할 중단 시간으로 용량을 추정합니다. 복구 뒤 새 로그를 받으면서 밀린 로그도 처리할 여유가 있는지 확인합니다. HTTP sink · 버퍼링 모델

운영하기 쉬운 위치에 변환 배치하기

호스트나 쿠버네티스 노드의 Vector Agent는 로컬 파일을 읽어 백엔드로 바로 보낼 수 있습니다. 여러 Agent의 이벤트를 Aggregator에서 받아 공통 변환과 라우팅을 맡길 수도 있습니다. 규칙을 바꿀 위치가 줄어드는 대신 네트워크 부하와 백프레셔가 집계 계층에 모입니다. 어떤 구성이 나을지는 실제 이벤트 크기, 변환 비용, 디스크 사용량, 출력 처리량을 보고 판단합니다. 배포 역할

파일 수집을 Guance DataKit으로 옮길 때는 대표 로그를 소량 수집해 비교합니다. 로그 탐색기에서 이벤트 발생 시각과 숫자 필드의 타입을 살펴보고, 여러 줄짜리 스택 트레이스도 한 이벤트로 묶이는지 확인합니다. 필요한 VRL 로직은 Pipeline 규칙으로 다시 구현해야 합니다. Vector를 유지하면서 수신처만 바꾼다면 전환 전에 수신 인터페이스와 HTTP 본문 형식을 확인합니다. DataKit 로그 수집 · Guance 로그 처리

설정할 때 자주 나오는 질문

source에서 sink로 바로 보낼 수 있나요? sink가 해당 이벤트 타입을 지원하고 수신처가 전송 형식을 처리할 수 있으면 가능합니다. Vector는 TOML, YAML, JSON을 지원합니다. 배포에서 실제로 읽는 설정 파일을 검증하세요.

체크포인트가 있으면 수신처에 저장된 건가요? 체크포인트는 파일의 읽기 위치입니다. 수신처의 영구 저장 여부와는 별도로 source와 sink의 종단 간 확인 응답 지원을 살펴봐야 합니다. 수집이 늦어질 때를 대비해 로테이션된 파일도 충분히 보관합니다. 종단 간 확인 응답

Vector와 Fluent Bit는 어떻게 비교하나요? 같은 샘플에 필요한 변환을 적용하고, 수신처가 느려질 때 두 구성이 어떻게 반응하는지 확인합니다. 기존 Fluent Bit 필터와 파일시스템 버퍼로 운영이 가능하다면 수집기 교체 비용을 고려해야 합니다. 필드 변환을 표현하거나 관리하기 어렵다면 VRL로 작성한 설정을 나란히 두고 출력을 비교합니다. Fluent Bit 버퍼링

관련 글

맞춤형 플랜 상담

문의하기

커뮤니티 가입

WeChat으로 스캔하여
커뮤니티에 가입하세요

Guance 사용해 보기

온라인에서 바로 시작하고 사용한 만큼만 결제하세요.

시작하기

Guance 요금제 선택

코드 저장소