7. 실습 ③ — 운영 로그 남기기

import json, time, uuid
from pathlib import Path

LOG_PATH = Path("logs/queries.jsonl")
LOG_PATH.parent.mkdir(exist_ok=True)

def log_query(question, final_state, elapsed):
    record = {
        "id":        str(uuid.uuid4())[:8],
        "ts":        time.strftime("%Y-%m-%d %H:%M:%S"),
        "question":  question,
        "intent":    final_state.get("intent"),
        "grade":     final_state.get("grade"),
        "verified":  final_state.get("grade") == "pass",
        "retries":   final_state.get("retries", 0),
        "rewrites":  final_state.get("rewrites", 0),
        "n_docs":    len(final_state.get("documents", [])),
        "top_score": (final_state.get("scores") or [None])[0],
        "fail_reason":   final_state.get("fail_reason", ""),
        "fallback_kind": final_state.get("fallback_kind", ""),
        "node_error":    final_state.get("node_error", ""),
        "elapsed":   round(elapsed, 2),
        "answer_len": len(final_state.get("answer", "")),
    }
    with LOG_PATH.open("a", encoding="utf-8") as f:
        f.write(json.dumps(record, ensure_ascii=False) + "\n")
    return record

# ==============================================================
# 31차시. PPT 31차시_예외처리설계. 코드 폴더는 src/31
# PPT: 31차시 안전 실행과 운영 로그
# 역할: 질문 처리가 끝난 State를 logs/queries.jsonl에 한 줄 JSON으로 추가합니다.
# 읽는 키: intent, grade, retries, rewrites, node_error 와 인자 question, elapsed
# 쓰는 키: 파일에 한 줄 추가. 반환값은 방금 저장한 record dict
# 그래프:
#   ask() 끝
#     |
#     v
#   log_query --> logs/queries.jsonl 에 한 줄 추가
# --------------------------------------------------------------
# 파이썬만 아는 분을 위한 말
# State는 노드들이 함께 쓰는 딕셔너리입니다. 함수는 state를 읽고, 바꿀 키만 return 합니다.
# return에 적지 않은 키는 이전 값이 남습니다.
# log와 tried_queries는 리스트라서, 새로 return한 항목이 뒤에 이어 붙습니다.
# Retriever: 검색 담당. 질문과 비슷한 문서 조각만 고릅니다. 답 문장은 만들지 않습니다.
# Generator: 고른 문서를 근거로 답 문장을 만듭니다. 문서가 없으면 안내 문장만 돌려줍니다.
# Verifier: 답이 근거와 맞는지 검사하고 grade를 적습니다.
#   grade=pass     답을 확정하고 그래프를 끝냅니다.
#   grade=retry    같은 문서로 답 문장만 다시 씁니다. retries가 1 늘어납니다.
#   grade=research 문서가 부족합니다. 검색어를 바꾼 뒤 다시 찾습니다. rewrites가 늘어납니다.
#   grade=giveup   더 진행하지 않고 fallback으로 안내 문장만 돌려줍니다.
# fallback: 실패했을 때 답을 지어내지 않고 안내 문장을 반환하는 노드입니다.
# intent: 질문 종류. greeting 인사, calc 계산, scope 문서 밖, document 문서 검색.
# rewrite: 사용자가 친 question은 유지하고, 검색에 쓰는 query만 바꿉니다.
# safe_node: 노드를 try로 감쌉니다. 오류가 나도 그래프는 멈추지 않고 node_error에 적습니다.
# JSONL은 한 줄에 JSON 객체 하나입니다. 질문을 처리할 때마다 한 줄이 뒤에 붙습니다.
# elapsed는 초 단위이며 소수 둘째 자리로 반올림합니다.
# 이 함수를 실행하면 현재 작업 폴더에 logs 폴더를 만들고 파일을 엽니다. 그래서 실행하지 않았습니다.
# ==============================================================

# ============================================================
# Logger
# RAG가 질문을 처리한 결과를 운영 로그로 저장합니다.
# 질문, 판정, 재시도 횟수, 오류, 실행 시간 등을 JSONL 파일에 기록합니다.
# ============================================================

import json
import os
import time

# ============================================================
# 질문 처리 결과를 로그 파일에 저장합니다.
# ============================================================

def log_query(question, state, elapsed):

    # --------------------------------------------------------
    # logs 폴더 준비
    # --------------------------------------------------------

    # logs 폴더가 없으면 새로 만듭니다.
    os.makedirs(
        "logs",
        exist_ok=True
    )

    # --------------------------------------------------------
    # 저장할 로그 데이터 만들기
    # --------------------------------------------------------

    record = {

        # 질문을 처리한 시간을 저장합니다.
        "time": time.strftime("%Y-%m-%d %H:%M:%S"),

        # 사용자가 입력한 질문을 저장합니다.
        "question": question,

        # 분류된 질문 종류를 저장합니다.
        "intent": state.get("intent", ""),

        # 검증 결과를 저장합니다.
        "grade": state.get("grade", ""),

        # 답변을 다시 생성한 횟수를 저장합니다.
        "retries": state.get("retries", 0),

        # 검색어를 다시 작성한 횟수를 저장합니다.
        "rewrites": state.get("rewrites", 0),

        # 노드에서 발생한 오류를 저장합니다.
        "node_error": state.get("node_error", ""),

        # 전체 실행 시간을 초 단위로 저장합니다.
        "elapsed": round(elapsed, 2)
    }

    # --------------------------------------------------------
    # 로그 파일에 저장
    # --------------------------------------------------------

    # JSON 데이터를 한 줄씩 파일에 추가합니다.
    with open(
        "logs/queries.jsonl",
        "a",
        encoding="utf-8"
    ) as file:

        # 딕셔너리를 JSON 문자열로 변환합니다.
        text = json.dumps(
            record,
            ensure_ascii=False
        )

        # JSON 한 건을 한 줄에 저장합니다.
        file.write(text + "\n")

    # --------------------------------------------------------
    # 저장한 로그 데이터를 반환
    # --------------------------------------------------------

    return record

