GoAccess — 실시간 웹 로그 분석기

GoAccess는 터미널과 웹 브라우저 모두에서 동작하는 오픈소스 실시간 웹 로그 분석기입니다. Nginx, Apache, Amazon S3 등 다양한 포맷의 로그를 파싱하여 방문자 수, 요청 통계, 대역폭, 응답 시간 등을 즉시 시각화합니다. 별도 데이터베이스나 백엔드 없이 단일 바이너리로 동작하므로 운영 서버에 빠르게 설치하고 분석을 시작할 수 있습니다.

---

GoAccess 소개 및 설치

주요 특징

• 실시간 업데이트: 터미널 대시보드와 HTML 리포트 모두 WebSocket으로 실시간 갱신
• 다양한 로그 포맷 지원: Nginx combined/main, Apache combined, Amazon S3, W3C, CSV 등
• 단일 바이너리: 의존성 없이 즉시 실행 가능
• 풍부한 통계: 방문자, 요청, 상태 코드, 대역폭, 요청 시간, GeoIP 지역 정보

설치 — Debian/Ubuntu (apt)

# Ubuntu 22.04 이상
sudo apt-get update
sudo apt-get install -y goaccess

# 버전 확인
goaccess --version

최신 버전이 필요하다면 공식 저장소를 추가합니다:

# GoAccess 공식 APT 저장소 추가
echo "deb https://deb.goaccess.io/ $(lsb_release -cs) main" | \
  sudo tee /etc/apt/sources.list.d/goaccess.list
wget -O- https://deb.goaccess.io/gnugpg.key | sudo apt-key add -
sudo apt-get update
sudo apt-get install -y goaccess

설치 — macOS (Homebrew)

brew install goaccess

# GeoIP 지원 포함 설치
brew install goaccess --with-geoip

설치 — Docker

# allinea/goaccess 이미지 사용 (또는 직접 빌드)
docker pull allinea/goaccess

# 바로 실행 테스트
docker run --rm -v /var/log/nginx:/var/log/nginx allinea/goaccess \
  /var/log/nginx/access.log \
  --log-format=COMBINED \
  --no-global-config \
  -o /var/log/nginx/report.html

---

터미널 실시간 대시보드

기본 실행

# COMBINED 포맷(Nginx/Apache 기본)으로 터미널 대시보드 실행
goaccess /var/log/nginx/access.log --log-format=COMBINED

# 터미널에서 바로 stdin 파이핑
tail -f /var/log/nginx/access.log | goaccess --log-format=COMBINED -

실행 후 터미널에는 다음 섹션이 표시됩니다:

Dashboard — Overall Analyzed Requests
Visitors                   Requests              Static Requests
Unique Visitors            Not Found             Log Size
Dynamic Requests           Failed Requests       Bandwidth
...

1. Unique Visitors per Day
2. Requested Files (URLs)
3. Static Requests
4. Not Found URLs (404)
5. Visitor Hostnames and IPs
6. Operating Systems
7. Browsers
8. Time Distribution
9. Referrers URLs
10. Referring Sites
11. Key Phrases from Google's search engine
12. HTTP Status Codes
13. Geolocation

주요 키보드 단축키

키	동작
F1 / h	도움말 표시
1~9, 0	해당 섹션으로 이동
s	현재 패널 정렬 방식 변경
t / T	상위/하위 항목 토글
o	세부 패널 열기/닫기
q	종료
↑ / ↓	스크롤

실시간 스트리밍 모드

# --real-time-html 옵션과 함께 사용하면 HTML도 실시간 갱신
tail -f /var/log/nginx/access.log | goaccess \
  --log-format=COMBINED \
  --real-time-html \
  -o /var/www/html/report.html -

---

HTML 리포트 생성

정적 HTML 리포트

# 기본 HTML 리포트 생성
goaccess /var/log/nginx/access.log \
  -o /var/www/html/report.html \
  --log-format=COMBINED

# 브라우저에서 확인
# http://your-server/report.html

생성된 HTML 파일은 단독으로 동작하는 완전한 인터랙티브 대시보드입니다. JavaScript와 CSS가 모두 인라인으로 포함되어 있어 추가 파일 없이 하나의 HTML 파일만으로 동작합니다.

여러 로그 파일 병합 분석

# 로테이션된 로그 파일들을 순서대로 병합
zcat /var/log/nginx/access.log.*.gz | goaccess \
  --log-format=COMBINED \
  -o /var/www/html/monthly-report.html -

# 현재 로그와 압축 로그 함께 분석
zcat /var/log/nginx/access.log.2.gz /var/log/nginx/access.log.1.gz \
  | cat - /var/log/nginx/access.log \
  | goaccess --log-format=COMBINED -o report.html -

CSV/JSON 출력

# JSON 형식으로 출력
goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -o report.json

# CSV 형식으로 출력
goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -o report.csv

---

Nginx/Apache 로그 포맷 설정

사전 정의 포맷 키워드

GoAccess는 일반적인 포맷에 대해 미리 정의된 키워드를 제공합니다:

키워드	설명
COMBINED	Apache/Nginx combined 포맷 (가장 많이 사용)
NCSA_COMBINED	NCSA combined 포맷
COMMON	CLF (Common Log Format)
W3C	IIS W3C 확장 로그 포맷
SQUID	Squid 네이티브 포맷
CLOUDFRONT	Amazon CloudFront
CLOUDSTORAGE	Google Cloud Storage
AWSELB	Amazon Elastic Load Balancing

커스텀 포맷 지정

응답 시간이 포함된 Nginx 커스텀 포맷:

# Nginx timed 포맷 예시:
# '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent rt=$request_time'

goaccess /var/log/nginx/access.log \
  --log-format='%h - %e [%d:%t %^] "%r" %s %b rt=%T' \
  --date-format='%d/%b/%Y' \
  --time-format='%H:%M:%S'

GoAccess 설정 파일 사용

매번 옵션을 입력하는 대신 설정 파일을 사용하는 것이 편리합니다:

# /etc/goaccess/goaccess.conf (또는 ~/.goaccessrc)

# Nginx combined 포맷
log-format COMBINED

# 날짜/시간 포맷 (COMBINED에서는 자동 설정되지만 명시해도 무방)
date-format %d/%b/%Y
time-format %H:%M:%S

# 로그 파일 경로
log-file /var/log/nginx/access.log

# HTML 리포트 출력 경로
output /var/www/html/report.html

# GeoIP 데이터베이스 경로 (옵션)
# geoip-database /usr/share/GeoIP/GeoLite2-City.mmdb

# 실시간 HTML 활성화
real-time-html true
ws-url wss://your-domain.com:7890
port 7890

설정 파일 적용:

goaccess --config-file=/etc/goaccess/goaccess.conf

---

실시간 HTML 대시보드 (WebSocket)

GoAccess는 WebSocket을 통해 HTML 리포트를 실시간으로 갱신할 수 있습니다.

GoAccess 실시간 서버 실행

# WebSocket 서버 포함 실시간 HTML 생성
tail -f /var/log/nginx/access.log | goaccess \
  --log-format=COMBINED \
  --real-time-html \
  --ws-url=wss://monitor.example.com \
  --port=7890 \
  -o /var/www/html/live-report.html -

Nginx 리버스 프록시 설정 (외부 접근)

# /etc/nginx/sites-available/goaccess-monitor
server {
    listen 443 ssl;
    server_name monitor.example.com;

    ssl_certificate     /etc/letsencrypt/live/monitor.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/monitor.example.com/privkey.pem;

    # 기본 인증으로 접근 보호
    auth_basic "GoAccess Monitor";
    auth_basic_user_file /etc/nginx/.htpasswd;

    # HTML 리포트 서빙
    location / {
        root /var/www/html;
        index live-report.html;
    }

    # WebSocket 프록시
    location /ws {
        proxy_pass http://127.0.0.1:7890;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400;
    }
}

# htpasswd 파일 생성 (접근 제한)
htpasswd -c /etc/nginx/.htpasswd admin
nginx -t && systemctl reload nginx

---

Docker로 GoAccess 실행

Docker 단독 실행

# 로그 파일 마운트하여 HTML 리포트 생성
docker run --rm \
  -v /var/log/nginx:/var/log/nginx:ro \
  -v /var/www/html:/output \
  allinea/goaccess \
  /var/log/nginx/access.log \
  --log-format=COMBINED \
  --no-global-config \
  -o /output/report.html

# 생성된 리포트 확인
ls -lh /var/www/html/report.html

Docker Compose로 실시간 대시보드

# docker-compose.yml
version: '3.8'

services:
  goaccess:
    image: allinea/goaccess
    container_name: goaccess
    restart: unless-stopped
    volumes:
      - /var/log/nginx:/var/log/nginx:ro
      - ./reports:/var/www/html
    command: >
      /var/log/nginx/access.log
      --log-format=COMBINED
      --no-global-config
      --real-time-html
      --ws-url=wss://monitor.example.com
      --port=7890
      -o /var/www/html/live-report.html
    ports:
      - "7890:7890"

  nginx:
    image: nginx:alpine
    container_name: goaccess-web
    restart: unless-stopped
    volumes:
      - ./reports:/usr/share/nginx/html:ro
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    ports:
      - "8080:80"
    depends_on:
      - goaccess

---

주요 통계 항목 설명

GoAccess HTML 대시보드의 주요 섹션과 각 항목의 의미:

Summary 패널

항목	설명
Unique Visitors	동일 날짜 기준 고유 IP 수
Requests	전체 요청 수 (정적 + 동적)
Static Requests	JS, CSS, 이미지 등 정적 파일 요청
Requests w/ a 404	Not Found 응답 요청 수
Bandwidth	전송된 총 바이트
Log Size	분석된 로그 파일 크기

섹션별 주요 지표

섹션	주요 지표
1. Unique Visitors	날짜별 방문자, 요청, 대역폭, 히트율
2. Requested Files	URL별 요청 수, 대역폭, 응답 시간
4. Not Found	404 URL 목록 및 요청 빈도
5. Visitor IPs	IP별 요청 수, 대역폭
8. Time Distribution	시간대별 요청 분포 (히트맵)
12. HTTP Status Codes	상태 코드별 요청 수 비율
13. Geolocation	국가/지역별 방문자 분포

---

GeoIP 지역 통계 활성화

GeoLite2 데이터베이스 설치

# MaxMind GeoLite2 데이터베이스 다운로드 (무료, 계정 필요)
# https://www.maxmind.com/en/geolite2/signup

# geoipupdate 도구 설치
sudo apt-get install -y geoipupdate

# /etc/GeoIP.conf 설정
sudo tee /etc/GeoIP.conf <<'EOF'
AccountID YOUR_ACCOUNT_ID
LicenseKey YOUR_LICENSE_KEY
EditionIDs GeoLite2-City GeoLite2-Country
EOF

# 데이터베이스 업데이트
sudo geoipupdate
ls /var/lib/GeoIP/
# GeoLite2-City.mmdb  GeoLite2-Country.mmdb

GoAccess에 GeoIP 적용

# GeoLite2-City 데이터베이스 사용 (도시 수준 정보)
goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  --geoip-database=/var/lib/GeoIP/GeoLite2-City.mmdb \
  -o report.html

# 또는 설정 파일에 추가
# geoip-database /var/lib/GeoIP/GeoLite2-City.mmdb

---

자동 리포트 생성 cron 설정

# /etc/cron.d/goaccess-report
# 매일 새벽 2시에 전일 리포트 생성
0 2 * * * root zcat /var/log/nginx/access.log.*.gz 2>/dev/null | \
  cat /var/log/nginx/access.log.1 - | \
  goaccess --log-format=COMBINED --no-global-config \
  -o /var/www/html/reports/$(date +\%Y\%m\%d).html - 2>/dev/null

# 오래된 리포트 자동 삭제 (30일 보관)
find /var/www/html/reports/ -name "*.html" -mtime +30 -delete

---

고수 팁

포맷 자동 감지: GoAccess는 --log-format=AUTO 옵션으로 포맷을 자동 탐지하려고 시도하지만, 운영 환경에서는 명시적으로 포맷을 지정하는 것이 안정적입니다.

대용량 로그 처리: GB 단위 로그 파일도 GoAccess는 효율적으로 처리하지만, 메모리 사용량이 높아질 수 있습니다. --max-items=N 옵션으로 각 패널의 최대 항목 수를 제한하면 메모리를 절약할 수 있습니다.

지속적 데이터베이스: --db-path와 --persist / --restore 옵션을 사용하면 이전 분석 결과를 저장하고 이어서 분석할 수 있어 로테이션된 로그의 누적 통계를 관리하는 데 유용합니다.

# 데이터베이스에 결과 저장하며 분석
goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  --db-path=/tmp/goaccess-db \
  --persist \
  -o report.html

# 다음 날 이어서 분석
goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  --db-path=/tmp/goaccess-db \
  --persist \
  --restore \
  -o report.html