동블

그래프 뷰

11. Observability와 장애 대응 런북

7 min read

이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.

  • Spring AI 기능 운영에서 어떤 metrics, logs, traces를 남겨야 하는가?
  • prompt 원문 로그는 왜 조심해야 하는가?
  • provider timeout, quota, JSON 깨짐, tool 중복 실행, vector DB 지연은 어떻게 나눠 대응하는가?
  • 장애 런북에는 어떤 사용자 메시지와 운영 절차가 들어가야 하는가?
flowchart TB
    subgraph SIGNAL["관측 신호"]
        METRIC["[Metrics]<br/>latency, token, error<br/>feature/model별 집계"]
        LOG["[Logs]<br/>requestId, promptVersion<br/>원문 대신 안전 필드"]
        TRACE["[Traces]<br/>gateway, retrieval, tool<br/>병목 위치"]
        EVAL["[Eval Result]<br/>품질 회귀<br/>golden set 비교"]
    end

    subgraph DETECT["탐지와 분류"]
        ALERT["[Alert]<br/>SLO, quota, spike<br/>임계치 기반"]
        CLASSIFY{"[Incident Type]<br/>장애 종류 분류"}
        PROVIDER["[Provider]<br/>timeout, 429, 5xx<br/>fallback 후보"]
        QUALITY["[Quality]<br/>hallucination, source miss<br/>rollback 후보"]
        SECURITY["[Security]<br/>PII, tool abuse<br/>차단 후보"]
    end

    subgraph RESPONSE["대응"]
        RUNBOOK["[Runbook]<br/>담당자, 절차<br/>사용자 메시지"]
        DEGRADE["[Degrade Mode]<br/>cached answer, queue<br/>feature flag"]
        ROLLBACK["[Rollback]<br/>prompt, model, index<br/>이전 버전"]
        POSTMORTEM["[Postmortem]<br/>eval 보강<br/>재발 방지"]
    end

    METRIC --> ALERT
    LOG --> CLASSIFY
    TRACE --> CLASSIFY
    EVAL --> QUALITY
    ALERT --> CLASSIFY
    CLASSIFY --> PROVIDER
    CLASSIFY --> QUALITY
    CLASSIFY --> SECURITY
    PROVIDER --> RUNBOOK --> DEGRADE
    QUALITY --> RUNBOOK --> ROLLBACK
    SECURITY --> RUNBOOK
    DEGRADE --> POSTMORTEM
    ROLLBACK --> POSTMORTEM

    classDef signal fill:#E3F2FD,stroke:#1565C0,color:#0D47A1;
    classDef detect fill:#FFF3E0,stroke:#EF6C00,color:#E65100;
    classDef response fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20;
    class METRIC,LOG,TRACE,EVAL signal;
    class ALERT,CLASSIFY,PROVIDER,QUALITY,SECURITY detect;
    class RUNBOOK,DEGRADE,ROLLBACK,POSTMORTEM response;

개요

AI 기능의 장애는 500 하나로 보이지 않는다. 사용자는 느린 답변, 틀린 답변, 비용 제한, 권한 없는 답변, JSON 깨짐, tool 중복 실행, 개인정보 노출을 모두 장애로 경험한다.

Spring AI는 observability 지원을 제공하고, Spring Boot Actuator와 Micrometer 생태계와 함께 운영 지표를 만들 수 있다. 하지만 어떤 차원을 남길지는 애플리케이션 설계다.

원리

최소 관측 차원은 다음과 같다.

  • feature
  • tenant
  • prompt version
  • model profile
  • provider
  • latency
  • error type
  • retry count
  • input/output token
  • retrieval hit count
  • index version
  • tool name과 execution count
  • structured output validation failure

raw prompt와 completion은 기본 로그로 장기 저장하지 않는다.

실습

Micrometer로 feature별 AI 호출 지표를 남긴다.

@Component
class AiMetrics {
 
    private final MeterRegistry registry;
 
