Copy & Run

Loki로 nginx 로그 모으고 LogQL로 조회하기: 라벨 설계와 개인정보 마스킹

nginx 접근 로그 하나를 Promtail 설정 두 개로 Loki 두 대에 보냅니다. 요청 주소와 IP를 라벨로 만든 나쁜 설정은 스트림이 11개로 늘고 이메일과 토큰이 그대로 저장되며, 좋은 설정은 스트림 1개에 마스킹된 줄만 저장합니다. 5xx 개수와 401 반복 IP를 LogQL로 세고, 점검 결과를 종료 코드로 바꿉니다.

Loki는 로그 본문 전체가 아니라 라벨만 색인하는 로그 저장소입니다. 그래서 라벨을 어떻게 정하느냐가 성능과 비용을 좌우하고, 본문에 무엇이 들어 있느냐가 개인정보 문제를 좌우합니다. 이 글은 nginx 접근 로그 파일 하나를 Promtail 설정 두 개가 동시에 읽어 서로 다른 Loki 두 대로 보내게 해서, 같은 로그가 두 설정에서 어떻게 달라지는지 비교합니다. 앞의 Logstash grok 글이 로그를 파싱해 필드로 나누는 방법이었다면, 이 글은 라벨 설계와 저장 전 마스킹을 다룹니다. 마스킹을 프롬프트와 로그에 적용하는 일반론은 개인정보 마스킹 글에, 로그 품질 점검은 SIEM 로그 품질 글에 있습니다.

준비물

항목 확인한 값
Docker 29.5.3 (Windows 11, Git Bash에서 실행)
Loki 3.5.0 (grafana/loki, 파일 시스템 저장, TSDB 색인)
Promtail 3.5.0 (grafana/promtail)
웹 서버와 클라이언트 nginx:alpine, curlimages/curl
점검 스크립트 파이썬 3.12 컨테이너(python:3.12-slim)에서 Loki HTTP API 호출

Promtail은 Grafana가 후속 도구인 Alloy로 옮기도록 안내하고 있어 앞으로 쓰이지 않을 도구로 알려져 있습니다. 이 글에서는 위 버전의 Promtail 이미지가 받아지고 동작하는 것까지만 확인했고, 폐기 일정은 확인하지 않았습니다. 라벨 설계와 마스킹 원리는 수집기가 바뀌어도 같지만, 설정 문법은 Alloy에서 다릅니다.

1. 구성

  1. osk-lbc-web(nginx)이 접근 로그를 공유 폴더의 access.log에 씁니다.
  2. Promtail 두 개가 같은 파일을 읽습니다. promtail_bad.yaml은 나쁜 설정, promtail_good.yaml은 좋은 설정입니다.
  3. 각각 loki-bad, loki-good로 보냅니다. loki-good에만 보존 기간 설정이 있습니다.
  4. 클라이언트 컨테이너 A와 B가 38건을 보냅니다. 요청마다 새 컨테이너를 띄우면 IP가 매번 달라지므로, 오래 사는 컨테이너 두 개에서 docker exec로 curl을 실행해 IP를 고정했습니다.
  5. 같은 점검 스크립트를 두 Loki에 돌립니다.

보낸 요청의 정답은 미리 정해 두었습니다.

요청 건수 비고
A: / 10 200
A: /search?email=u1@example.com&token=SECRETtok1 등 5 주소에 이메일과 토큰
A: /boom 3 500
A: POST /login 12 401
A: /missing 4 404
B: POST /login, /boom 각 2 401, 500

전체 38건, 5xx 5건, 401은 A가 12건, B가 2건입니다.

이 단계의 파일 내려받기:nginx_lab.confpromtail_bad.yamlpromtail_good.yaml

2. 나쁜 설정과 좋은 설정

나쁜 설정(promtail_bad.yaml)은 정규식으로 ip, uri, status를 뽑아 모두 라벨로 올립니다. 편리해 보이지만 라벨 값의 조합마다 Loki 스트림이 하나씩 생깁니다. 요청 주소에 이메일이 들어 있으면 사용자마다 새 스트림이 생기는 셈입니다. 좋은 설정(promtail_good.yaml)은 라벨을 job과 container로 고정하고, replace 단계에서 이메일과 token= 뒤의 값을 ****로 바꿉니다. IP와 상태 코드는 라벨이 아니라 조회할 때 LogQL의 pattern 파서로 뽑습니다.