import json
from collections import Counter

rows = [json.loads(l) for l in open("logs/queries.jsonl",
                                    encoding="utf-8")]

print("총 질문:", len(rows))
print("검증 통과율:",
      f"{sum(r['verified'] for r in rows)/len(rows)*100:.0f}%")
print("유형 분포:", Counter(r["intent"] for r in rows))
rewrite_count, error_count, fallback_kinds = 0, 0, []
for r in rows:
    if r["rewrites"] > 0: rewrite_count += 1
    if r["node_error"]: error_count += 1
    if r["fallback_kind"]: fallback_kinds.append(r["fallback_kind"])
print("재작성 발생률:", f"{rewrite_count/len(rows)*100:.0f}%")
print("평균 응답:", f"{sum(r['elapsed'] for r in rows)/len(rows):.1f}초")
print("오류 발생:", error_count)
print("실패 사유:", Counter(fallback_kinds))

# ==============================================================
# 31차시. PPT 31차시_예외처리설계. 코드 폴더는 src/31
# PPT: 31차시 안전 실행과 운영 로그
# 역할: logs/queries.jsonl을 읽어 질문 수, 통과율, intent 분포, 재작성 비율, 평균 시간, 오류 수를 출력합니다.
# 읽는 키: 파일의 intent, grade, rewrites, elapsed, node_error
# 쓰는 키: 화면 출력만. State 없음
# 그래프:
#   logs/queries.jsonl
#     |
#     v
#   집계 print
# --------------------------------------------------------------
# 각 줄은 logger.py가 저장한 딕셔너리입니다.
# grade가 pass인 줄 수를 전체 줄 수로 나누면 검증 통과율입니다.
# rewrites가 0보다 큰 줄의 비율이 재작성 발생률입니다.
# node_error가 비어 있지 않은 줄이 오류 발생 건수입니다.
# API를 부르지 않고 로컬 jsonl만 읽습니다.
# ==============================================================

# ============================================================
# RAG 실행 로그를 읽어 간단한 통계를 출력합니다.
# ============================================================

import json
# Counter는 같은 값이 몇 번 나왔는지 세어 주는 딕셔너리입니다.
from collections import Counter

# 로그 읽기
# 한 줄이 JSON 하나이므로 줄마다 json.loads로 딕셔너리로 바꿉니다.
# line.strip()이 빈 문자열인 줄(맨 끝 빈 줄)은 건너뜁니다.
with open("logs/queries.jsonl", encoding="utf-8") as f:
    rows = [json.loads(line) for line in f if line.strip()]

# 로그가 없으면 종료
# 아래에서 len(rows)로 나누므로, 0건이면 여기서 멈춰야 나눗셈 오류가 나지 않습니다.
if not rows:
    print("로그가 없습니다.")
    raise SystemExit

# 기본 통계
print("총 질문:", len(rows))

# grade가 pass인 줄만 1씩 더해 개수를 셉니다.
pass_count = sum(
    1 for r in rows
    if r.get("grade") == "pass"
)

# 통과 수를 전체로 나누고 100을 곱해 백분율로 보여 줍니다. :.0f는 소수점 없이 표시합니다.
print(
    "검증 통과율:",
    f"{pass_count / len(rows) * 100:.0f}%"
)

# intent 값마다 몇 건인지 셉니다. 키가 없는 줄은 빈 문자열로 셉니다.
print(
    "유형 분포:",
    Counter(r.get("intent", "") for r in rows)
)

# 재작성 및 오류 횟수
# 재작성 횟수가 아니라 "재작성이 한 번이라도 일어난 질문 수"를 셉니다.
rewrite_count = sum(
    1 for r in rows
    if r.get("rewrites", 0) > 0
)

# node_error가 빈 문자열이 아니면 오류가 난 질문입니다.
error_count = sum(
    1 for r in rows
    if r.get("node_error", "")
)

# 결과 출력
print(
    "재작성 발생률:",
    f"{rewrite_count / len(rows) * 100:.0f}%"
)

# elapsed를 모두 더해 질문 수로 나누면 한 질문당 평균 응답 시간(초)입니다.
print(
    "평균 응답:",
    f"{sum(r.get('elapsed', 0) for r in rows) / len(rows):.1f}초"
)

print("오류 발생:", error_count)