04. 운영 관측과 품질 신호

운영 관측(observability)은 API 실행 이후의 품질 신호를 로그와 메트릭으로 확인하는 활동입니다. API가 계속 응답하더라도 오류(error), 지연 시간(latency), 검증 실패(validation failure), 점수 분포, 예측 분포가 함께 움직이면 품질 조사 대상입니다.

앞 장에서 확인한 /predict 응답 필드는 운영 로그에서도 이어져야 합니다. 이번 장에서는 request_id, model_version, score, threshold, prediction이 로그와 메트릭에 남아 점수와 예측 분포 변화를 추적할 수 있는지 확인합니다.

기준	내용
맡는 일	운영 중 품질 신호를 관측하고 원인 후보를 좁힘
이번 장의 상황	API는 계속 응답하지만 오류율, 지연 시간, 점수 분포, 예측 분포가 기준선과 달라짐
확인 증거	구조화 로그, Prometheus 메트릭, Loki 조회 결과, Grafana 대시보드
판단 산출물	운영 품질 관측 리포트와 이상 신호 해석

1. 공통 운영 시나리오 적용

공통 운영 시나리오 high_risk_prediction_shift는 4장에서 실제 운영 관측값으로 다시 확인합니다. 3장에서 확인한 추적 필드를 로그와 메트릭에서 사용해 model_version, threshold, 점수, 예측, 검증 실패, 지연 시간을 함께 봅니다.

항목	4장에서의 적용
이번 장의 역할	운영 로그와 메트릭으로 실제 점수, 예측, 검증 실패 변화를 확인
새로 확인하는 증거	구조화 로그, Prometheus 메트릭, Grafana 대시보드
후보 상태 변화	model_version과 threshold 변경 후보는 약화하고, 입력 구성 변화와 검증 실패 후보는 남김
보고서 문장	운영 artifact에서 model_version=v1과 threshold=0.5는 유지되지만 점수, 예측, 검증 실패가 함께 움직입니다
다음 질문	남은 후보를 승인, 조건부 보류, 추가 확인 기준으로 어떻게 정리할 것인가

2. 이번 장에서 다룰 운영 관측 상황

운영 관측 사건은 API가 계속 응답하지만 운영 대시보드에서 품질 신호가 기준선과 달라진 상황입니다. 공통 운영 시나리오 high_risk_prediction_shift를 정상 로그와 이상 로그로 비교하면 model_version=v1과 threshold=0.5는 유지되지만, 검증 실패, 지연 시간, 점수 분포, 예측 분포가 함께 움직입니다.

normal events와 anomaly events 비교
→ 점수 분포와 예측 분포 변화 확인
→ 오류율과 지연 시간 변화 확인
→ model_version과 threshold 유지 여부 확인

이 사건의 핵심은 설정 변경 가능성과 입력/운영 변화 가능성을 분리하는 것입니다. model_version과 threshold가 유지되므로 설정 변경만으로 설명하기는 어렵습니다. 대신 검증 실패, 입력 분포 변화, 운영 지연을 남은 후보로 두고 로그, 메트릭, 대시보드 증거를 모읍니다.

3. 운영 관측의 역할

운영 관측의 역할은 운영 중 품질 변화를 관측 가능한 신호로 바꾸는 것입니다. AI 서비스에서는 API 오류(error)와 지연 시간만으로 품질 상태를 설명하기 어렵기 때문에 검증 실패, 점수 분포, 예측 분포를 함께 확인해야 합니다.

운영 관측은 도구 화면을 만드는 일이 아니라 품질 판단에 필요한 로그와 메트릭을 남기는 일입니다. AI 서비스 품질/운영에 관심 있는 실무자와 QA 담당자는 어떤 필드(field)와 로그/메트릭 라벨(label)이 있어야 원인 추적이 가능한지 이해해야 합니다. 여기서 라벨은 정답 라벨이 아니라, service, environment처럼 조회 범위를 좁히는 운영 메타데이터입니다.

4. 핵심 질문

핵심 질문은 운영 지표와 모델 품질 신호를 함께 확인하기 위한 기준입니다.

확인 관점	핵심 질문
운영 위협	입력 이상, 지연 시간 증가, 검증 실패, 드리프트(drift)를 구분할 수 있는가
로그	request_id, model_version, score, threshold, prediction이 구조화되어 남는가
메트릭	오류율, 지연 시간, 검증 실패를 시간 흐름으로 볼 수 있는가
분포 관측	점수 분포와 예측 분포 변화를 볼 수 있는가
대시보드	이상 징후를 설명하고 원인 후보를 좁힐 수 있는가

5. 학습 흐름

학습 흐름은 운영 품질 위협 요인을 관측 가능한 신호로 바꾸는 순서입니다.

