MOMIN09Platform & DevOps

로그 분석기 개발

8 min read

Step 4: 로그 분석기 개발 (4주차)

목표

  • 3주차 설계·샘플을 바탕으로 규칙만으로 AnalyzeLogResponse 형태의 구조화 결과를 생성
  • 원인 분리를 위해 AI(LLM)는 사용하지 않음

병합된 상세 노트

GC 덤프 분석기

원본: GC 덤프 분석기 (내부 문서)

항목내용
문서 버전1.0
작성 기준일2026-05-11
상태Step 4 완료 (실제 로그 예시 포함)
근거 문서lena-ts-log-analysis(README·CONTRACT·REQUIREMENTS), dev-docs(19), shared-contracts

1. 개요

1.1 목적

본 문서는 GC 로그 분석 기능의 핵심 로직 구현과 시스템 전체 통합 과정을 기록한다. JVM GC 로그를 정규식 기반으로 분석하여 구조화된 진단 결과를 제공하고, 챗봇 에이전트와 연동하는 것을 목표로 한다.

1.2 핵심 가치

  • AI 의존도를 낮추고 신뢰할 수 있는 규칙(Rule-based)에 근거한 전문가 수준의 진단 제공
  • JVM GC 로그를 정규식 기반으로 분석하여 구조화된 진단 결과를 제공
  • 챗봇 에이전트와 연동하여 파일 업로드 기반 자동 분석 지원

2. 구현된 분석 패턴 (Pattern Detection)

총 7가지 이상의 핵심 패턴을 감지하며, 각각의 심각도(Severity)에 따른 권장 조치를 제공한다.

2.1 감지 패턴 목록

패턴명심각도감지 기준 (Regex/Keyword)권장 조치 요약
Full GCHIGH[Full GC, Full GC (Ergonomics)힙 크기 검토 및 메모리 누수 점검
Long PauseHIGH정지 시간 > 1.0초GC 튜닝 및 애플리케이션 병목 확인
Promotion FailedHIGHpromotion failedOld Gen 공간 증설 및 객체 생존 주기 분석
Concurrent FailureHIGHconcurrent mode failureCMS/G1 설정 최적화
Allocation FailureMEDIUMAllocation FailureYoung 영역 크기 및 객체 할당 속도 점검
Metaspace FullMEDIUMMetaspaceMaxMetaspaceSize 설정 확인
Minor GCINFO일반 [GC 패턴정상 활동 모니터링

3. 시스템 통합 (System Integration)

3.1 에이전트 파일 읽기 연동

  • 기능: 사용자가 채팅창에 업로드한 파일을 에이전트가 직접 읽을 수 있도록 전용 API(GET /chat-content/{file_id})를 구현함.
  • 자동화: 파일 확장자(.log, .txt)를 인식하여 자동으로 GC 분석 로직을 호출하도록 에이전트 엔진 고도화.

3.2 데이터베이스(MySQL) 연동

  • 목적: 대용량 파일 업로드 시 메타데이터를 안정적으로 관리.
  • 해결: MySQL 8 보안 인증(sha2) 이슈를 cryptography 패키지 추가를 통해 해결하고, docker-compose 환경 변수를 일괄 정비함.

3.3 프론트엔드 최적화

  • Vite Proxy: /api/v1/log-analysis 경로를 분석기 서비스(8102)로 직접 라우팅하여 성능 및 연동성 확보.

4. 검증 결과

항목내용
테스트 세트정상/주의/장애 상황을 아우르는 10가지 시나리오 로그 생성 및 검증 완료
UI 동작파일 업로드 → 에이전트 전달 → 분석 결과 출력의 전체 흐름(End-to-End) 확인

5. 상세 코드 변경 로그 (Detailed Code Changes)

5.1 분석 엔진 및 API (log-analysis 서비스)

파일변경 내용
services/analyzer.py_analyze_gc 메서드 신규 구현: 정규식 기반 패턴 감지 로직 추가. analyze 메인 메서드에 GC 타입 분기 처리 통합.
routers/chat_upload.pyGET /chat-content/{file_id} 엔드포인트 추가: 업로드된 파일의 본문을 읽어오는 기능.
services/chat_upload_store.pyget_record(file_id) 메서드 추가: DB에서 파일 메타데이터를 조회하는 로직 구현 (MySQL/SQLite 공통).

5.2 에이전트 엔진 (agent-engine 서비스)

파일변경 내용
ax-workshop/agent-engine/app/main.pyworkshop_invoke 로직 수정: file_id가 전달될 경우 로그 분석기의 본문 가져오기 API를 호출하도록 징검다리 로직 추가. 파일 확장자에 따른 log_type (GC, THREAD_DUMP 등) 자동 판별 로직 추가.

5.3 인프라 및 환경 설정

파일변경 내용
docker-compose.ymllog-analysis 서비스에 MySQL 접속 정보(LOG_ANALYSIS_MYSQL_*) 환경 변수 주입.
frontend/vite.config.tsVite 개발 서버 프록시 설정에 /api/v1/log-analysis 전용 경로 추가 (8102 포트 직접 연결).
requirements.txtMySQL 8 보안 인증 지원을 위한 cryptography 패키지 명시.

6. 주요 API 명세 (API Specifications)

6.1 로그 분석기 전용 (Port: 8102)

기능엔드포인트설명
로그 분석POST /api/v1/log-analysis/analyze로그 본문을 직접 분석
파일 업로드POST /api/v1/log-analysis/chat-upload분석용 파일 업로드 및 ID 발급
본문 조회GET /api/v1/log-analysis/chat-content/{file_id}업로드된 파일 내용 확인
헬스체크GET /api/v1/log-analysis/health서비스 및 DB 상태 확인

6.2 통합 및 에이전트 (Port: 8100/8101)

기능엔드포인트설명
에이전트 채팅POST /api/v1/chat에이전트 대화 및 파일 기반 분석 요청
분석 프록시POST /api/v1/workshop/proxy/analyzeBFF를 통한 간접 분석 요청

7. API 호출 예시 (Request & Response Examples)

7.1 정상 Young GC 분석 (gc_sample_1_normal.log)

Request (curl):

curl -X POST http://localhost:8102/api/v1/log-analysis/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "log_type": "GC",
    "content": "[2024-05-11T10:00:01.000+0900] [GC (Allocation Failure) [PSYoungGen: 512K->64K(1024K)] 512K->128K(4096K), 0.0152340 secs]"
  }'

Response:

{
  "log_type": "GC",
  "summary": "GC 로그에서 1개의 대표 패턴을 감지했다.",
  "detected_patterns": ["YOUNG_GC"],
  "signals": [
    {
      "code": "YOUNG_GC",
      "severity": "INFO",
      "message": "Minor GC(Young 영역 수집) 활동이 감지되었다."
    }
  ],
  "recommended_actions": [
    "일시적인 Young GC는 정상이지만, 빈도가 너무 잦다면 Young 영역 크기 조절을 검토한다."
  ],
  "parser_version": "0.2.0-rules"
}

7.2 긴 정지 시간 발생 (gc_sample_3_long_pause.log)

Request (curl):

curl -X POST http://localhost:8102/api/v1/log-analysis/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "log_type": "GC",
    "content": "GC(316) Pause Young (Mixed) (G1 Evacuation Pause) 6642M->5421M(8192M) 2812.421ms"
  }'

