Grafana Loki 최신 가이드: Docker Compose로 로그 수집 시스템 구축하기

요약

Grafana Loki는 로그 전체를 무겁게 색인하지 않고 라벨 기반으로 로그 스트림을 찾는 로그 수집 시스템입니다. 2026년 6월 기준 최신 릴리스는 Loki 3.7.x 계열이며, 예전 Loki 3.0 기준 글을 그대로 따라 하면 Promtail, 라벨 설계, 저장소 구성에서 오래된 정보가 섞일 수 있습니다. 이 글에서는 Docker Compose로 테스트 환경을 구성하는 방법과 실제 운영에서 자주 막히는 실패 사례를 함께 정리합니다.

배경

Loki를 처음 접하면 Elasticsearch처럼 로그 본문을 전부 색인하는 시스템으로 생각하기 쉽습니다. 하지만 Loki의 핵심은 다릅니다. 로그 본문 전체를 인덱싱하기보다, job, service_name, namespace, container 같은 라벨로 로그 스트림을 찾고 그 안에서 LogQL로 필터링합니다.

이 구조는 비용과 저장 효율 면에서 장점이 있지만, 라벨을 잘못 설계하면 오히려 성능이 나빠집니다. 특히 request_id, user_id, trace_id처럼 값이 계속 바뀌는 데이터를 라벨로 넣으면 카디널리티가 폭발합니다.

또 하나 중요한 변화는 Promtail입니다. Grafana 공식 문서 기준 Promtail은 2026년 3월 2일 EOL이 되었고, 향후 기능 개발은 Grafana Alloy에서 진행됩니다. 기존 Promtail 예제는 여전히 많이 검색되지만, 새로 구성한다면 Alloy 기준으로 보는 편이 안전합니다.

Loki 구조 이해

Loki 기반 로그 수집은 보통 세 부분으로 나눕니다.

구성 요소	역할
Loki	로그를 저장하고 LogQL 쿼리를 처리하는 서버
Alloy 또는 로그 수집 에이전트	파일, 컨테이너, Kubernetes 로그를 읽어 Loki로 전송
Grafana	Loki 데이터 소스를 연결해 로그를 검색하고 대시보드/알림을 구성

작은 테스트 환경에서는 Loki를 단일 바이너리로 실행해도 충분합니다. 하지만 운영 환경에서는 저장소, 복제, 보존 기간, 쿼리 성능, 멀티테넌시, 알림까지 고려해야 합니다.

Docker Compose 테스트 구성

공식 문서는 Docker 또는 Docker Compose를 평가, 테스트, 개발 용도로 사용할 수 있다고 설명합니다. 운영 환경에서는 Helm 또는 Tanka 같은 배포 방식을 권장합니다.

테스트용으로는 아래처럼 단순 구성부터 시작할 수 있습니다.

services:
  loki:
    image: grafana/loki:3.7.0
    ports:
      - "3100:3100"
    command: -config.file=/etc/loki/local-config.yaml

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=****
    depends_on:
      - loki

실행합니다.

docker compose up -d

Loki 상태는 다음처럼 확인할 수 있습니다.

curl http://localhost:3100/ready

정상이라면 ready에 가까운 응답을 볼 수 있습니다. Grafana는 브라우저에서 접속합니다.

http://localhost:3000

이 구성은 학습용입니다. 실제 운영에서는 파일시스템 저장소만 믿고 운영하거나, 단일 컨테이너 하나로 장기간 로그를 보관하는 방식은 피해야 합니다.

Promtail 대신 Alloy를 봐야 하는 이유

예전 Loki 튜토리얼은 대부분 Promtail을 사용합니다. 하지만 공식 문서 기준 Promtail은 EOL 상태입니다.

Promtail EOL: 2026-03-02
향후 기능 개발: Grafana Alloy

기존 운영 환경에서 Promtail을 이미 쓰고 있다면 즉시 장애가 나는 것은 아닙니다. 하지만 새로 구축하거나 글을 새로 작성한다면 Alloy 기반 구성을 함께 보는 것이 맞습니다. Grafana는 Promtail 설정을 Alloy 설정으로 변환하는 마이그레이션 도구도 안내하고 있습니다.

