사용 가능 플랜: Entry, Enterprise, Enterprise Advanced(Professional 제외)

이 가이드는 기존 Prometheus와 Grafana 성능 모니터링 배포를 확장하여 중앙 집중식 로그 집계를 위한 Grafana Loki를 추가하는 방법을 설명합니다. Prometheus가 메트릭(CPU, 요청 지연 시간, goroutine 수)을 수집하는 반면, Loki는 로그를 수집합니다. 이를 통해 운영 팀은 단일 Grafana 인터페이스에서 모든 서버에 걸친 Mattermost 애플리케이션 로그를 검색, 필터링, 상관 분석할 수 있습니다.

Loki를 도입하면 다음이 가능합니다.

• Grafana에서 모든 애플리케이션 서버의 Mattermost 로그를 검색합니다.
• 로그 레벨, HTTP 상태 코드 또는 자유 텍스트 검색으로 필터링합니다.
• 반복적으로 발생하는 상위 오류 및 경고를 식별합니다.
• 동일한 타임라인에서 로그 이벤트와 Prometheus 메트릭 스파이크를 연관 지을 수 있습니다.
• 선택적으로 애플리케이션 로그와 함께 PostgreSQL 데이터베이스 로그를 수집합니다.

아키텍처 개요#

이 배포는 모니터링 스택에 두 가지 구성 요소를 추가합니다.

• Loki — 기존 Grafana/Prometheus 모니터링 서버에 설치되는 로그 집계 엔진입니다.
• OpenTelemetry Collector — 로그를 전송하기 위해 각 Mattermost 애플리케이션 서버에 설치되는 범용 산업 표준 에이전트입니다.

┌──────────────────────┐       ┌──────────────────────┐
│  Mattermost App 01   │       │  Mattermost App 02   │
│                      │       │                      │
│  /opt/mattermost/    │       │  /opt/mattermost/    │
│   logs/mattermost.log│       │   logs/mattermost.log│
│         │            │       │         │            │
│    [ OTel Col ]      │       │    [ OTel Col ]      │
└─────────┬────────────┘       └─────────┬────────────┘
          │ push (:3100/otlp)            │
          ▼                              ▼
┌─────────────────────────────────────────────────────┐
│           Monitoring Server                         │
│                                                     │
│   [ Prometheus :9090 ]    [ Loki :3100 ]            │
│           │                     │                   │
│           └──────┬──────────────┘                   │
│                  ▼                                  │
│           [ Grafana :3000 ]                         │
│            Metrics + Logs                           │
└─────────────────────────────────────────────────────┘

Optional: Add the OpenTelemetry Collector on your PostgreSQL server to also
ship database logs to Loki.

사전 요구 사항#

시작하기 전에 다음을 확인하세요.

• 성능 모니터링 가이드에 따라 Prometheus와 Grafana가 배포되어 Mattermost 메트릭을 수집 중입니다.
• 모니터링 서버 및 각 Mattermost 애플리케이션 서버에 대한 sudo 권한이 있는 SSH 접근 권한이 있습니다.
• Mattermost가 /opt/mattermost(기본 위치)에 설치되어 있습니다. 설치 경로가 다른 경우 /opt/mattermost가 나오는 곳마다 해당 경로로 대체하세요.
• 네트워크 연결: 각 Mattermost 서버가 TCP 포트 3100(Loki의 HTTP API)을 통해 모니터링 서버에 접근할 수 있습니다.

1단계: Mattermost JSON 로깅 확인#

Loki 쿼리가 작동하려면 Mattermost가 JSON 형식의 파일 로그를 기록하고 있어야 합니다. 이는 모든 플랜에서 기본값입니다. 각 애플리케이션 서버에서 확인하세요.

tail -1 /opt/mattermost/logs/mattermost.log

JSON 형식의 줄은 다음과 같습니다.

{"timestamp":"2025-01-15T14:32:01.123Z","level":"info","msg":"Server is listening on [::]:8065","caller":"app/server.go:482"}

대신 일반 텍스트 출력이 보이면 System Console > Environment > Logging으로 이동하여 JSON 형식으로 파일에 로그 출력을 true로 설정한 후 Mattermost를 재시작하세요.

sudo systemctl restart mattermost

2단계: 모니터링 서버에 Loki 설치#

Grafana와 Prometheus가 실행 중인 서버에 Loki를 설치합니다. 이 섹션의 모든 명령은 모니터링 서버에서 실행합니다.

1. Loki 사용자와 디렉터리를 생성하고 바이너리를 다운로드하세요.

   # Create a dedicated system user
   sudo useradd --system --no-create-home --shell /bin/false loki
   
   # Create directories
   sudo mkdir -p /opt/loki/data /opt/loki/bin
   
   # Download and extract Loki
   sudo apt-get install -y unzip
   cd /tmp
   curl -LO https://github.com/grafana/loki/releases/download/v3.4.2/loki-linux-amd64.zip
   unzip loki-linux-amd64.zip
   sudo mv loki-linux-amd64 /opt/loki/bin/loki
   sudo chmod +x /opt/loki/bin/loki
   