    AiMetrics(MeterRegistry registry) {
        this.registry = registry;
    }
 
    void record(AiCallMetric metric) {
        Timer.builder("app.ai.call.duration")
                .tag("feature", metric.feature())
                .tag("modelProfile", metric.modelProfile())
                .tag("promptVersion", metric.promptVersion())
                .tag("status", metric.status())
                .register(registry)
                .record(metric.duration());
 
        Counter.builder("app.ai.call.tokens")
                .tag("feature", metric.feature())
                .tag("modelProfile", metric.modelProfile())
                .tag("type", "input")
                .register(registry)
                .increment(metric.inputTokens());
    }
}

감사 로그는 원문 대신 안전한 metadata 중심으로 남긴다.

@Component
class AiAuditLogger {
 
    private static final Logger log = LoggerFactory.getLogger(AiAuditLogger.class);
 
    void request(AiAuditEvent event) {
        log.info("ai_request feature={} tenant={} promptVersion={} modelProfile={} traceId={} inputChars={} piiMasked={}",
                event.feature(),
                event.tenantId(),
                event.promptVersion(),
                event.modelProfile(),
                event.traceId(),
                event.inputChars(),
                event.piiMasked());
    }
}

성공 경로는 장애 신고가 왔을 때 feature, prompt version, model profile, index version을 기준으로 영향을 좁힐 수 있는 것이다.

자주 나는 오류는 user id, document id, raw prompt를 metric tag로 넣는 것이다. 고카디널리티와 민감정보 문제가 생긴다.

운영에서는 OpenTelemetry GenAI semantic conventions와 내부 표준을 맞춰 trace attribute를 정한다.

실전 판단

장애 유형별 첫 확인은 다음처럼 나눈다.

  • Provider timeout: provider latency, API timeout, thread pool, circuit breaker
  • Rate limit: retry storm, tenant quota, batch job 충돌
  • JSON 깨짐: prompt version, model profile, schema 변경
  • Tool 중복 실행: idempotency key, execution id, retry 중첩
  • Vector DB 지연: filter selectivity, topK, index 상태, ingestion job
  • Prompt injection: user input, retrieved document, memory 오염원
  • 비용 폭증: token length, retry, eval batch, embedding batch

fallback은 다른 모델 재시도만이 아니다. 검색 결과만 제공, 답변 생성 생략, 비동기 처리, human review, 기능 일시 중단도 fallback이다.

실전 팁

  • alert는 error rate뿐 아니라 token spike와 validation failure spike에도 건다.
  • prompt 원문 저장은 sampling, masking, retention, access control이 있을 때만 한다.
  • 장애 런북에는 사용자 안내 문구를 포함한다.
  • batch embedding과 online chat은 rate limit bucket을 분리한다.
  • vector DB health를 provider health와 별도로 본다.

위험 신호!

  • AI 기능 SLO가 일반 API SLO와 완전히 같다.
  • token 사용량을 feature별로 볼 수 없다.
  • prompt 변경이 장애 원인인지 확인할 방법이 없다.
  • prompt와 completion 원문이 일반 로그에 장기 저장된다.
  • vector DB 장애를 provider 장애로 오해한다.

확인 질문

확인 질문

  • AI 운영에서 latency 외에 봐야 할 지표는 무엇인가?
    • token, cost estimate, prompt version, model profile, retrieval hit, index version, tool execution, validation failure다.
  • raw prompt를 metric tag로 넣으면 왜 안 되는가?
    • 고카디널리티와 민감정보 노출 위험이 크기 때문이다.
  • tool 중복 실행 장애에서 먼저 볼 것은 무엇인가?
    • execution id, idempotency key, retry 정책, provider/application retry 중첩이다.
  • fallback을 설계할 때 고려할 것은 무엇인가?
    • 사용자 경험, 데이터 정합성, 비용, 보안, 재시도 가능성, 운영자 인지 가능성이다.

학습 연결

참고 문서

관련 문서

백링크