즉, 현재 기준의 권장 방향은 다음과 같습니다.

새 프로젝트: Alloy 우선 검토
기존 Promtail 운영: 마이그레이션 계획 수립
단기 테스트: 기존 예제 참고 가능하나 EOL 상태 명시

라벨 설계와 저장소 주의점

Loki에서 라벨은 검색의 시작점입니다. 공식 문서는 라벨을 로그 소스를 설명하는 낮은 카디널리티 값에 사용하라고 안내합니다.

좋은 라벨 예시는 다음과 같습니다.

service_name="api-server"
environment="prod"
namespace="backend"
container="nginx"

피해야 할 라벨 예시는 다음과 같습니다.

request_id="a1b2c3..."
user_id="123456"
ip="203.0.113.10"
trace_id="..."

자주 검색해야 하는 고카디널리티 값은 라벨보다 structured metadata나 로그 본문 필터링을 고려해야 합니다.

저장소도 중요합니다. 로컬 테스트에서는 파일시스템을 써도 되지만 운영에서는 S3, GCS, Azure Blob 같은 object storage와 보존 정책을 검토해야 합니다. 특히 retention을 설정하지 않으면 로그가 계속 쌓여 디스크나 저장소 비용 문제가 생길 수 있습니다.

실패 사례와 해결

사례 1. Grafana에서 Loki 데이터 소스 연결이 안 되는 경우

Grafana에서 http://localhost:3100을 넣었는데 연결이 안 될 수 있습니다. Docker Compose 안에서 Grafana 컨테이너가 Loki에 접근할 때의 주소와, 사용자의 브라우저에서 접근하는 주소가 다르기 때문입니다.

Compose 내부에서는 서비스 이름을 사용합니다.

http://loki:3100

호스트에서 직접 확인할 때는 다음을 씁니다.

curl http://localhost:3100/ready

즉, Grafana 컨테이너 내부 설정에는 localhost가 아니라 loki 서비스명을 넣어야 하는 경우가 많습니다.

사례 2. 로그가 들어오지 않는데 Loki는 정상인 경우

Loki가 떠 있어도 로그 수집 에이전트가 제대로 보내지 않으면 Grafana에는 아무것도 보이지 않습니다.

먼저 Loki 상태를 확인합니다.

curl http://localhost:3100/ready

그다음 수집 에이전트 로그를 봅니다.

docker compose logs

확인할 것은 다음입니다.

Loki push URL이 맞는가?
컨테이너 간 네트워크 이름이 맞는가?
로그 파일 경로가 컨테이너 안에서 보이는가?
라벨 설정 때문에 다른 stream으로 들어간 것은 아닌가?

사례 3. `label values`가 너무 많아지고 쿼리가 느려지는 경우

Loki에서 가장 흔한 운영 실수입니다. pod, container, namespace 정도는 괜찮을 수 있지만, 요청마다 바뀌는 값을 라벨로 넣으면 stream 수가 급격히 늘어납니다.

문제가 의심되면 라벨 목록부터 확인합니다.

{service_name="api-server"}

운영에서는 다음 원칙을 지킵니다.

라벨은 낮은 카디널리티 값만 사용
사용자 ID, 요청 ID, 세션 ID는 라벨로 넣지 않기
자주 바뀌는 값은 structured metadata 또는 로그 본문으로 처리

사례 4. Promtail 예제를 그대로 따라 했는데 최신 권장 방식과 다른 경우

검색 결과에는 Promtail 예제가 매우 많습니다. 하지만 Promtail은 EOL입니다. 따라서 새 환경을 만들 때는 Alloy 문서를 먼저 확인해야 합니다.

기존 Promtail 설정을 갖고 있다면 바로 지우기보다 마이그레이션 도구와 Alloy 문서를 확인합니다.

