지표, 로그, 추적 기록을 연결하는 방법¶

이 페이지는 4장 본편의 선택 읽기입니다. 5교시에는 본편에서 정한 신호 종류, 도구와 비교 계약이 각 자료에 어떻게 나타나는지 확인하고, 6교시의 요청 단위 원인 조사에서는 같은 범위로 대표 요청을 연결할 때 필요한 세부를 참고합니다. 최종 승인과 보류 판단은 이 페이지에서 다루지 않습니다.

운영 이상을 조사할 때 모든 요청을 로그부터 읽는 방식은 전체 변화를 놓치기 쉽습니다. 먼저 지표로 시간대와 시나리오를 정하고, 로그와 추적 기록으로 대표 요청을 좁혀 가야 예측 비율 증가와 실행 환경의 관계를 설명할 수 있습니다.

현재 구성에서는 Alloy가 지표, 로그와 추적 기록을 수집, 전달하고, Grafana에서 Prometheus 계열 지표, Loki 로그, Tempo 추적 기록을 조회합니다. 도구 사용법보다 각 신호가 어떤 질문에 답하는지 이해하는 것이 우선입니다.

세 신호를 연결하는 한 문장

지표로 변화한 범위를 찾고 → 로그로 대표 요청을 고르고 → 추적 기록으로 서비스 경로를 확인합니다. 이 순서는 원인을 확정하는 절차가 아니라, 다음 확인을 맡길 팀을 좁히는 절차입니다.

세 가지 운영 신호의 역할¶

지표(metric)는 요청 수, 상태 코드, 지연 시간과 분포처럼 시간에 따른 변화를 숫자로 집계합니다. 전체 추세를 빠르게 찾을 수 있지만 요청 하나의 상세한 입력과 오류 이유는 담지 않습니다.

로그(log)는 애플리케이션이 남긴 사건 기록입니다. 구조화 로그는 키와 값을 가진 JSON 형태로 남기므로 request_id, 모델 정보, 오류 코드를 조건으로 검색할 수 있습니다. 로그 한 건은 전체 요청에서 차지하는 비율을 알려 주지 않습니다.

추적 기록(trace)은 한 요청이 여러 서비스와 작업을 거친 순서와 처리 시간을 연결합니다. Risk API가 KServe를 호출하는 과정에서 어느 구간이 느렸는지 확인할 수 있지만, 정답이 필요한 모델 품질 지표를 계산하는 자료는 아닙니다.

신호	잘 답하는 질문	대표 필드 또는 값	단독으로 답하기 어려운 질문
지표	언제 어떤 추세가 달라졌는가	상태, 시나리오, 모델 정보, P95, 분포	요청 하나가 실패한 정확한 이유
로그	특정 요청에서 어떤 사건이 있었는가	`request_id`, 오류 코드, 모델 정보, 점수와 예측	전체 트래픽에서 발생한 비율
추적 기록	요청이 어느 경로에서 얼마나 걸렸는가	trace ID, span, 서비스와 처리 시간	모델 예측이 정답과 맞았는가

세 신호는 서로 대체하지 않고 연결해서 사용합니다. 5교시에서 고정한 환경, 모델, 시간대와 시나리오를 유지한 채 6교시의 요청 조사에서 지표로 변화 범위를 찾고, 로그와 추적 기록으로 대표 요청의 서비스 경로를 확인하면 다음 담당 팀을 구체적으로 정할 수 있습니다.

한 요청의 추적 경로 읽기¶

추적 화면에서는 span 이름뿐 아니라 span을 만든 서비스와 종류를 함께 봅니다. 로컬 모델을 호출하는 기본 경로는 다음 순서입니다.

traffic-generator: traffic.generate
└─ traffic-generator: risk-api.predict (CLIENT)
   └─ risk-api: POST /v1/predict (SERVER)
      └─ risk-api: risk.predict

traffic.generate는 한 번의 트래픽 실행을 묶는 시작 span입니다.
risk-api.predict는 트래픽 생성기가 Risk API로 보내는 HTTP 요청 구간입니다.
POST /v1/predict는 Risk API가 그 요청을 받은 구간입니다.
risk.predict는 입력 검사 뒤 점수를 만들고 예측을 기록하는 애플리케이션 구간입니다.

Risk API가 KServe를 사용하면 risk.predict 아래에 kserve.infer CLIENT span, KServe의 infer SERVER span과 내부 추론 span이 이어집니다. 같은 kserve.infer라는 이름이 보이더라도 service.name과 span 종류가 다르면 각각 호출한 쪽과 처리한 쪽입니다.