운영 품질 위협 요인 이해
→ 로그, 메트릭, 트레이싱 구분
→ 구조화 로그와 request_id 확인
→ Loki/Prometheus 기반 조회
→ Grafana 대시보드 확인
→ 운영 품질 신호 해석

이 흐름은 도구를 많이 연결하기 위한 순서가 아닙니다. 운영 중 품질 이상이 보였을 때 어떤 로그와 메트릭으로 원인 후보를 좁힐지 확인하는 순서입니다.

6. 산출물과 확인 기준

운영 품질 관측 리포트는 핵심 산출물입니다. 이 리포트는 장애 대응뿐 아니라 운영 중 AI 품질 변화의 근거로 사용합니다. Lab 산출물은 uv run --group lab python labs/ch04_observability/build_observability_artifacts.py로 만들 수 있고, 준비된 로그와 메트릭 파일을 직접 열어도 같은 판단을 연습할 수 있습니다.

산출물	실행 또는 확인 경로	보고서에 남길 필드	원인 후보에 미치는 영향
구조화 로그 샘플	artifacts/logs/chapter_04_anomaly_events.jsonl	request_id, model_version, score, threshold, prediction, validation_failure, latency_ms	설정 변경 후보를 약화하고 입력/운영 변화 후보를 유지
Prometheus 메트릭	artifacts/metrics/chapter_04_anomaly.prom	요청 수 120, 오류 8, 검증 실패 8, 평균 지연 시간 223.750, 전체 high_risk 비율 0.458333, 유효 요청 high_risk 비율 0.464286, drift 후보 metric	서비스 영향과 유효 요청의 모델 응답 변화를 분리하고 입력 구성 변화 후보를 5장으로 넘김
Loki 조회 결과	4-4 문서의 request_id 조회 예시	특정 요청의 점수, 예측, 검증 실패, 지연 시간	개별 요청 단위 재현 가능성 확인
Tempo trace preview	artifacts/traces/chapter_04_tempo_payload.json	POST /predict, validate_payload, score_model, emit_observability, course_trace_id	로그의 trace_id와 요청 처리 흐름을 연결
Grafana 대시보드	artifacts/grafana/ai_quality_overview_dashboard.json, artifacts/grafana/ai_quality_details_dashboard.json	Overview의 점수/예측/오류/지연/drift 후보 패널, Details의 로그/trace 패널	품질 신호를 먼저 보고, 대표 요청 증거를 따로 확인
검증 실패 예시	artifacts/reports/chapter_04_validation_failure_examples.md	request_id, client_id, source_system, failed_field, error_detail, owner	API 계약 문제의 후속 확인 담당을 좁힘
운영 품질 해석	artifacts/reports/quality_issue_trace.md	input_case_mix_shift, prediction_shift, api_validation, service_latency 후보와 다음 조치	4장에서 생성한 후보를 5장의 입력 구성 변화와 승인 기준으로 넘김

Grafana Cloud Demo는 계정 연결 자체를 배우는 시간이 아닙니다. 필수 확인은 로컬에서 생성한 dashboard JSON, Prometheus text, Tempo trace preview, payload preview, Loki/TraceQL/PromQL 조회 예시를 읽는 것입니다. 시간이 있고 개인 계정과 네트워크 권한이 있는 수강생만 GRAFANA_DASHBOARD_TOKEN, GRAFANA_TELEMETRY_TOKEN, endpoint를 설정해 dashboard import와 Alloy collector 전송을 선택적으로 확인합니다. 계정이 없으면 실행 blocker로 기록하고 로컬 artifact 확인 결과만 보고서에 씁니다.

7. 문서 목록

문서 목록은 대시보드의 이상 신호에서 로그와 메트릭 근거로 내려가는 순서입니다. 이 장이 끝나면 수강생은 검증 실패, 점수 분포, 예측 분포 변화를 근거로 원인 후보를 정리할 수 있어야 합니다. 남은 질문은 이 근거로 배포 승인, 보류, 추가 확인 중 무엇을 선택할 것인가입니다.

순서	문서	확인할 내용
1	운영 품질의 위협 요인	입력 이상, 지연, API 오류, 설정 오류, 드리프트
2	로그, 메트릭, 트레이싱의 차이	운영 관측 신호별 역할과 한계
3	구조화 로그와 request_id	request_id, trace_id, model_version, score 기록
4	로그와 지표 확인 도구	Loki, Prometheus, request_id 기반 조회
5	Grafana 대시보드 확인	오류(error), 지연 시간, 검증 실패, 점수/예측 분포
6	운영 품질 관측 실습	정상 상태와 이상 상태의 로그와 지표 비교
7	4장 마무리	대시보드 결과를 보고서로 바꾸는 기준
8	전체 참고문헌	출처와 추가 학습 자료