이 단계의 파일 내려받기:loki_bad.yamlpromtail_bad.yamlpromtail_good.yaml

3. 같은 점검의 결과

점검 스크립트는 7가지를 확인하고 실패한 개수를 종료 코드로 돌려줍니다.

loki_demo.sh 실행 결과에서 나쁜 설정은 스트림 11개, 원문 이메일과 토큰 5건씩, 보존 기간 기본값으로 4개가 실패해 종료 코드 4이고, 좋은 설정은 스트림 1개와 마스킹으로 7개가 모두 통과해 종료 코드 0인 것을 확인합니다.
loki_demo.sh 실행 결과에서 나쁜 설정은 스트림 11개, 원문 이메일과 토큰 5건씩, 보존 기간 기본값으로 4개가 실패해 종료 코드 4이고, 좋은 설정은 스트림 1개와 마스킹으로 7개가 모두 통과해 종료 코드 0인 것을 확인합니다.

점검 나쁜 설정 좋은 설정
스트림 3개 이하 실패(11개) 통과(1개)
저장된 줄에 원문 이메일 실패(5건) 통과(0건)
저장된 줄에 원문 토큰 실패(5건) 통과(0건)
5xx 개수가 access.log와 일치 통과(5) 통과(5)
전체 줄 수가 access.log와 일치 통과(38) 통과(38)
401이 가장 많은 IP의 건수 통과(12) 통과(12)
보존 기간 설정 실패(기본값) 통과(24시간)
종료 코드 4 0
  • 개수 조회는 두 설정이 같았습니다. 5xx 개수와 전체 줄 수는 grep -c로 센 access.log의 값과 두 Loki 모두 맞았습니다. 라벨 설계가 나빠도 조회 결과는 틀리지 않습니다. 문제는 조회가 아니라 스트림 수와 저장된 내용에서 드러납니다.
  • 401 반복은 IP 하나로 모였습니다. sum by (ip) (count_over_time(... | status="401" [15m]))로 세면 건수가 가장 많은 IP가 12건이었고, A에서 보낸 건수와 같았습니다. 나쁜 설정에서는 ip가 라벨이라 같은 쿼리가 그대로 동작했습니다.
  • 마스킹은 저장 전에만 적용됩니다. access.log 원본에는 이메일이 든 줄이 그대로 5줄 남아 있었습니다. Promtail이 Loki로 보내는 줄만 바뀝니다. 원본 파일의 보관과 접근 제한은 따로 해야 합니다.
이 단계의 파일 내려받기:lbc_check.pyloki_demo.sh

4. 라벨과 저장된 줄 직접 보기

KEEP=1로 데모를 돌려 두 Loki를 남기고, 라벨 이름과 저장된 줄을 API로 읽어 봤습니다.

loki_peek.sh 실행 결과에서 나쁜 설정의 라벨은 ip, status, uri를 포함하고 uri 값이 9개이며 저장된 줄에 이메일과 토큰이 그대로 있고, 좋은 설정의 라벨은 container, filename, job, service_name이며 저장된 줄은 email과 token 값이 별표로 바뀐 것을 확인합니다.
loki_peek.sh 실행 결과에서 나쁜 설정의 라벨은 ip, status, uri를 포함하고 uri 값이 9개이며 저장된 줄에 이메일과 토큰이 그대로 있고, 좋은 설정의 라벨은 container, filename, job, service_name이며 저장된 줄은 email과 token 값이 별표로 바뀐 것을 확인합니다.

  • 나쁜 설정의 라벨: filename, ip, job, service_name, status, uri. uri 값만 9가지였습니다.
  • 좋은 설정의 라벨: container, filename, job, service_name. 저장된 줄은 GET /search?email=****&token=**** HTTP/1.1이었습니다.
  • service_name: 내가 설정하지 않았는데 두 Loki 모두에 생겼습니다. 이 버전이 자동으로 붙이는 라벨로 보이며, 설정 문서까지는 확인하지 않았습니다.
