WireGuard 로그·모니터링: Prometheus·Grafana 연동

개요

WireGuard는 가볍고 빠른 VPN으로 널리 사용된다. 운영 환경에서는 접속 상태, 핸드셰이크, 트래픽을 모니터링해야 안정적인 서비스 유지가 가능하다. 본문은 WireGuard 로그 수집과 Prometheus·Grafana 연동을 중심으로 구성 요소, 설정 예시, 대시보드 구성까지 실무 관점에서 설명한다. 처음 접하는 사람도 이해하기 쉽도록 단계별로 정리한다.

구성 요소와 역할

WireGuard

커널 레벨에서 동작하는 VPN으로 패킷 전송과 암호화를 담당한다. 자체적으로는 세부 지표를 외부로 노출하지 않으므로 별도의 수집기가 필요하다.

Exporter

WireGuard 지표를 Prometheus 형식으로 노출하는 컴포넌트가 필요하다. 다양한 구현체가 있으며, 주로 다음 항목을 제공한다: 전송/수신 바이트, 핸드셰이크 수, 피어 상태 등.

Prometheus

지표 수집과 저장을 담당한다. Exporter가 노출하는 /metrics 엔드포인트를 스크랩하도록 설정하면 시계열 데이터로 보관된다.

Grafana

저장된 데이터를 시각화한다. 쿼리 기반으로 패널을 만들고 알람을 연동하면 운영에 쓸 수 있는 대시보드가 완성된다.

WireGuard 로그 수집 방식

WireGuard 자체는 커널에서 동작하므로 표준 로그가 제한적이다. 운영 환경에서는 다음 방법을 병행한다.

• 커널 로그: dmesg나 journald에서 관련 메시지 확인.
• wg-quick 훅: PostUp/PostDown 또는 PostUp/PostDown에 logger를 이용해 연결 이벤트 기록.
• Exporter 지표: 접속 여부와 트래픽을 메트릭으로 변환해 수집.

가벼운 연결 이벤트 로깅은 wg-quick 설정에 훅을 추가하는 방식으로 구현 가능하다. 예시:

[Interface]
PostUp = logger -t wireguard "wg interface up: %i"
PostDown = logger -t wireguard "wg interface down: %i"

Prometheus 연동 예시

Exporter를 설치한 뒤 Prometheus의 scrape_configs에 항목을 추가하면 된다. 일반적인 YAML 예시는 다음과 같다.

scrape_configs:
  - job_name: 'wireguard'
    static_configs:
      - targets: ['127.0.0.1:9614']

Exporter는 기본 포트(예: 9614)를 사용하거나 설정에 따라 변경된다. Prometheus 설정을 적용한 뒤 서비스가 exporter를 정상적으로 스크랩하는지 /targets 페이지에서 확인한다.

Exporter 설치와 서비스 예시

간단한 systemd 유닛 예시는 다음과 같다. 바이너리 경로와 옵션은 사용하는 구현체에 맞춰 조정한다.

[Unit]
Description=WireGuard Exporter
After=network.target

[Service]
User=nobody
ExecStart=/usr/local/bin/wireguard-exporter --listen-address=:9614
Restart=on-failure

[Install]
WantedBy=multi-user.target

Grafana 대시보드 구성

대시보드는 기본적으로 다음 패널을 포함하면 유용하다.

• 피어별 전송량(tx/rx) — 쿼리 예: sum(rate(wireguard_peer_tx_bytes_total[5m])) by (peer)
• 핸드셰이크 빈도 — 쿼리 예: rate(wireguard_peer_handshakes_total[5m])
• 피어 연결 상태(업/다운) — exporter가 노출하는 상태 메트릭 활용
• 전체 트래픽 추이 — sum(rate(...) ) 형태의 롤업 그래프

패널 설정 시 레이블(peer, interface 등)을 활용하면 특정 피어나 인터페이스에 대한 세부 모니터링이 가능하다. 알람 조건은 장시간 트래픽 저하, 핸드셰이크 실패 증가, 피어 비가용 등을 기준으로 구성한다.

대시보드 예시 쿼리와 설명

• 피어별 TX:

  sum(rate(wireguard_peer_tx_bytes_total[5m])) by (peer)

• 피어별 RX:

  sum(rate(wireguard_peer_rx_bytes_total[5m])) by (peer)

• 핸드셰이크 오류 모니터링:

  increase(wireguard_peer_handshakes_total[1h])

쿼리의 집계 기간과 레이블 분해 수준은 환경 특성에 맞춰 조정한다. 빈번한 샘플링은 저장소 사용량을 증가시키므로 보존 정책과 리텐션을 고려한다.

운영 관점 권장 사항

• 지표 컬렉션 주기는 트래픽 패턴과 저장 용량을 기준으로 결정.
• 핸드셰이크 관련 알람은 단기 스퍼이크보다 지속적인 이상 패턴 감지 중심으로 설정.
• 로그와 메트릭을 함께 수집하면 문제 원인 파악이 수월해짐.
• 대시보드 템플릿을 만들어 신규 노드에 빠르게 적용.

문제 해결 사례

예를 들어 특정 피어에서 트래픽이 급감할 때는 다음 항목을 확인한다. 네트워크 경로, 방화벽 규칙, 피어의 키 교체 여부, 핸드셰이크 실패 로그 등이다. 메트릭으로는 tx/rx 변화와 핸드셰이크 실패율을 우선 확인하면 원인 범위를 좁힐 수 있다.

마무리

WireGuard 모니터링은 로그 수집과 메트릭 수집을 병행할 때 가장 효과적이다. Exporter로 핵심 지표를 Prometheus에 적재하고, Grafana에서 직관적인 대시보드를 구성하면 운영 가시성이 크게 개선된다. 본문에 제시한 설정 예시를 환경에 맞춰 적용하면 빠르게 모니터링 체계를 갖출 수 있다.