Promtail 설정 백업
Alloy 마이그레이션 문서 확인
테스트 환경에서 변환 설정 검증
운영 반영 전 로그 유실 여부 확인

사례 5. 로그 보존 기간을 설정하지 않아 저장소가 계속 커지는 경우

테스트 때는 잘 보이지 않지만 운영에서 자주 발생합니다. 로그는 생각보다 빨리 쌓입니다. 특히 debug 로그나 access log를 모두 수집하면 저장소 비용이 빠르게 늘어납니다.

운영 전에는 반드시 다음을 정합니다.

보존 기간
삭제 정책
저장소 타입
압축/청크 설정
환경별 로그 레벨

사례 6. Docker Compose 테스트 구성을 운영에 그대로 쓰는 경우

공식 문서도 Docker Compose는 평가, 테스트, 개발 용도에 적합하다고 설명합니다. 운영에서는 장애 복구, 저장소, 확장성, 보안, 인증, 모니터링을 따로 설계해야 합니다.

운영이라면 최소한 다음을 검토합니다.

Helm 기반 Kubernetes 배포
object storage 연동
retention 설정
Grafana 인증과 권한
Loki 자체 모니터링
백업과 장애 복구

모범 사례

Loki를 처음 구축할 때는 작게 시작하되 운영 기준을 미리 정하는 것이 좋습니다.

테스트는 Docker Compose로 빠르게 시작
새 수집 구성은 Alloy 기준으로 검토
라벨은 적게 시작하고 필요할 때 늘리기
고카디널리티 값은 라벨로 넣지 않기
운영 저장소와 retention을 먼저 설계
Grafana 대시보드보다 로그 유실/저장 비용/쿼리 성능을 먼저 확인

흔한 실수

Loki를 Elasticsearch처럼 이해하는 것

Loki는 로그 본문 전체를 색인하는 방식이 아닙니다. 라벨 설계가 검색 성능과 비용에 큰 영향을 줍니다.

Promtail 예제를 최신 권장 방식으로 착각하는 것

Promtail 예제는 많지만 현재는 EOL입니다. 새 구축에서는 Alloy를 우선 검토해야 합니다.

`localhost` 주소를 컨테이너 내부에서도 그대로 쓰는 것

Docker Compose 내부의 localhost는 각 컨테이너 자기 자신입니다. Grafana에서 Loki를 찾을 때는 http://loki:3100처럼 서비스명을 써야 할 수 있습니다.

retention 없이 로그를 계속 쌓는 것

로그는 계속 증가합니다. 보존 기간과 삭제 정책 없이 운영하면 디스크나 object storage 비용 문제가 생깁니다.

결론

Grafana Loki는 비용 효율적인 로그 수집 시스템을 만들기에 좋은 선택입니다. 하지만 제대로 쓰려면 설치 명령보다 라벨 설계, 수집 에이전트 선택, 저장소, retention, 쿼리 패턴을 먼저 이해해야 합니다.

2026년 기준으로 새로 구축한다면 Loki 3.7.x 문서를 기준으로 보고, Promtail 예제는 EOL 상태를 감안해 Alloy 전환까지 함께 고려하는 것이 좋습니다. 테스트는 Docker Compose로 시작해도 되지만, 운영은 Helm, object storage, retention, 모니터링을 포함해 별도로 설계해야 합니다.

참고 자료

Grafana Loki GitHub Release v3.7.2: https://github.com/grafana/loki/releases/tag/v3.7.2
Grafana Loki Docker 설치 문서: https://grafana.com/docs/loki/latest/setup/install/docker/
Grafana Loki Promtail 문서: https://grafana.com/docs/loki/latest/send-data/promtail/
Grafana Loki Alloy 문서: https://grafana.com/docs/loki/latest/send-data/alloy/
Grafana Loki Labels 문서: https://grafana.com/docs/loki/latest/get-started/labels/
Grafana Loki Storage 문서: https://grafana.com/docs/loki/latest/operations/storage/
Grafana Loki Query 문서: https://grafana.com/docs/loki/latest/query/