관측성 기본선 구축: 메트릭·probe·대시보드·알림 추가

[ckdals4600]

관련 이슈

• close 관측성 기본선 구축: health/readiness/liveness/metrics #239

PR 설명

운영 관측성 기본선을 구축했습니다. 로그에 의존하지 않고 메트릭/대시보드/알림으로
시스템 상태를 파악할 수 있도록, 지표 수집부터 시각화·알림까지 추가했습니다.

배경

• 기존에는 로그는 많지만 표준 상태 신호·메트릭이 부족했다.
• health endpoint 가 문자열 OK 응답뿐이고 readiness/liveness, 메트릭 활용이 없었다.
• 배포 이후 장애(응답 지연·에러율·AI 호출 실패·비동기 실패)를 감지할 수단이 없었다.

변경 사항

메트릭 수집 (코드)

• AI 호출 결과 메트릭 ai_client_calls_total{client, operation, result} 추가
  (answer/title/summary/link-sync, success/empty/failure)
• 비동기 작업 최종 실패 메트릭 async_task_failures_total{task, action} 추가
  (재시도 소진 후 @Recover/catch 지점)
• 카운터는 앱 시작 시 0으로 미리 등록 → 첫 발생 전에도 시계열 존재(그래프·알림 안정화)
• (부수) RagAnswerClient 빈 응답 시 IndexOutOfBounds 발생하던 버그 수정

Actuator 설정

• http.server.requests 히스토그램 활성화 → p95/p99 지연 측정
• tomcat·hikaricp·jvm 등 핵심 메트릭 노출
• readiness/liveness probe 활성화

시각화 (Grafana)

• AI/비동기 전용 대시보드 추가: AI 실패율·호출량·비동기 최종 실패 패널
• 프로비저닝 폴더에 추가하여 자동 로드 (기존 HTTP 대시보드와 별도)

모니터링·알림 (인프라)

• Prometheus 알림 룰 추가: 5xx 에러율, p95 지연, AI 실패율, 비동기 최종 실패, 인스턴스 다운
• Alertmanager 구성 추가, alerting/ 폴더로 룰·설정 분리
• prometheus·alertmanager 호스트 포트 미노출 → 외부 접근 차단

테스트

• MeterRegistry 의존성 추가로 깨진 단위 테스트 수정
• mock 대신 SimpleMeterRegistry 사용, @PostConstruct 미호출 구간은 카운터 수동 등록
• AI 클라이언트·이벤트 리스너·워커 테스트 정상화 및 카운터 검증 추가

확인

• /actuator/prometheus 에서 ai_client_calls_total, async_task_failures_total 노출 확인
• Grafana 'Linkiving AI / Async Overview' 대시보드 데이터 확인
• Grafana 'Linkiving HTTP Overview' 대시보드(요청수·에러율·p95) 데이터 확인
• Prometheus Status→Rules 에서 알림 룰 로드 확인
• ./gradlew test 전체 통과

[ckdals4600]

Alertmanager 전달 경로 연결의 경우 확정 이후 작업 진행하도록 하겠습니다.

[github-actions]

📊 코드 커버리지 리포트

Overall Project	94.32% -0.28%	🍏
Files changed	95.5%	🍏

File	Coverage
LinkEventListener.java	100%	🍏
LinkSyncEventListener.java	100%	🍏
RagAnswerClient.java	100%	🍏
SummaryWorker.java	100%	🍏
RagSummaryClient.java	96.69% -1.99%	🍏
RagTitleClient.java	94.12%	🍏
RagLinkSyncClient.java	89.83% -10.17%	🍏