서비스 사이에서는 W3C traceparent HTTP 헤더가 trace 문맥을 전달합니다. 이 헤더가 이어져야 트래픽 생성기, Risk API, KServe의 span이 하나의 trace ID 아래에 놓입니다. X-Request-ID는 로그와 응답에서 업무 요청을 다시 찾는 값이며, trace 부모와 자식 관계를 전달하는 traceparent와 역할이 다릅니다.

일상 점검 요청은 trace에서 제외합니다

Risk API의 /health/live, /health/ready, /metrics와 KServe의 live, ready, 모델 ready 경로는 반복 호출되는 probe와 scrape입니다. 이 경로는 trace 저장량과 검색 잡음을 늘리므로 제외하고, 실제 /v1/predict와 KServe infer 요청은 남깁니다. 준비 상태가 정상인지 확인할 때는 HTTP 응답과 지표를 사용하고, 요청 처리 경로를 조사할 때는 trace를 사용합니다.

구조화 로그와 요청 ID¶

구조화 로그의 목적은 사람이 읽기 좋은 문장을 남기는 데 그치지 않고 나중에 같은 조건으로 검색할 수 있게 하는 것입니다. 성공한 예측 기록에는 request_id, model_profile, model_version, score, threshold, prediction이 함께 있어야 모델 출력과 실행 모델 정보를 대조할 수 있습니다.

입력 검증 실패는 점수와 예측이 만들어지기 전에 끝날 수 있습니다. http.request.completed 이벤트와 요청 지표에는 HTTP 422가 남고, model.input.validation.failed 이벤트에는 error_code=MODEL_INPUT_INVALID와 제한된 validation_category가 남습니다. 분류값은 missing, extra, type, other 중 하나이며 민감한 원본 값이나 특성명은 기록하지 않습니다.

요청 ID는 응답, 로그와 추적 기록에서 같은 요청을 찾는 연결값입니다. Prometheus 지표 레이블에 요청 ID를 넣으면 요청마다 새 시계열이 생기므로 지표 저장과 조회가 불안정해집니다. 지표에는 값의 종류가 제한된 프로필, 버전, 시나리오, 예측과 상태만 사용합니다. request_id, run ID, trace ID, span ID는 로그와 trace 검색에만 사용합니다.

필드를 기록할 때는 다음 원칙을 지킵니다.

성공 요청에는 요청 ID, 모델 정보, 점수, 임계값과 예측을 함께 남깁니다.
입력 검증 실패에는 없는 점수나 예측을 채우지 않고 HTTP 상태, 오류 코드와 제한된 검증 분류를 연결합니다.
요청 ID와 trace ID는 검색과 연결용이며 지표 레이블로 넣지 않습니다.

필드	기록 위치	사용하는 목적	주의할 점
`request_id`	응답, 로그, 추적 기록	요청 하나를 여러 자료에서 연결	지표 레이블로 사용하지 않음
`model_profile`, `model_version`	응답, 로그, 제한된 지표 레이블	실행 모델과 시간대 비교	프로필만으로 모델 파일 전체를 확정하지 않음
`score`, `threshold`, `prediction`	성공 응답과 예측 로그	모델 출력과 최종 예측의 관계 확인	정답 없는 운영에서 품질 지표로 바꾸지 않음
오류 코드와 HTTP 상태	오류 응답과 로그, 상태 지표	입력 오류와 서비스 오류 구분	422와 5xx를 같은 원인으로 합치지 않음
trace ID와 span ID	로그와 추적 기록	서비스 경로와 처리 시간 연결	지표 레이블로 사용하지 않음

구조화 필드가 빠지면 대시보드 변화와 대표 요청을 연결하기 어렵습니다. 필요한 필드가 없다면 원인을 추측하지 말고 서빙 담당자에게 로그 계약 보완을 요청합니다.

Alloy, Prometheus, Loki, Tempo, Grafana의 관계¶

Alloy는 애플리케이션에서 운영 신호를 모아 저장소로 전달하는 수집기입니다. 로컬 구성에서는 Risk API의 /metrics를 주기적으로 읽고, Docker 컨테이너 로그를 수집하며, OTLP로 받은 추적 기록을 원격 저장소에 보냅니다.

Prometheus는 시계열 지표를 수집하고 조회하는 방식과 언어를 제공합니다. Loki는 로그를 레이블과 내용으로 저장하고, Tempo는 분산 추적 기록을 저장합니다. Grafana는 이 자료를 한 대시보드에서 조회하는 화면입니다.