Response:

{
  "log_type": "GC",
  "summary": "GC 로그에서 1개의 대표 패턴을 감지했다.",
  "detected_patterns": ["LONG_PAUSE"],
  "signals": [
    {
      "code": "LONG_PAUSE",
      "severity": "HIGH",
      "message": "GC 정지 시간이 1초(임계치)를 초과한 2.812s가 감지되었다."
    }
  ],
  "recommended_actions": [
    "정지 시간이 매우 길어 서비스 지연이 우려된다. GC 튜닝 옵션을 검토하거나 힙 크기 적절성을 확인한다."
  ],
  "parser_version": "0.2.0-rules"
}

7.3 파일 업로드 (chat-upload)

Request (curl):

curl -X POST http://localhost:8102/api/v1/log-analysis/chat-upload \
  -F "file=@{PROJECT_DIR}/Step4/LogExample/gc_sample_1_normal.log"

Response:

{
  "ok": true,
  "file_id": "file_8a2b3c4d5e6f...",
  "original_name": "gc_sample_1_normal.log",
  "stored_name": "file_8a2b3c4d5e6f..._gc_sample_1_normal.log",
  "size": 256,
  "content_type": "text/plain",
  "uploaded_at": "2024-05-12T00:50:00.123456"
}

7.4 업로드된 파일 본문 조회 (chat-content)

Request (curl):

curl -X GET http://localhost:8102/api/v1/log-analysis/chat-content/file_8a2b3c4d5e6f...

Response:

{
  "ok": true,
  "content": "[2024-05-11T10:00:01.000+0900] [GC (Allocation Failure) ...]",
  "original_name": "gc_sample_1_normal.log"
}

그래프 뷰