2. 프로덕션 구성 파일을 다운로드하고 설치하세요.

   • loki-config.yaml 다운로드

   sudo cp loki-config.yaml /opt/loki/loki-config.yaml
   

   팁

   로그 보존 기간은 기본적으로 14일로 설정됩니다. 이를 변경하려면 /opt/loki/loki-config.yaml을 편집하고 limits_config 아래의 retention_period 값을 업데이트하세요. Loki는 이 값을 시간 단위로 요구하며, 일반적인 값은 다음과 같습니다.

   • 336h = 14일 (기본값)
   • 720h = 30일
   • 2160h = 90일
   • 8760h = 365일

   보존 기간이 길수록 디스크 사용량이 증가합니다. 대략적인 기준으로, 중간 정도로 활성화된 Mattermost 배포의 경우 하루 1–3 GB를 예상하세요(로그 볼륨에 따라 다릅니다). 첫 주가 지난 후 /opt/loki/data/를 모니터링하여 스토리지 필요량을 예측하세요. 보존 정책이 적용되려면 compactor.retention_enabled 설정이 true여야 합니다.

3. 소유권을 설정하세요.

   sudo chown -R loki:loki /opt/loki
   

4. systemd 서비스 파일을 생성하세요.

   sudo tee /etc/systemd/system/loki.service > /dev/null <<'EOF'
   [Unit]
   Description=Grafana Loki Log Aggregation
   Documentation=https://grafana.com/docs/loki/latest/
   After=network-online.target
   Wants=network-online.target
   
   [Service]
   Type=simple
   User=loki
   Group=loki
   ExecStart=/opt/loki/bin/loki -config.file=/opt/loki/loki-config.yaml
   Restart=on-failure
   RestartSec=5
   LimitNOFILE=65536
   StandardOutput=journal
   StandardError=journal
   
   [Install]
   WantedBy=multi-user.target
   EOF
   

5. Loki를 시작하세요.

   sudo systemctl daemon-reload
   sudo systemctl enable --now loki
   

6. Loki가 실행 중인지 확인하세요.

   sudo systemctl status loki
   curl -s http://localhost:3100/ready
   

   /ready 엔드포인트는 ready를 반환해야 합니다. Loki는 시작 후 ready를 보고하기까지 15–20초가 걸릴 수 있으며, 이 워밍업 지연은 정상입니다.

3단계: 각 Mattermost 서버에 OpenTelemetry Collector 설치#

OpenTelemetry(OTel) Collector는 각 Mattermost 애플리케이션 서버에서 실행되며 로그를 Loki로 푸시합니다. 모든 Mattermost 애플리케이션 서버에서 이 단계를 반복하세요.

1. OTel Collector Contrib 배포판을 설치하세요.

   # Add OTel Collector repository and install
   # Commands below are for Ubuntu/Debian
   wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.145.0/otelcol-contrib_0.145.0_linux_amd64.deb
   sudo dpkg -i otelcol-contrib_0.145.0_linux_amd64.deb
   

   참고

   설치 과정에서 otelcol-contrib라는 시스템 사용자와 그룹이 자동으로 생성됩니다.

2. OpenTelemetry Collector 구성을 다운로드하고 편집하세요.

   • otel-collector-config-mattermost.yaml 다운로드

   sudo cp otel-collector-config-mattermost.yaml /etc/otelcol-contrib/config.yaml
   

   /etc/otelcol-contrib/config.yaml을 편집하고 플레이스홀더를 교체하세요.

   • 를 모니터링 서버 주소로 교체하세요.
   • 을 이 서버의 호스트명으로 교체하세요.
   • 을 서비스 유형(예: mattermost)으로 교체하세요.

   sudo vi /etc/otelcol-contrib/config.yaml
   

3. Collector에 Mattermost 로그 디렉터리 읽기 권한을 부여하세요.

   # Grant the collector access to read Mattermost logs.
   # Substitute 'mattermost' for the group that owns your log file.
   sudo usermod -aG mattermost otelcol-contrib
   
   # Ensure logs are group-readable
   sudo chmod 640 /opt/mattermost/logs/mattermost.log
   sudo chmod g+rx /opt/mattermost/logs
   

4. 서비스를 재시작하세요.

   sudo systemctl restart otelcol-contrib
   sudo systemctl enable otelcol-contrib
   

5. Collector가 실행 중이고 로그를 전송하는지 확인하세요.

   sudo systemctl status otelcol-contrib
   sudo journalctl -u otelcol-contrib -f
   

