Docker에서 Loki로 로그 수집하기: “사이드카 패턴”도 가능하지만, Docker에서는 더 단순한 방법이 있다

Docker에서도 사이드카 패턴으로 로그를 뽑아서 Loki로 보낼 수 있을까?

왜 “사이드카”라는 말이 Docker에서는 조금 애매할까

1. stdout/stderr 로그를 바로 Loki로 보낸다
→ loki-docker-driver

2. 파일 로그를 수집하거나 전처리가 필요하다
→ Alloy 컨테이너가 파일 또는 Docker API를 읽어서 Loki로 전송

먼저 결론: 나는 어떤 방식을 고르면 될까

• 애플리케이션이 stdout/stderr로 로그를 남긴다
→ Loki Docker logging driver 추천

• 애플리케이션이 파일 로그를 남긴다
→ Alloy 컨테이너 + 공유 볼륨 tailing 추천

• stdout 로그인데도 수집 규칙을 중앙에서 제어하고 싶다
→ Alloy가 Docker daemon을 읽는 방식 고려

방법 1. stdout/stderr 기반이라면 Loki Docker logging driver가 가장 단순하다

여기서 말하는 “도커 플러그인”이란?

설치 예시

docker plugin install grafana/loki-docker-driver:3.6.0-arm64 \
  --alias loki \
  --grant-all-permissions

Docker Compose 예시

services:
  api:
    image: your-api:latest
    ports:
      - "8000:8000"
    environment:
      APP_ENV: prod
    logging:
      driver: loki
      options:
        loki-url: "https://USER:[email protected]/loki/api/v1/push"
        loki-batch-size: "400"
        loki-retries: "5"
        max-size: "10m"
        max-file: "3"

이 방식이 잘 맞는 경우

• 앱이 이미 콘솔 로그를 잘 남긴다

• 설정을 최대한 단순하게 가져가고 싶다

• 컨테이너별 수집기 운영이 번거롭다

• docker logs도 계속 쓰고 싶다

주의할 점

방법 2. 진짜 “사이드카 느낌”이 필요하면 Alloy + 파일 로그 구성이 맞다

Compose 예시

services:
  api:
    image: your-api:latest
    volumes:
      - app_logs:/var/log/myapp
    environment:
      LOG_PATH: /var/log/myapp/app.log

  alloy:
    image: grafana/alloy:latest
    command:
      - run
      - --server.http.listen-addr=0.0.0.0:12345
      - --storage.path=/var/lib/alloy/data
      - /etc/alloy/config.alloy
    volumes:
      - ./alloy/config.alloy:/etc/alloy/config.alloy:ro
      - app_logs:/var/log/myapp:ro
      - alloy_data:/var/lib/alloy/data
    depends_on:
      - api
    ports:
      - "12345:12345"

volumes:
  app_logs:
  alloy_data:

config.alloy 예시

logging {
  level  = "info"
  format = "logfmt"
}

loki.source.file "api_logs" {
  targets = [
    {
      __path__ = "/var/log/myapp/*.log",
      job      = "api",
      service  = "your-api",
      env      = "prod",
    },
  ]

  forward_to = [loki.write.remote.receiver]

  file_match {
    enabled     = true
    sync_period = "10s"
  }
}

loki.write "remote" {
  endpoint {
    url = "https://loki.example.com/loki/api/v1/push"

    basic_auth {
      username = "USER"
      password = "PASSWORD"
    }
  }
}

이 방식이 잘 맞는 경우

• 앱이 파일 로그를 남긴다

• 컨테이너별로 수집 책임을 느슨하게 분리하고 싶다

• 나중에 파싱, 라벨링, 필터링을 더 붙일 가능성이 있다

• “앱 + 보조 수집기” 구조를 명확히 유지하고 싶다

방법 3. stdout 로그인데도 중앙 수집기를 쓰고 싶다면 Alloy + Docker daemon 방식도 가능하다

Alloy 설정 예시

discovery.docker "containers" {
  host = "unix:///var/run/docker.sock"
}

discovery.relabel "api_only" {
  targets = discovery.docker.containers.targets

  rule {
    source_labels = ["__meta_docker_container_label_logging_job"]
    action        = "keep"
    regex         = "api"
  }

  rule {
    source_labels = ["__meta_docker_container_name"]
    target_label  = "container"
  }

  rule {
    target_label = "job"
    replacement  = "api"
  }
}

loki.source.docker "api" {
  host          = "unix:///var/run/docker.sock"
  targets       = discovery.relabel.api_only.output
  labels        = { env = "prod" }
  forward_to    = [loki.write.remote.receiver]
}

loki.write "remote" {
  endpoint {
    url = "https://loki.example.com/loki/api/v1/push"

    basic_auth {
      username = "USER"
      password = "PASSWORD"
    }
  }
}

services:
  api:
    image: your-api:latest
    labels:
      logging_job: api

그런데 이 방식은 왜 1순위가 아닐까

self-hosted Loki를 서버에 둘 때 꼭 알아둘 점

그래서 내 선택은?

1. 가장 추천하는 기본값

2. 사이드카가 정말 필요한 경우

3. 중앙에서 유연하게 관리하고 싶을 때

마무리

• stdout 로그라면 Docker logging driver가 가장 실용적이고

• 파일 로그라면 Alloy 수집 컨테이너가 자연스럽고

• 정교한 수집 제어가 필요하면 Alloy가 더 유연하다