DOCS/docs/troubleshooting/20250714_system_metrics_implementation.md

시스템 메트릭 구현 트러블슈팅

개요

• 날짜: 2025-07-14
• 작업: 관리자 대시보드에 시스템 메트릭 그래프 추가
• 목표: PostgreSQL + TimescaleDB 기반 시계열 데이터 수집 및 Chart.js 그래프 표시

주요 문제들과 해결 과정

1. Docker 네트워크 통신 문제

문제: 관리자 대시보드에서 모든 서비스가 timeout/unreachable 상태 원인: Docker 컨테이너간 네트워크 격리 (DOCKER-ISOLATION iptables 체인) 해결:

• 서비스 URL을 IP 주소에서 컨테이너 이름으로 변경
• http://172.17.0.2:5173 → http://frontend:5173
• http://172.17.0.1:10508 → http://rb10508_test:10508

2. TimescaleDB 설치 및 설정

문제: PostgreSQL에 TimescaleDB 확장 설치 필요 해결:

# TimescaleDB 확장 설치
sudo apt-get update
sudo apt-get install timescaledb-2-postgresql-15

# 데이터베이스 생성 및 확장 활성화
sudo -u postgres createdb robing_metrics
sudo -u postgres psql robing_metrics -c "CREATE EXTENSION IF NOT EXISTS timescaledb;"

3. HDD 저장소 설정

문제: 메트릭 데이터를 HDD에 저장하기 위한 테이블스페이스 생성 해결:

-- HDD 테이블스페이스 생성
CREATE TABLESPACE hdd_tablespace LOCATION '/hdd/postgresql_data';

-- 테이블 생성시 HDD 테이블스페이스 사용
CREATE TABLE system_metrics (
    time TIMESTAMPTZ NOT NULL,
    metric_type VARCHAR(50) NOT NULL,
    value DOUBLE PRECISION NOT NULL,
    hostname VARCHAR(100) DEFAULT 'localhost'
) TABLESPACE hdd_tablespace;

4. PostgreSQL 연결 인증 문제

문제: Docker 컨테이너에서 PostgreSQL 접속 시 password authentication failed 원인: PostgreSQL 사용자 비밀번호 미설정 해결:

# PostgreSQL 비밀번호 설정
sudo -u postgres psql -c "ALTER USER postgres PASSWORD '19800508';"

# docker-compose.yml에 환경변수 추가
environment:
  - METRICS_DB_PASSWORD=19800508

5. 테이블 구조 불일치 문제

문제:

• 로그: column "timestamp" of relation "system_metrics" does not exist
• 실제 테이블: time 컬럼 존재, timestamp 컬럼 없음

원인: 코드와 데이터베이스 스키마 불일치 해결 과정:

1. 기존 테이블 구조 확인:

   \d system_metrics
   -- time (timestamptz), metric_type (varchar), value (double precision)
   

2. 코드 수정하여 기존 테이블 구조에 맞춤:

   # 정규화된 구조로 데이터 삽입
   INSERT INTO system_metrics (time, metric_type, value)
   VALUES ($1, $2, $3)
   

6. 잘못된 대시보드 구현

문제: 고객용 React 앱에 시스템 메트릭을 구현함 원인: 두 개의 프론트엔드 구조 혼동

• 고객용: React SPA (/client/)
• 관리자용: 정적 HTML (/backend/admin_static/)

해결: 관리자 대시보드(정적 HTML)에 Chart.js 기반 그래프 구현

최종 구현 결과

파일 구조

backend/
├── admin_routes.py          # 관리자 API 엔드포인트
├── admin_static/
│   └── index.html          # 관리자 대시보드 (Chart.js 그래프)
├── metrics_collector.py    # 시스템 메트릭 수집기
├── metrics_database.py     # PostgreSQL 데이터베이스 연결
└── main.py                 # 메트릭 시스템 초기화

주요 기능

1. 메트릭 수집: 1분 간격으로 CPU, 메모리, 디스크, 업타임 수집
2. 데이터 저장: PostgreSQL TimescaleDB 하이퍼테이블에 시계열 데이터 저장
3. 그래프 표시: Chart.js로 1h/1d/7d/30d/90d/1y 기간별 그래프
4. 실시간 표시: 현재 메트릭 값과 진행률 바 표시

API 엔드포인트

• GET /admin/metrics/current - 현재 메트릭 조회
• GET /admin/metrics/history/{period} - 기간별 메트릭 히스토리
• POST /admin/metrics/collect - 수동 메트릭 수집

미해결 문제

현재 상태: 테이블 구조 불일치로 인한 메트릭 데이터 삽입 실패 증상: column "timestamp" of relation "system_metrics" does not exist 예상 원인: 코드 내 일부 SQL 쿼리에서 여전히 timestamp 컬럼 참조

학습 포인트

1. Docker 네트워크: 컨테이너간 통신 시 서비스 이름 사용
2. TimescaleDB: PostgreSQL 확장으로 시계열 데이터 최적화
3. 두 프론트엔드 구조: 고객용 React vs 관리자용 정적 HTML 구분
4. 데이터베이스 스키마: 코드와 실제 테이블 구조 일치 중요성
5. PostgreSQL 인증: Docker 환경에서 비밀번호 설정 필요

후속 작업

1. 테이블 구조 불일치 문제 완전 해결
2. 메트릭 데이터 수집 정상 동작 확인
3. 그래프에 실제 데이터 표시 검증
4. 성능 최적화 및 에러 핸들링 개선