4단계: Grafana에 Loki 데이터 소스 추가#

1. Grafana에 로그인하세요(기본값: http://<monitoring-server>:3000).
2. Administration > Data Sources > Add data source로 이동하세요.
3. 목록에서 Loki를 선택하세요.
4. 연결을 구성하세요.
   • 이름: Loki
   • URL: http://localhost:3100 (Loki가 Grafana와 같은 서버에 있으므로)
5. 저장 및 테스트를 선택하세요. Grafana가 데이터 소스가 작동 중임을 확인해 줍니다.

5단계: Mattermost Loki 대시보드 가져오기#

로그 모니터링에는 미리 구성된 Grafana 대시보드 사용을 권장합니다. 이 대시보드는 기본 예시로 제공됩니다.

• Mattermost Loki Logs 대시보드 JSON 다운로드

대시보드는 다음을 제공합니다.

• 심각도별 로그 볼륨 — 심각도별 로그 비율을 보여 주는 누적 막대 차트입니다.
• 오류 / 경고 / 전체 카운터 — 선택한 시간 범위에 대한 통계 패널입니다.
• HTTP 4xx/5xx 수 — 애플리케이션 수준 HTTP 오류를 빠르게 파악할 수 있습니다.
• 시간별 오류율 — 오류 스파이크를 찾기 위한 인스턴스별 시계열입니다.
• 상위 오류 메시지 — 가장 빈번한 오류의 순위를 보여 주는 테이블입니다.
• 로그 브라우저 — 레벨 및 자유 텍스트 변수를 갖춘 검색 및 필터링 가능한 로그 패널입니다.

대시보드를 가져오려면 다음을 따르세요.

1. Grafana에서 Dashboards > New > Import로 이동하세요.
2. Upload JSON file을 선택하고 다운로드한 mattermost-loki-logs.json 파일을 선택하세요.
3. 가져오기 화면에서 드롭다운 목록의 Loki 데이터 소스를 선택하세요.
4. Import를 선택하세요.

6단계: 유용한 LogQL 쿼리#

다음 쿼리를 Grafana Explore(Loki 데이터 소스 선택)에서 직접 실행하거나 추가 대시보드 패널을 만드는 데 사용할 수 있습니다.

모든 Mattermost 로그 검색:

{service_name="mattermost"}

로그 레벨로 필터링:

{service_name="mattermost"} | json | detected_level="error"

모든 HTTP 4xx 응답 검색:

{service_name="mattermost"} | json | status_code >= 400

모든 HTTP 5xx 응답 검색:

{service_name="mattermost"} | json | status_code >= 500

5분 윈도우별 상위 5개 오류 메시지:

topk(5, sum(count_over_time({service_name="mattermost"} | json | detected_level="error" [5m])) by (msg))

5분 윈도우별 메시지별 오류 수:

sum(count_over_time({service_name="mattermost"} | json | detected_level="error" [5m])) by (msg)

자유 텍스트 검색(예: 플러그인 오류):

{service_name="mattermost"} |~ "plugin"

인증 관련 로그 줄:

{service_name="mattermost"} |~ "(?i)(auth|login|token|session)"

특정 서버 인스턴스의 로그:

{service_name="mattermost", service_instance_id="mm-app-01"}

선택 사항: PostgreSQL 로그 수집 추가#

PostgreSQL 데이터베이스가 전용 서버(RDS 아님)에서 실행되는 경우 해당 로그도 Loki로 전송할 수 있습니다. 이는 느린 쿼리나 데이터베이스 오류를 Mattermost 애플리케이션 이벤트와 연관 짓는 데 유용합니다.

실행되면 PostgreSQL 로그는 Grafana에서 {service_name="postgres"} 레이블로 표시됩니다.

{service_name="postgres"} | json | detected_level="error"

검증 및 문제 해결#

엔드투엔드 검증 체크리스트:

1. Loki가 정상 상태인지 확인하세요.

   curl -s http://<monitoring-server>:3100/ready
   # Expected: "ready"
   

2. OpenTelemetry Collector가 로그를 전송 중인지 확인하세요(각 Mattermost 서버에서 실행).

   sudo journalctl -u otelcol-contrib -n 100
   # Look for export successful messages or lack of errors
   

3. Grafana에서 로그가 보이는지 확인하세요. Explore로 이동하여 Loki 데이터 소스를 선택한 후 {service_name="mattermost"}를 실행하세요. 최근 로그 줄이 표시되어야 합니다.

4. 대시보드가 로드되는지 확인하세요. Mattermost Log Aggregation 대시보드를 열고 패널에 데이터가 채워졌는지 확인하세요. (참고: service_name 및 service_instance_id를 사용하도록 대시보드 쿼리를 업데이트해야 할 수 있습니다.)

일반적인 문제: