dpdpdndn 블로그

BE-06-incident-analysis-gateway-impl

NEW2 min read

[BE-06] IncidentAnalysisGatewayImpl (Claude LLM 원인분석)

⚠️ SUPERSEDED (2026-07-06): LLM 원인분석 제거로 이 티켓은 폐기됨. process 단계는 텔레메트리 원지표 조회·첨부로 대체(별도 구현 완료). 아래 본문은 이력으로 보존한다.

작업 내용 (설계 의도)

변경 사항

IncidentAnalysisGateway(BE-01 interface)를 Claude API HTTP 호출로 구현한다(ADR-002, FR-4/FR-5). 근거 TDD: ../TDD.md §Detail Design·§실패경로.

  • infrastructure/alerting/gateway/IncidentAnalysisGatewayImpl.kt — analyze(context)에서 TelemetrySnapshot+signal을 프롬프트로 구성해 Claude API 호출, 응답을 IncidentAnalysis(errorType/causeEstimation/remediation) 도메인 타입으로 변환.
  • Client는 GatewayImpl에만 DI — Claude HTTP client(ClaudeClient)는 infra에 정의, 요청/응답 DTO는 infra에 둠.
  • 긴 타임아웃: ExternalRestClientFactory의 5초는 부족 → GatewayImpl이 자체 RestClient.Builder로 긴 read timeout(예: 55초, NFR 60초 내)을 구성(공유 팩토리 미변경 — Single Writer 회피).
  • 타임아웃·5xx·파싱 실패 시 IncidentAnalysisException을 던진다(폴백 결정은 도메인 몫, FR-8).
  • 모델·키·타임아웃은 LlmProperties(@ConfigurationProperties) 신규, 키는 ALERTING_LLM_API_KEY env.

롤백: ALERTING_LLM_API_KEY 언셋 시 게이트웨이가 예외 → 도메인 폴백(발송 유지).

의존

  • BE-01 (IncidentAnalysisGateway interface, IncidentContext, IncidentAnalysis)

다이어그램

처리 흐름

sequenceDiagram
    participant G as IncidentAnalysisGatewayImpl
    participant C as ClaudeClient
    participant LLM as Claude API
    G->>C: analyze(prompt(context))
    C->>LLM: POST /messages (long timeout)
    LLM-->>C: 분석 텍스트
    C-->>G: IncidentAnalysis 또는 IncidentAnalysisException

테스트 케이스

  • 정상 응답을 errorType/causeEstimation/remediation으로 파싱한다(mock 서버).
  • 읽기 타임아웃 시 IncidentAnalysisException을 던진다.
  • 5xx 응답 시 IncidentAnalysisException을 던진다.
  • 응답 파싱 실패(예상 밖 포맷) 시 IncidentAnalysisException을 던진다.
  • 프롬프트에 signal(endpoint/source/severity)과 텔레메트리 요약이 포함된다.

그래프 뷰