대시보드 자료를 해석하는 방법¶
이 페이지는 4장 본편의 선택 읽기입니다. 5교시에는 신호 종류, 도구와 비교 계약을 확인할 때 패널의 집계 범위를 점검하고, 6교시에는 요청 단위 원인 조사로 이어질 대표 요청을 고를 때 필요한 대시보드 세부를 참고합니다. 최종 승인과 보류 판단은 이 페이지에서 다루지 않습니다.
대시보드는 운영 자료를 모아 보여 주고, 다음 확인 순서를 정하는 데 도움을 줍니다. 운영 상태를 검토하는 담당자는 대시보드를 열기 전에 각 패널이 무엇을 집계하는지 알아야 합니다. 이 대시보드는 Risk API가 버전 관리하는 YAML에 선언한 지표 이름을 사용하고, Prometheus(지표 저장소), Loki(로그 저장소), Tempo(추적 기록 저장소)를 고정 UID의 대시보드에 연결합니다.
운영 자료를 보고서에 쓰려면 어떤 환경을 봤는지와 어느 시간대의 값인지 함께 적어야 합니다. 시간대와 확인한 환경이 없으면 같은 대시보드라도 배포 판단을 뒷받침하는 자료가 되지 않습니다. 대시보드를 가져오기에 성공했다는 사실만으로 실제 운영 자료를 확인한 것은 아닙니다.
대시보드를 열기 전에 정할 것
- 비교할 환경, 모델 정보, 시나리오, 시간대를 먼저 적습니다.
- 패널은 다음 조사 대상을 고르는 도구이지 모델 품질의 최종 판정표가 아닙니다.
- 화면의 값과 대표 요청을 연결한 뒤에도 확정 원인과 정답 기준 품질은 별도 근거가 필요합니다.
비교 조건을 먼저 고정합니다¶
대시보드의 environment와 scenario 변수를 먼저 선택하고, 각 패널의 model_profile, model_version 범례를 확인합니다. baseline과 current-shift를 비교할 때는 같은 기준 모델과 팀 수집 기록에 적은 절대 UTC 시작과 종료 시각을 유지합니다. 시간이 지나면 함께 움직이는 기본 상대 범위는 앞서 수집한 자료를 숨길 수 있으므로 팀 수집 기록의 범위로 사용하지 않습니다. 패널 조회식은 시나리오를 합쳐 버리지 않고 제한된 scenario 레이블로 필터링하거나 구분해야 합니다.
정적 노트북 검사는 이 변수와 조회식의 연결을 확인합니다. 이 검사가 통과했다면 result=PASS, scope=static으로 기록합니다. 실제 시계열이 수집됐다는 뜻은 아닙니다. 또한 Grafana Cloud는 저장 위치이지 증거 범위를 결정하는 환경 이름이 아닙니다. 로컬 Compose에서 만든 신호를 Cloud에서 봤다면 environment=compose, scope=local이고, 제공된 대상 환경에서 발생한 신호를 대상 모델, URL, 시간대와 함께 확인했을 때만 scope=target입니다.
같은 scenario 선택은 Prometheus 지표, Loki 로그, Tempo trace에 모두 적용됩니다. Tempo 패널의 TraceQL은 다음처럼 실제 span 속성 aiqa.scenario를 사용합니다.
{ resource.service.name = "risk-api" && span."aiqa.scenario" =~ "${scenario:regex}" }
대시보드 변수는 화면에서 비교 범위를 고르는 도구입니다. trace 한 건을 열었을 때는 변수 선택과 별도로 service.name, span 이름, trace ID, request ID가 같은 요청을 가리키는지 확인합니다.
95백분위수(P95)와 운영 자료의 의미¶
95백분위수(P95)는 데이터의 95%가 이 값 이하에 놓이는 경계값입니다. 다시 말해 상위 5%가 시작되는 지점입니다. P95 지연 시간이 높아지면 느린 요청이 늘었는지 조사합니다. 평균의 변화와 모델 품질은 각각 별도 자료로 확인합니다.
히스토그램은 score, 지연 시간, 빠진 특성 수처럼 연속된 값을 구간별로 모은 자료입니다. 히스토그램으로 P95 같은 요약값을 만들 수 있습니다. score P95가 바뀌면 높은 점수 쪽 분포가 달라졌다는 사실은 확인됩니다. 정답이 없는 트래픽에서 high_risk 정확도가 바뀌었는지는 아직 모릅니다.
조사는 지표에서 시작해 요청 하나로 범위를 좁힙니다. 6교시 요청 조사에서는 1~3단계로 같은 대시보드 범위를 분석한 뒤, 요청 단위 원인 조사의 상세 연결 절차를 참고합니다.
- 팀 수집 기록의 절대 UTC 범위와 환경과 시나리오를 복원합니다.
- 요청 상태, 5xx, 지연, 누락 특성, 점수와 예측 분포를
baseline과current-shift에서 비교하고invalid의 422를 따로 봅니다. - 같은 범위의 로그에서 요청 조사에 이어 볼 run ID와
request_id를 고릅니다. - 그 요청의 trace에서 API 경로와 처리 시간을 확인하고 다음 점검 대상을 기록합니다.
실제 run ID에서 request ID를 고르고 Tempo trace까지 전환하는 복사 가능한 LogQL과 TraceQL은 요청 단위 원인 조사에서 사용합니다. Grafana Cloud가 없으면 준비된 오프라인 관측 묶음에서 같은 연결 순서를 연습합니다. 준비된 초기 이상 관찰 자료와 오프라인 묶음의 식별자는 실제 수집 자료를 가리키지 않으므로 Loki나 Tempo 검색에 사용하지 않습니다.
| 확인 순서 | 보는 자료 | 지금 판단할 수 있는 것 | 아직 판단할 수 없는 것 |
|---|---|---|---|
| 지표 | 상태 코드 구성, P95, score, 예측 분포 |
어느 시간대와 시나리오를 더 조사할지 | 요청 하나의 정확한 원인 |
| 로그 | request_id, HTTP 상태, error_code, 제한된 validation_category, API 모델 정보 |
대표 오류 요청의 상태와 검증 분류 | 원본 입력값과 전체 트래픽에서 차지하는 비율 |
| 추적 기록 | 요청 조사에서 확인한 같은 요청의 서비스 경로와 처리 시간 | 지연 시간 또는 담당 경로의 문제 가능성 | 정답이 필요한 모델 품질 지표 |
| 운영 확인 기록 | 신호, 원인 후보, 담당자와 다음 확인 조건 | 추가 확인이 필요한 조건 | 확정 원인 |
Candidate B는 모델 후보이고, 입력, API, 실행 환경은 운영 문제의 원인 후보입니다. 이 둘은 이름은 비슷하지만 역할이 다릅니다. Candidate B는 평가 기준으로 비교하는 대상이고, 운영 문제의 원인 후보는 관측값을 설명하는 가능성입니다. 보고서에는 어느 원인 후보를 어떤 자료로 더 확인할지 적습니다.
대시보드 패널이 답하는 질문¶
각 패널은 서로 다른 질문에 답합니다. 실제 대시보드 이름은 Request rate(요청 수)처럼 한 번만 함께 적고, 이후에는 한국어로 설명합니다. 패널 이름에 오류라는 말이 들어 있어도 모든 잘못된 요청을 한 그래프로 판단할 수는 없습니다.
| 패널 | 조회하는 값 | 확인할 질문 |
|---|---|---|
Request rate(요청 수) |
시나리오와 상태 코드별 aiqa_risk_requests_total |
트래픽과 200, 422, 5xx의 구성은 어떤가 |
Error rate(5xx 오류율) |
상태 코드가 5..인 요청 수 |
서버 또는 서비스 오류가 늘었는가 |
P95 latency(P95 지연 시간) |
aiqa_risk_request_duration_seconds 요청 처리 시간 히스토그램 |
실행 환경 또는 의존 서비스 상태가 바뀌었는가 |
High-risk prediction rate(고위험 예측 비율) |
aiqa_risk_predictions_total의 모델 profile/version과 시나리오별 예측 수 |
점수와 예측의 구성이 기준 트래픽과 달라졌는가 |
Risk score P95(위험 점수 P95) |
aiqa_risk_score의 모델 profile/version과 시나리오별 점수 히스토그램 |
높은 점수 구간의 분포가 달라졌는가 |
Missing features P95(누락 특성 수 P95) |
aiqa_risk_missing_features의 모델 profile/version과 시나리오별 누락 특성 수 히스토그램 |
API에 들어오는 입력의 완전성이 달라졌는가 |
Recent logs / traces(최근 로그와 추적 기록) |
Risk API의 구조화 로그와 추적 기록 조회 | 전체 추세와 연결할 대표 요청은 무엇인가 |
의도적으로 잘못 만든 트래픽은 422 입력 형식 검증 실패를 만듭니다. 이 값은 요청 수 패널의 상태 코드별 시계열에서 확인합니다. 5xx 오류율 패널은 서비스 오류를 볼 때 사용하므로, 입력 검증 실패와 서비스 오류를 같은 그래프의 결론으로 합치지 않습니다.
트래픽 시나리오로 확인하는 입력 변화¶
합성 시나리오의 신호는 원인 후보를 점검하는 자료이지, 정답이 필요한 모델 성능 지표가 아닙니다. 아래 시나리오는 실제 장애 데이터를 재현한 것이 아니라 특정 입력 조건에서 어떤 신호가 나타나는지 확인하도록 만든 입력입니다.
시나리오를 읽을 때는 다음을 지킵니다.
baseline을 기준으로 잡고 다른 시나리오를 같은 모델과 시간대 범위에서 비교합니다.invalid의 422는 입력 검증 경로를 보는 신호이며 5xx 오류율과 합치지 않습니다.current-shift의 분포 변화는 입력 조건 영향의 가능성을 보여 줄 뿐, Candidate B의 성능 저하를 뜻하지 않습니다.
| 시나리오 | 만드는 입력 | 확인한 범위 |
|---|---|---|
baseline |
정상 운영용 입력 | 기준 트래픽 시계열과 API 입출력 형식 |
approved-candidate(선택 학습) |
제한된 시나리오 레이블을 붙인 정상 입력 | 확인한 범위에서 승인된 profile/version의 시계열 |
current-shift |
age/heart-rate/lactate/GCS를 변환한 입력 | 입력 조건 변화가 신호에 미치는 영향 가능성 |
invalid |
특성 누락, 추가, 잘못된 boolean 값을 번갈아 넣은 입력 | API 입력 검증 동작과 422 시계열 |
운영용 입력 묶음에는 target이 없습니다. 여기서는 고위험 예측 비율, score P95, 빠진 특성 수 P95의 변화와 다음 조사 대상을 기록합니다. 새 재현율(Recall), 정밀도(Precision), F1 점수(F1), 미탐(false negative, FN)은 신뢰할 수 있는 정답 레이블을 확보한 별도 평가에서 계산합니다.
정규 course-session은 baseline, current-shift, invalid 세 시나리오만
사용합니다. approved-candidate는 별도 명령과 모델 전환 근거가 준비된 경우에
선택 심화 학습이며 팀 수집 기록에 반드시 포함할 항목은 아닙니다.
관측 자료에서 원인 후보 정리하기¶
운영 자료는 원인 후보의 가능성을 낮추거나 추가 확인의 필요성을 높입니다. 하나의 신호로 원인을 확정할 수는 없으므로, 다음 표에는 다음에 확인할 자료도 함께 적습니다.
보고 문장은 다음 구조로 쓰면 범위를 지킬 수 있습니다.
- 관측: 어느 시나리오와 시간대에서 무엇이 달라졌는가
- 해석: 어떤 설명의 가능성이 낮아지거나 추가 점검이 필요한가
- 한계: 아직 확인하지 못한 대상 환경, 정답, 확정 원인은 무엇인가
- 후속: 누가 어떤 자료를 추가로 확인하는가
| 관측한 사실 | 가능성이 낮아지는 설명 | 추가로 점검할 설명 | 아직 확인할 설명 |
|---|---|---|---|
정상 baseline 200과 예상한 모델 버전 |
단순 API 프로세스 중단 | 확인한 범위에서 API 형식 사용 가능 | 대상 환경의 모델 정보, 트래픽 분포 |
| 의도적으로 만든 422 | 잘못된 입력을 조용히 받음 | 입력, API 검증 경로 | 모델 품질, 5xx 서비스 오류 |
current-shift에서 score 또는 고위험 예측 비율 변화 |
“대시보드 값은 항상 기준과 같다” | 입력 조건 또는 트래픽 구성 변화 | 정답 기준 정확도, 확정 원인 |
| 같은 모델 정보에서 P95 지연 시간 변화 | “모델 지표만으로 지연 시간을 설명할 수 있다” | 실행 환경, 의존 서비스, 트래픽 조건 | 정확한 병목 위치 |
운영 자료만으로 하나의 원인을 확정할 수는 없습니다. 검토자는 관측 자료가 뒷받침하는 내용과 아직 없는 자료를 함께 남겨, 5장의 릴리스 회의에서 성급한 승인과 불필요한 보류의 위험을 설명할 수 있어야 합니다.
실시간 운영 자료를 확인할 수 없을 때¶
uv run --package aiqa-grafana-dashboard-importer aiqa-grafana-dashboard --check가 .env.grafanacloud의 데이터 소스, 토큰 설정을 요구하거나 Alloy 비밀값이 없다면, 접속 정보와 Grafana Cloud 환경이 아직 준비되지 않은 상태입니다. 수집의 필수 필드를 모두 확인하지 못하면 재시작을 멈추고 PREPARED/OFFLINE 수집 묶음으로 전환합니다. 담당자는 대시보드 템플릿과 노트북의 정적 검사로 조회식이 맞는지 확인하고, 실시간 수집값을 보지 못했다는 사실을 분명히 적습니다.
Grafana의 실시간 수집값은 [접속 정보/환경]이 없어 확인하지 못했다. 대시보드 템플릿에는 선언된 지표와 Prometheus/Loki/Tempo 데이터 소스 설정이 있지만, 이번 보고서에 쓸 운영 자료와 시간대는 아직 확인하지 못했다. [운영 검토 담당자/플랫폼 담당자]가 설정을 갖춘 환경에서 다시 확인해야 한다.
이 기록은 대시보드를 가져오지 못했다는 이유만으로 실제 장애나 모델 결함을 확정하지 않게 합니다. 동시에 실시간 운영 자료가 없는 상태에서 대상 환경이 정상이라고 주장하는 일도 막습니다. 승인과 보류 판단은 5장 본편에서 별도 근거로 작성합니다.
운영 확인 기록의 예¶
팀 수집 기록에는 시나리오별 UTC 범위와 자료 상태를 남깁니다. 실시간 경로는 수집 매니페스트를, 오프라인 경로는 준비된 수집 묶음을 사용합니다. 개인 관찰 기록에는 자신이 그 범위를 복원해 확인한 지표와 대표 요청 또는 실시간 수집을 하지 못한 이유를 적습니다. 요청 조사 기록에는 그 요청의 로그와 trace 결과 및 데이터, 모델, 서빙 근거를 이어 씁니다.
기록에는 다음 네 항목을 채웁니다.
- 확인한 사실: 시나리오, 시간대, 지표, 로그, 추적 기록 또는 실시간 수집을 못 한 이유
- 현재 해석: 원인 후보를 좁히는 신호와 대시보드 조회식
- 남은 한계: 정답이 필요한 모델 품질, 확정 원인, 미확인 대상 환경의 운영 자료
- 다음 조치: 필요한 자료, 담당자, 다시 판단할 조건