이 단계의 파일 내려받기:lbc_peek.pyloki_peek.sh

5. 보존 기간은 무엇을 보면 되나

loki_good.yaml에는 limits_config.retention_period: 24h와 compactor.retention_enabled: true가 있습니다. 적용 여부는 Loki의 /config 주소에서 읽었고, 그 출력은 24h를 1d로 보여 줍니다. 처음에는 점검 스크립트가 24h라는 글자를 찾다가 설정이 있는데도 실패했습니다. 실제로 오래된 로그가 지워지는지는 확인하지 않았습니다. 설정이 적용된 것만 확인했습니다.

이 단계의 파일 내려받기:loki_good.yaml

전체 코드

전체를 한 번에 돌리는 스크립트입니다. 아래 파일과 같은 폴더에서 실행합니다. KEEP=1로 실행하면 컨테이너를 남깁니다.

# loki_demo.sh
#!/usr/bin/env bash
# nginx 접근 로그 하나를 Promtail 두 설정(나쁜 라벨과 원문 저장, 좋은 라벨과 마스킹)으로 Loki 두 개에 보내고 같은 점검을 돌린다.
# 준비: Docker, python, 같은 폴더에 loki_*.yaml, promtail_*.yaml, nginx_lab.conf, lbc_check.py. 내 PC의 컨테이너만 쓴다.
# 실행(Git Bash): bash loki_demo.sh   (약 2분). KEEP=1 로 실행하면 컨테이너를 남기고, loki_peek.sh 가 보고 지운다.
export MSYS_NO_PATHCONV=1
HERE="$(pwd)"
OUT=../osk-lbc-out                       # 결과 폴더는 설정 폴더 밖에 둔다
rm -rf "$OUT"; mkdir -p "$OUT/logs"; ABS="$(cd "$OUT" && pwd)"
N=osk-lbc-net
cleanup() { docker rm -f osk-lbc-web osk-lbc-loki-bad osk-lbc-loki-good osk-lbc-pt-bad osk-lbc-pt-good osk-lbc-ca osk-lbc-cb >/dev/null 2>&1; docker network rm $N >/dev/null 2>&1; }
cleanup
docker network create $N >/dev/null
for v in bad good; do
  docker run -d --name osk-lbc-loki-$v --network $N -v "$HERE/loki_$v.yaml:/etc/loki/local.yaml:ro" \
    grafana/loki:3.5.0 -config.file=/etc/loki/local.yaml >/dev/null
done
docker run -d --name osk-lbc-web --network $N -v "$HERE/nginx_lab.conf:/etc/nginx/conf.d/default.conf:ro" \
  -v "$ABS/logs:/var/log/nginx" nginx:alpine >/dev/null
sleep 2
for v in bad good; do
  docker run -d --name osk-lbc-pt-$v --network $N -v "$HERE/promtail_$v.yaml:/etc/promtail/config.yml:ro" \
    -v "$ABS/logs:/var/log/nginx:ro" grafana/promtail:3.5.0 -config.file=/etc/promtail/config.yml >/dev/null
done
echo "## 1. Loki 준비 기다리기"
for v in bad good; do
  for i in $(seq 1 40); do
    r=$(docker run --rm --network $N curlimages/curl -s http://osk-lbc-loki-$v:3100/ready)
    [ "$r" = "ready" ] && break; sleep 3
  done
  echo "  loki-$v: $r"
done

echo "## 2. 트래픽 보내기(클라이언트 A 34건, B 4건, IP를 구분하려고 컨테이너 둘을 유지)"
for c in ca cb; do docker run -d --name osk-lbc-$c --network $N --entrypoint sleep curlimages/curl 600 >/dev/null; done
A() { docker exec osk-lbc-ca curl -s -o /dev/null "$@"; }
B() { docker exec osk-lbc-cb curl -s -o /dev/null "$@"; }
for i in $(seq 1 10); do A http://osk-lbc-web/; done
for i in 1 2 3 4 5; do A "http://osk-lbc-web/search?email=u$i@example.com&token=SECRETtok$i"; done
for i in 1 2 3; do A http://osk-lbc-web/boom; done
for i in $(seq 1 12); do A -X POST -d 'pw=x' http://osk-lbc-web/login; done
for i in 1 2 3 4; do A http://osk-lbc-web/missing; done
for i in 1 2; do B -X POST -d 'pw=x' http://osk-lbc-web/login; B http://osk-lbc-web/boom; done
sleep 12
LINES=$(wc -l < "$ABS/logs/access.log" | tr -d ' ')
E5=$(grep -cE '" 5[0-9][0-9] ' "$ABS/logs/access.log")
echo "  access.log: 전체 $LINES줄, 5xx $E5줄, 이메일이 든 줄 $(grep -c '@example.com' "$ABS/logs/access.log")줄"

echo "## 3. 같은 점검을 두 Loki 에 돌리기(실패 개수가 종료 코드)"
for v in bad good; do
  echo "### $v"
  docker run --rm --network $N -v "$HERE:/w:ro" python:3.12-slim python /w/lbc_check.py http://osk-lbc-loki-$v:3100 --lines "$LINES" --err5xx "$E5" --bf-ip 12
  echo "  종료 코드 $?"
done
[ "$KEEP" = "1" ] || cleanup
echo "## 끝 (결과 폴더: $OUT)"

보존 기간을 넣은 Loki 설정입니다. 나쁜 쪽(loki_bad.yaml)은 여기서 limits_config와 compactor 두 블록만 뺀 것으로, 내려받는 묶음에 들어 있습니다.

loki_good.yaml

auth_enabled: false
server:
  http_listen_port: 3100
common:
  path_prefix: /loki
  storage:
    filesystem:
      chunks_directory: /loki/chunks
      rules_directory: /loki/rules
  replication_factor: 1
  ring:
    kvstore:
      store: inmemory
schema_config:
  configs:
    - from: 2024-01-01
      store: tsdb
      object_store: filesystem
      schema: v13
      index:
        prefix: index_
        period: 24h
limits_config:
  retention_period: 24h
compactor:
  working_directory: /loki/compactor
  retention_enabled: true
  delete_request_store: filesystem
analytics:
  reporting_enabled: false

나쁜 Promtail 설정입니다. 정규식으로 뽑은 값을 라벨로 올립니다.

promtail_bad.yaml

server:
  disable: true
positions:
  filename: /tmp/positions.yaml
clients:
  - url: http://osk-lbc-loki-bad:3100/loki/api/v1/push
scrape_configs:
  - job_name: nginx
    static_configs:
      - targets: [localhost]
        labels:
          job: nginx
          __path__: /var/log/nginx/access.log
    pipeline_stages:
      - regex:
          expression: '^(?P<ip>\S+) \S+ \S+ \[[^\]]+\] "(?P<method>\S+) (?P<uri>\S+) [^"]*" (?P<status>\d+)'
      - labels:
          ip:
          uri:
          status:

좋은 Promtail 설정입니다. 라벨은 둘로 고정하고 이메일과 토큰 값을 별표로 바꿉니다.

promtail_good.yaml

server:
  disable: true
positions:
  filename: /tmp/positions.yaml
clients:
  - url: http://osk-lbc-loki-good:3100/loki/api/v1/push
scrape_configs:
  - job_name: nginx
    static_configs:
      - targets: [localhost]
        labels:
          job: nginx
          container: osk-lbc-web
          __path__: /var/log/nginx/access.log
    pipeline_stages:
      - replace:
          expression: '([\w.+-]+@[\w-]+\.[\w.]+)'
          replace: '****'
      - replace:
          expression: 'token=(\w+)'
          replace: '****'

로그 파일 경로를 지정한 nginx 설정입니다.

# nginx_lab.conf
server {
  listen 80;
  access_log /var/log/nginx/access.log;
  location = /login   { return 401 "denied\n"; }
  location = /boom    { return 500 "error\n"; }
  location = /missing { return 404 "none\n"; }
  location /          { return 200 "hello\n"; }
}

Loki API로 점검하고 실패한 개수를 종료 코드로 돌려주는 스크립트입니다.

# lbc_check.py
#!/usr/bin/env python
"""Loki HTTP API 로 로그 저장 상태를 점검하고, 실패한 점검 개수를 종료 코드로 돌려준다.
사용: python lbc_check.py http://osk-lbc-loki-good:3100 --lines 38 --err5xx 5 --bf-ip 12"""
import json
import sys
import urllib.parse
import urllib.request

base = sys.argv[1]
arg = lambda k: int(sys.argv[sys.argv.index(k) + 1])
PAT = '| pattern `<ip> - <_> [<_>] "<_> <_> <_>" <status> <_> "<_>" "<_>"`'


def get(path, **q):
    url = f"{base}{path}?{urllib.parse.urlencode(q, doseq=True)}"
    return json.load(urllib.request.urlopen(url, timeout=20))


def instant(expr):
    r = get("/loki/api/v1/query", query=expr)["data"]["result"]
    return {tuple(sorted(x["metric"].items())): int(float(x["value"][1])) for x in r}


def count(expr):
    return sum(instant(f"sum(count_over_time({expr}[15m]))").values())


results = []
streams = len(get("/loki/api/v1/series", **{"match[]": '{job="nginx"}'})["data"])
results.append(("스트림 수 3 이하", streams <= 3, f"스트림 {streams}개"))
for name, needle in (("이메일", "@example.com"), ("토큰", "SECRETtok")):
    n = count(f'{{job="nginx"}} |= "{needle}"')
    results.append((f"원문 {name} 0건", n == 0, f"{n}건"))
n5 = count(f'{{job="nginx"}} {PAT} | status=~"5.."')
results.append(("5xx 개수 일치", n5 == arg("--err5xx"), f"Loki {n5} / 기대 {arg('--err5xx')}"))
total = count('{job="nginx"}')
results.append(("전체 줄 수 일치", total == arg("--lines"), f"Loki {total} / access.log {arg('--lines')}"))
bf = instant(f'sum by (ip) (count_over_time({{job="nginx"}} {PAT} | status="401" [15m]))')
top = max(bf.values()) if bf else 0
results.append(("401 최다 IP 탐지", top == arg("--bf-ip"), f"최다 {top}건 / 기대 {arg('--bf-ip')}"))
cfg = urllib.request.urlopen(base + "/config", timeout=20).read().decode()
ret = "retention_period: 1d" in cfg and "retention_enabled: true" in cfg   # /config 는 24h 를 1d 로 보여 준다
results.append(("보존 기간 설정", ret, "적용됨" if ret else "기본값"))

bad = 0
for name, ok, detail in results:
    print(f"  {'통과' if ok else '실패'}  {name:<16} {detail}")
    bad += not ok
print(f"  실패 {bad}개 -> 종료 코드 {bad}")
sys.exit(bad)

라벨과 저장된 줄을 보는 스크립트와 실행기입니다.

# lbc_peek.py
#!/usr/bin/env python
"""두 Loki 의 라벨 이름, uri 라벨 값 개수, 저장된 줄 예시를 보여 준다. 사용: python lbc_peek.py"""
import json
import sys
import time
import urllib.parse
import urllib.request

sys.stdout.reconfigure(encoding="utf-8")


def get(base, path, **q):
    url = f"{base}{path}?{urllib.parse.urlencode(q)}"
    return json.load(urllib.request.urlopen(url, timeout=20))["data"]


for v in ("bad", "good"):
    base = f"http://osk-lbc-loki-{v}:3100"
    print(f"### {v}")
    print("  라벨 이름:", ", ".join(get(base, "/loki/api/v1/labels")))
    if v == "bad":
        vals = get(base, "/loki/api/v1/label/uri/values")
        print(f"  uri 라벨 값 {len(vals)}개, 예: {vals[0]}")
    now = int(time.time() * 1e9)
    res = get(base, "/loki/api/v1/query_range", query='{job="nginx"} |= "search"', limit=1,
              start=now - 3600 * 10**9, end=now)["result"]
    print("  저장된 줄 예:", res[0]["values"][0][1][:100] if res else "(없음)")

위 스크립트를 부르고 컨테이너를 지우는 실행기입니다.

# loki_peek.sh
#!/usr/bin/env bash
# KEEP=1 bash loki_demo.sh 로 남겨 둔 두 Loki 의 라벨과 저장된 줄을 보고, 컨테이너를 지운다.
export MSYS_NO_PATHCONV=1
HERE="$(pwd)"
docker run --rm --network osk-lbc-net -v "$HERE:/w:ro" python:3.12-slim python /w/lbc_peek.py
docker rm -f osk-lbc-web osk-lbc-loki-bad osk-lbc-loki-good osk-lbc-pt-bad osk-lbc-pt-good osk-lbc-ca osk-lbc-cb >/dev/null 2>&1
docker network rm osk-lbc-net >/dev/null

자주 막히는 곳

증상 원인 해결
보존 기간 점검이 설정을 넣었는데도 실패 /config가 24h를 1d로 출력 출력 형식에 맞춰 retention_period: 1d 검색
요청마다 docker run으로 보내면 IP별 집계가 의미 없음 컨테이너마다 IP가 달라짐 오래 사는 컨테이너에서 docker exec로 실행(첫 초안 검토 중 발견, 실행 전 수정)
Promtail이 로그를 못 읽음 공유 폴더에 access.log가 없거나 경로가 다름 nginx를 먼저 띄우고 같은 폴더를 읽기 전용으로 마운트

확인 범위

  • 해 본 것: 2026-10-31, Windows 11 · Docker 29.5.3 · Loki 3.5.0 · Promtail 3.5.0에서 같은 nginx 로그를 설정 두 개로 두 Loki에 보내 스트림 수, 원문 이메일과 토큰 검색, 5xx 개수, 전체 줄 수, 401 최다 IP, 보존 설정을 확인하고 종료 코드를 비교했습니다. 전체 스크립트를 세 번 이상 실행해 결과가 같았고 끝에 컨테이너와 네트워크를 지웠습니다.
  • 해 보지 않은 것: Alloy 설정, Grafana 화면 조회, 실제 보존 기간 만료와 삭제, 저장 파일(chunk)의 바이트 검사(마스킹은 API 검색으로만 확인), 이메일과 토큰 외의 개인정보 마스킹, 스트림이 매우 많을 때의 성능과 제한 값, 여러 호스트의 로그 수집, Linux와 macOS.
  • 읽을 때 주의: 이 글의 트래픽은 내 PC의 컨테이너끼리 만든 것입니다. 스트림 수 기준 3개와 개수 기대값은 이 실습용으로 정했고 권장값이 아닙니다. 마스킹 정규식은 이 글의 주소 형식에만 맞춘 예이며 모든 이메일 형식을 잡는다고 보장하지 않습니다. Promtail의 폐기 일정과 service_name 자동 라벨의 정확한 규칙은 확인하지 않았습니다.

이 글은 스타트업·소규모 조직 보안 구축 로드맵의 한 단계입니다.

이 글의 다음 단계

  • Prometheus 알림 규칙 promtool 단위 시험Prometheus 2.51 컨테이너의 promtool로 알림 규칙의 문법 오류와 논리 오류를 나눠 잡고, 가짜 시계열을 넣어 몇 분 뒤에 알림이 울리는지 단위 시험으로 확인합니다. Alertmanager 0.27의 amtool로 라벨별 수신처가 맞는지, 수신처를 빠뜨린 설정이 막히는지도 서버 없이 시험하고 종료 코드로 판정합니다.
  • Logstash로 nginx 로그를 Grok으로 파싱하고 ECS로 정규화하기nginx 접근 로그를 Logstash grok으로 파싱해 ECS 필드 이름으로 정리하고, 파싱에 실패한 로그를 Elasticsearch 쿼리로 세어 별도 인덱스로 보냅니다. Docker로 Elasticsearch 8.19와 Logstash 8.19를 띄워 끝까지 돌리고, Kibana Discover에서 적재된 필드를 확인합니다.

이 내용을 팀 교육으로 진행하고 싶으신가요?

인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.

교육 문의하기

교육 진행 순서와 자주 묻는 질문 보기

팀이나 교육 담당자에게 이 글 제안하기

메일로 보내실 수도 있습니다: fankh111@gmail.com

같은 카테고리의 글