[Observability][P1] Server·AI Runtime 추적과 운영 지표 고도화 #26

한눈에 보기

FOWOCO의 요청이 Client → Server → AI Runtime → Task/Renewal을 지나는 동안 어디에서 얼마나 걸렸고 왜 실패했는지 개인정보 없이 확인하는 작업입니다.

단순 운영 로그가 아니라, 데모 발표의 정량적 평가와 기대효과 근거를 만드는 것이 이번 구현의 핵심입니다.

• 완료 PR: AI 파이프라인 단계별 로그와 Prometheus 지표 추가 #139

이번 구현 범위

Server 단계별 관측

• AiRun 단계별 구조화 로그
  • PLAN_RUNTIME_CALL
  • SLOT_RESOLUTION
  • ANALYZE_RUNTIME_CALL
  • RESULT_PERSIST
  • TOTAL
• Renewal 단계별 구조화 로그
  • CONTEXT_LOAD
  • RENEWAL_RUNTIME_CALL
  • DOCUMENT_GENERATION
  • RESULT_APPLY
  • TOTAL
• 성공·실패·timeout을 안전한 failure_code로 구분
• AI 응답의 model/prompt version과 AiAttempt 기록 정합성 확인

Micrometer·Prometheus

• AiRun 단계별 Timer와 결과·실패 Counter 추가
• Renewal 단계별 Timer와 실패 Counter 추가
• micrometer-registry-prometheus와 /actuator/prometheus 구성
• 로컬 전용 Prometheus Compose와 scrape 설정 추가
• Prometheus 기본 화면에서 확인할 PromQL 예시 문서화
• 운영·배포 환경에서는 Prometheus endpoint가 공개되지 않도록 방어

정량 평가 산출물

• 워밍업과 실제 측정을 구분하는 방법 문서화
• 단계별 시간·전체시간·성공률·결과 비율을 기록할 표 제공
• 최소 10회 반복 측정 방법과 중앙값·최댓값 계산 방법 문서화
• Server E2E 시간과 AI 팀의 모델 내부 추론시간을 혼동하지 않도록 측정 경계 명시

이번에 하지 않는 것

• Grafana Dashboard
• OpenTelemetry Collector·Jaeger·Tempo
• AI 내부 BERT·A.X·LangGraph Node별 시간 측정
• Metric 저장을 위한 신규 DB 테이블·Flyway
• 관리자 화면 API

Grafana·OpenTelemetry와 실제 Prometheus 배포는 운영 고도화 범위로 유지합니다. 이번 PR은 Server 저장소 안에서 로컬 측정 구성까지 완결합니다.

측정 경계

안전 규칙

Metric tag에는 종류가 제한된 아래 값만 사용합니다.

• phase
• stage
• status
• outcome
• failure_code

다음 값은 로그 본문이나 Metric tag에 넣지 않습니다.

• companyId, workerId, taskId
• 실명, 연락처, 이메일, 여권번호, 외국인등록번호
• Worker Link 원본 Token, JWT, API Key
• HR 발화문, 실제 Slot 값, Prompt 전문, AI 전체 응답

requestId와 attemptId는 문제 추적용 구조화 로그에서만 사용하고 Metric tag에는 사용하지 않습니다.

완료 조건

• PLAN → Slot 조회 → ANALYZE → 결과 저장의 단계별 시간과 실패 원인을 확인할 수 있음
• Renewal 기존 단계 로그와 신규 Prometheus 지표가 같은 단계 정의를 사용함
• OUT_OF_SCOPE에서는 Slot·ANALYZE 단계가 기록되지 않음
• timeout·계약 오류가 실패 지표에 구분되어 기록됨
• Metric·로그에 개인정보 및 고카디널리티 tag가 없음
• ./gradlew clean test 성공
• 로컬 Prometheus 컨테이너에서 실제 scrape와 PromQL 조회 확인
• 정량 평가 실행·정리 방법 문서화

현재 검증 결과

• ./gradlew clean test: 557 tests, 0 failures, 37 skipped
• 핵심 단계·endpoint 통합 테스트: 성공
• docker compose -f compose.observability.yml config: 성공
• 로컬 Prometheus Target fowoco-server-local: 1/1 UP
• /actuator/prometheus 실제 scrape 및 PromQL 조회: 성공

후속 정량 측정

정상 PLAN→ANALYZE, OUT_OF_SCOPE, NEEDS_INFO, timeout, Renewal 문서 생성의 반복 측정값 취합은 대표 흐름 E2E 이슈 #10에서 진행합니다. #26에서는 해당 값을 수집할 Server 로그·Metric·PromQL 경로까지 완성했습니다.

현재 기반

• PR Renewal 실행 결과를 기존 업무·안내 초안·생성 문서에 연결 #131 Renewal 실행 단계 로그
• PR AI PLAN 결정을 ANALYZE에 재사용 #138 PLAN 결정 재사용·OUT_OF_SCOPE·240초 deadline
• AI PR fix(intent): Knowledge A.X 프롬프트와 PLAN 재사용 계약 통합 ai#33 PLAN/ANALYZE 계약
• Request ID·AiRun/AiAttempt·SSE·Audit 기반
• Micrometer·Actuator 기반 지표

관계

• 구현 기반: [AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현 #8, [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24, [Reliability] 이벤트 유실 방지·재처리 기반 구현 #25, PR Renewal 실행 결과를 기존 업무·안내 초안·생성 문서에 연결 #131, PR AI PLAN 결정을 ANALYZE에 재사용 #138
• 대표 흐름 검증: [E2E] 제품 대표 복합 요청 시나리오·데모 런북 완성 #10
• 데모 배포: [Deploy] PostgreSQL·AI Runtime 기반 데모 배포 구성 #9
• Parent: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2