기존 커리큘럼에서 Promtail은 컨테이너 로그를 읽어 Loki로 보내는 역할을 설명하는 도구였습니다. 현재 구성에서는 Alloy의 loki.source.docker와 loki.write가 그 역할을 맡으며, 지표와 추적 기록도 같은 수집기에서 함께 다룹니다. 학습 목표는 바뀌지 않고 도구 구성이 현행화된 것입니다.

도구 이름보다 관측 범위와 한계를 먼저 구분합니다.

도구	현재 역할	확인할 설정 또는 결과	아직 모르는 것
Alloy	지표 스크랩, 로그 수집, 추적 기록 전달	수집 대상, 원격 주소, 상태	모델 품질과 단일 원인
Prometheus	지표 저장과 PromQL 조회	요청 수, 지연, 점수 히스토그램	요청 본문의 상세 오류
Loki	구조화 로그 저장과 LogQL 조회	요청 ID, 오류 코드, 모델 정보	전체 추세의 정확한 비율
Tempo	추적 기록 저장	서비스 경로, span별 시간	정답 기준 성능
Grafana	지표, 로그, 추적 기록을 한 화면에서 조회	데이터 소스, 시간대, 패널과 조회식	확인하지 않은 외부 환경 상태

도구 연결이 성공해도 실제 운영 신호를 확인한 것은 아닙니다. 대시보드 URL, 환경, 시간대와 시나리오를 함께 기록하고, 접속 정보가 없으면 정적 설정 확인까지만 완료로 표시합니다.

선택 읽기: 대표 요청을 고르는 기준¶

대표 요청을 고르는 목적은 전체 현상을 한 건으로 결론내리는 것이 아니라 다음 확인 경로를 정하는 것입니다. 실제 조사 명령과 기록 형식은 요청 단위 원인 조사를 따르고, 아래 표는 비교 조건을 다시 확인할 때 참고합니다.

팀 수집 기록의 절대 UTC 범위와 환경과 시나리오를 복원합니다.
요청 수, 5xx 오류율, P95 지연 시간, 누락 특성, 점수와 예측 분포를 같은 범위에서 비교합니다.
로그 패널에서 요청 조사에 이어 볼 run ID와 대표 request_id를 고릅니다.
추적 기록에서 Risk API와 KServe 경로, 처리 시간을 확인해 다음 담당 팀을 정합니다.

자료	입력으로 사용할 조건	관측 결과	배포 판단 기록에 남길 내용
지표	팀 수집 기록의 환경, 절대 UTC 범위, 모델 정보, 시나리오	변화한 비율, P95, 분포	신호와 비교 범위
로그	같은 시간대와 서비스, 오류 코드	대표 요청 ID와 사건 내용	확인한 사실과 원인 후보
추적 기록	대표 요청의 trace ID	서비스 경로와 구간별 시간	담당 팀과 다음 확인
추가 확인 조건	필요한 새 자료와 기준	판단을 다시 열 조건	기한, 담당 팀과 확인 범위

대표 요청 하나가 전체 추세를 증명하지는 않습니다. 지표의 추세와 일치하는지 확인하고, 서로 다른 원인이 섞여 있다면 요청 유형을 나누어 기록합니다.

실시간 환경을 확인하지 못했을 때¶

Grafana Cloud와 Alloy 연결에는 외부 주소와 자격 증명이 필요합니다. 팀 수집 기록을 점검할 때 필수 필드를 모두 확인하지 못하면 환경을 다시 만들지 않고 PREPARED/OFFLINE 경로로 확정합니다. 이 경로에서는 대시보드 JSON, 데이터 소스 UID, 노트북의 조회식과 importer의 정적 검사, 강사가 제공한 고정 자료만 확인합니다.

접속 정보가 없을 때 보고서에는 다음만 남깁니다.

확인한 템플릿, UID, 데이터 소스, 조회식
실시간 값을 보지 못한 이유
플랫폼 또는 운영 담당자가 준비할 연결 정보
같은 모델 정보와 시나리오로 다시 확인할 조건

정적 검사는 대시보드 구성이 현재 지표 이름과 맞는다는 근거입니다. 실제 요청이 수집됐거나 특정 시간대의 값이 정상이라는 근거는 아닙니다. 확인하지 못한 실시간 값은 미확인으로 남깁니다.

보고서에는 “대시보드 템플릿과 조회식은 확인했지만 실시간 환경의 URL과 시간대는 확인하지 못했다”고 적습니다. 플랫폼 또는 운영 담당자가 연결 정보를 준비한 뒤 같은 모델 정보와 시나리오로 다시 확인하도록 재평가 조건을 남깁니다.