소속팀: Developer팀 작성자: 유수영
🧭 이 글에서 다루는 것
“답변이 늦어요”라는 말만으로는 어느 부분을 고쳐야 할지 알기 어렵습니다. 검색, 재정렬, 모델 호출, 후처리를 나눠 봐야 합니다. 기존 프로젝트의 요청·단계별 관측 구조를 JSONL과 OpenTelemetry 예제로 풀어봅니다. 운영 기록을 남기는 방법뿐 아니라 그 기록을 해석하는 기준도 살펴봅니다.
| 읽는 순서 | 함께 살펴볼 질문 |
|---|---|
| 측정 범위 | 사용자가 기다린 시간과 함수 실행 시간은 같을까? |
| 기록 연결 | 로그와 trace를 어떻게 같은 요청으로 묶을까? |
| 코드 적용 | 오류나 취소가 나도 관측 정보를 남길 수 있을까? |
| 운영 판단 | 지연과 검색 품질을 어떻게 나눠 볼까? |
1. 개요 — 느린 답변을 작은 구간으로 나누기 💬
상담 화면에서는 답변을 기다리는 시간이 하나로 보입니다. 내부에서는 여러 작업이 이어집니다. 질문을 정리하고, 문서를 찾고, 후보를 고른 뒤 모델을 호출합니다. 답변 형식을 맞추거나 이력을 저장하는 작업도 있을 수 있습니다.
기존 프로젝트는 요청 전체와 개별 처리 구간을 나눠 관측합니다. 전체 실행 기록으로 성공 여부와 소요 시간을 확인합니다. 단계별 기록으로 검색과 모델 호출 중 어디에서 시간이 늘었는지 봅니다. JSONL과 OpenTelemetry는 이 기록을 분석 도구로 연결하는 수단입니다.
여기서 목표는 로그를 많이 만드는 것이 아닙니다. 사용자가 겪은 문제를 처리 단계까지 따라가는 것입니다. 어느 요청이었는지, 어디서 지연됐는지, 어떤 상태로 끝났는지 알아야 합니다. 다음에 확인할 곳을 좁혀 주는 기록이 운영에 도움이 됩니다.
그림 1. 상담 화면의 지연을 실제 처리 흐름과 연결합니다. AI 생성 일러스트입니다.
1.1 이번 글에서 유지한 기존 구조
| 기존 설계의 역할 | 이 글의 설명 방식 |
|---|---|
| 서비스 실행 단위 기록 | 요청을 감싸는 관측 구간 |
| 개별 처리 시간 기록 | 검색·모델 호출 등의 하위 구간 |
| 요청 문맥 누적 | 요청별 ContextVar와 이벤트 연결 |
| 실행 로그 저장 | 한 줄에 하나의 JSON 이벤트 |
| OpenTelemetry 연계 | 부모·자식 span과 식별자 |
| 응답 메타데이터 | 사용자에게 필요한 요청 식별자 |
기존 원고는 데코레이터로 적용하는 방식을 소개했습니다. 이 글에서는 시작과 종료 위치가 잘 보이도록 비동기 컨텍스트 관리자를 사용합니다. 같은 경계를 데코레이터로 감싸는 설계도 가능합니다. 동기 함수와 비동기 함수, 스트림은 각각 종료 시점이 다르므로 구현을 구분해야 합니다.
예제는 관측 흐름을 설명하기 위한 축약 코드입니다. 실제 검색 서비스나 모델에 연결하지 않고 대역 함수로 검증할 수 있습니다. 본문의 시간과 후보 수는 운영 성과를 나타내는 수치가 아닙니다. 프로젝트 내부 이름 대신 일반적인 식별자를 사용합니다.
2. 로그·trace·metric은 서로 다른 질문에 답한다 🧩
요청이 느려졌다는 신호는 집계 지표에서 먼저 볼 수 있습니다. 특정 요청의 흐름은 trace에서 따라갑니다. 그 단계에서 무슨 일이 있었는지는 구조화 로그로 확인합니다. 세 자료가 같은 요청을 가리키면 분석이 쉬워집니다.

그림 2. JSONL과 span은 요청 식별자·trace 식별자로 연결합니다. 집계 지표는 별도의 관측 수단입니다.
| 구분 | 주로 답하는 질문 | 예시 |
|---|---|---|
| 로그 | 어떤 사건이 발생했나? | 후보 수, 대체 경로, 오류 종류 |
| trace | 요청이 어떤 구간을 거쳤나? | API → 검색 → 모델 → 응답 구성 |
| metric | 전체에서 얼마나 자주, 얼마나 오래 발생하나? | 요청 수, 오류율, 지연 분포 |
| 감사 기록 | 누가 어떤 업무 행위를 했나? | 문서 다운로드, 권한 변경 |
감사 기록은 보존 목적과 접근 범위가 다를 수 있습니다. 운영 로그를 전부 감사 자료처럼 보관할 필요는 없습니다. 대화 원문을 저장하는 기능과 관측 로그도 구분합니다. 검색 품질 분석에 원문이 필요하다면 별도의 권한과 수집 범위를 정합니다.
2.1 시간의 시작과 끝을 먼저 정하기
| 시간 | 시작과 끝 | 빠질 수 있는 구간 |
|---|---|---|
| 서비스 실행 시간 | 업무 함수 진입 → 종료 | 인증, 대기열, 응답 전송 |
| HTTP 요청 시간 | 서버 수신 → 응답 전송 | 사용자의 화면 처리 |
| 첫 출력까지 시간 | 요청 시작 → 첫 답변 조각 | 나머지 답변 생성 시간 |
| 스트리밍 전체 시간 | 요청 시작 → 정상 종료 또는 중단 | 클라이언트 렌더링 시간 |
같은 latency라는 이름으로 서로 다른 구간을 섞으면 비교가 어렵습니다. 대시보드에도 측정 범위를 함께 표시합니다. 벽시계는 기록 시각에 쓰고, 경과 시간은 단조 시계로 측정합니다. 서버 시계가 보정돼도 소요 시간이 뒤집히지 않게 하기 위해서입니다.
3. JSONL에는 한 줄에 하나의 사건을 남기기 📝
JSONL은 각 줄이 독립적인 JSON 값인 형식입니다. 예쁜 들여쓰기보다 한 이벤트를 한 줄로 구분하는 데 초점을 둡니다. 본문 안의 줄바꿈은 JSON 문자열 안에서 이스케이프합니다. 인코딩과 줄 구분 규칙은 JSON Lines 형식 안내를 참고할 수 있습니다.
다음은 이해를 돕기 위한 샘플입니다. 같은 요청에서 검색과 모델 호출이 실행됐고, 마지막에 전체 구간이 끝났습니다. 요청 식별자와 trace 식별자는 공유하지만 각 span 식별자는 다릅니다.
|
{“schema_version”:1,”request_id”:”request-demo”,”trace_id”:”11111111111111111111111111111111″,”span_id”:”0000000000000002″,”stage”:”retrieval”,”outcome”:”ok”,”duration_ms”:250,”attributes”:{“app.retrieval.result_count”:5}} |
|---|
3.1 요청 식별자와 trace 식별자 구분하기
요청 식별자는 사용자 문의와 실행 기록을 연결하는 값입니다. trace 식별자는 여러 처리 구간과 서비스를 연결합니다. 세션 식별자는 여러 대화를 묶을 수 있으므로 한 요청과 같지 않습니다. 사용자 식별자는 접근 권한을 확인하는 용도이며 공개 추적 번호로 대신 쓰지 않습니다.
| 필드 | 의미 | 운영 원칙 |
|---|---|---|
| schema_version | 로그 구조의 버전 | 필드 변경 시 해석 기준 유지 |
| request_id | 한 요청을 찾는 식별자 | 원문 대신 문의 대응에 활용 |
| trace_id | 분산 실행의 연결 값 | 유효한 span 문맥에서 추출 |
| span_id | 개별 실행 구간 | 같은 요청의 반복 호출 구별 |
| stage | 코드에 정의한 단계명 | 질문 내용을 이름에 넣지 않기 |
| outcome | 성공·오류·취소 등 | 업무 결과와 구분해서 정의 |
3.2 JSONL 출력 실패가 본 작업을 덮지 않게
다음 출력기는 UTF-8로 열린 스트림에 사용한다고 가정합니다. 직렬화와 쓰기를 한곳에서 처리합니다. 프로세스 안에서는 잠금으로 여러 스레드의 쓰기를 직렬화합니다. 여러 프로세스가 같은 파일에 쓰는 문제까지 해결하는 예제는 아닙니다.
|
import json |
|---|
이 예제는 관측 출력 오류를 호출자에게 다시 던지지 않습니다. 대신 실패 횟수를 남깁니다. 운영에서는 이 횟수를 별도 지표나 수집기 상태로 확인해야 합니다. 실패한 출력기로 실패 로그를 다시 쓰면 반복 오류가 생길 수 있습니다.
디스크가 가득 차면 한 줄이 일부만 기록될 수도 있습니다. 잠금이 쓰기의 내구성이나 원자성을 보장하지는 않습니다. 동기 쓰기가 느리면 비동기 작업도 지연될 수 있습니다. 운영에서는 크기가 제한된 큐와 전용 출력 작업, 누락 지표를 함께 검토합니다.
4. 요청 문맥을 다른 상담과 섞지 않기 🔗
여러 상담 요청이 동시에 들어오면 기록도 섞여 도착합니다. 로그의 줄 순서만으로 한 요청의 흐름을 추측하기 어렵습니다. 각 비동기 작업이 같은 요청 식별자를 참조할 수 있어야 합니다. 기존 설계는 요청 문맥을 통해 이런 정보를 전달합니다.
여기서는 ContextVar에 요청 식별자 하나를 둡니다. 요청 시작 시 새 값을 설정하고 종료 시 이전 상태로 복원합니다. 오류나 취소가 발생해도 복원 코드는 실행되도록 구성합니다. 공유 사전에 모든 요청의 누적 값을 직접 넣는 방식은 피합니다.
그림 3. 단계가 나뉘어도 같은 요청의 문맥을 이어 갑니다. AI 생성 일러스트입니다.
|
from contextlib import asynccontextmanager |
|---|
ContextVar는 비동기 문맥별 값을 관리합니다. 하지만 그 안에 넣은 가변 객체를 자동으로 깊은 복사하지는 않습니다. 하위 작업이 같은 리스트를 수정하는 누적 방식에는 별도 설계가 필요합니다. 기본 동작은 Python ContextVar 문서를 참고합니다.
스레드, 프로세스, 외부 서비스 경계에서는 전파 방식을 확인해야 합니다. 요청에서 만든 백그라운드 작업이 더 오래 살아남는 경우도 마찬가지입니다. 요청 안에서 끝낼 작업은 종료까지 기다리고, 별도 작업은 별도 실행으로 구분합니다. ContextVar가 분산 추적 헤더를 대신 만들어 주는 것은 아닙니다.
5. OpenTelemetry span과 JSONL을 같은 구간에서 만들기 ⏱️
span은 시작과 끝이 있는 작업 구간입니다. 상위 요청 span 안에서 검색 span을 만들면 부모·자식 관계로 연결됩니다. 그 문맥의 식별자를 로그에 넣으면 같은 실행을 두 도구에서 찾을 수 있습니다. span 이름에는 질문 원문보다 고정된 단계명을 사용합니다.
5.1 SDK와 exporter의 역할
아래 설정은 exporter를 외부에서 받습니다. 검증에서는 메모리 exporter를 쓰고, 운영에서는 수집기로 보내는 exporter를 선택할 수 있습니다. provider는 요청마다 만들지 않고 애플리케이션 수명에 맞춰 관리합니다. 종료 시에는 정해진 시간 안에서 flush와 shutdown을 수행합니다.
|
from opentelemetry.sdk.resources import Resource |
|---|
API만 사용하는 경우와 SDK·exporter를 연결한 경우는 다릅니다. SDK가 없으면 기본 no-op 동작일 수 있습니다. SDK가 있어도 exporter나 수집기가 준비되지 않으면 화면에서 trace를 볼 수 없습니다. 설정 방법은 OpenTelemetry Python 계측 문서를 참고합니다.
5.2 성공·오류·취소를 구분하는 단계 측정
다음 코드는 실행 중 수정할 속성 사전을 반환합니다. 허용한 키만 로그와 span에 옮깁니다. 원시 예외 메시지와 스택은 자동 기록하지 않고 오류 종류만 남깁니다. 그 안에 질문이나 외부 주소가 들어갈 수 있기 때문입니다.
|
import asyncio |
|---|
app.*는 이 글에서 정한 사용자 정의 속성입니다. 표준 속성으로 소개한 이름은 아닙니다. 실제 적용 시에는 OpenTelemetry 의미 규약의 버전과 안정성을 확인합니다. 같은 의미의 값을 여러 이름으로 기록하지 않도록 조직 내 기준을 정합니다.
허용한 키의 값도 서버가 정한 형식과 범위를 따라야 합니다. 예제의 허용 목록은 값의 민감성까지 판별하는 장치는 아닙니다. 자동 계측이 별도로 예외나 본문을 기록하는지도 확인해야 합니다. 취소를 오류 상태로 표시한 것은 이 예제의 정책이며 집계에서는 취소를 따로 구분합니다.
5.3 검색과 모델 호출에 적용하기
|
async def run_agent(question, retrieve, generate, tracer, sink): |
|---|
현재 예제의 전체 시간은 업무 함수 범위입니다. HTTP 수신부터 전송까지의 시간과 같지 않습니다. 사용자 응답에는 문의할 때 쓸 요청 식별자만 넣었습니다. 내부 주소, 원시 오류, 세부 관측 속성을 그대로 공개할 필요는 없습니다.
기존 설계처럼 관측 요약을 응답 메타데이터에 붙일 수도 있습니다. 이 경우에도 공개할 항목과 관리자용 항목을 구분합니다. 검색 결과가 0건인 것은 실행 오류가 아닐 수 있습니다. 기술적 성공과 업무 결과를 서로 다른 필드로 기록합니다.
6. 병렬 실행과 스트리밍은 시간을 다르게 읽기 🌊
의미 검색과 키워드 검색이 동시에 실행될 수 있습니다. 각각 200ms와 150ms가 걸렸다고 전체 검색이 350ms인 것은 아닙니다. 부모 구간은 두 작업을 기다린 실제 경과 시간을 가집니다. 하위 구간의 합계는 겹친 실행 시간을 포함할 수 있습니다.
| 상황 | 기록할 구간 | 해석할 때 볼 것 |
|---|---|---|
| 순차 실행 | 상위 요청과 각 단계 | 단계 사이의 대기·준비 시간 |
| 병렬 검색 | 부모와 병렬 자식 span | 가장 오래 걸린 경로와 합류 대기 |
| 재시도 | 전체 호출과 시도별 span | 대기 시간, 횟수, 최종 상태 |
| 대체 경로 | 최초 실패와 대체 실행 | 성공 응답 안에 숨은 품질 변화 |
6.1 스트림을 만들 때와 다 읽었을 때
비동기 생성기 객체를 만든 시간은 답변 생성 시간이 아닙니다. 실제로 반복하며 조각을 소비하는 동안 측정해야 합니다. 아래 예제는 스트림 소비 구간을 감쌉니다. 완료되지 않은 생성기를 닫으면 취소로 기록합니다.
|
async def stream_answer(source, tracer, sink): |
|---|
소비하는 쪽에서 중간에 멈추면 생성기도 명시적으로 닫아야 합니다. contextlib.aclosing 같은 수명 관리 방식으로 종료 코드를 실행할 수 있습니다. 연결 종료 신호를 처리하고 원본 스트림을 정리하는 일은 호출 계층의 책임입니다. 이 코드만으로 모든 HTTP 연결 중단이 자동 탐지되는 것은 아닙니다.
첫 출력까지의 시간과 전체 종료 시간은 별도로 측정합니다. 빈 스트림이라면 첫 출력 시간은 측정값 없음으로 표현합니다. 생성 완료와 클라이언트가 화면에서 읽은 시점도 다릅니다. 대시보드에서 어느 지점을 뜻하는지 표시해야 합니다.
6.2 서비스 밖으로 trace를 이어 가기
같은 프로세스 안의 부모·자식 span은 현재 문맥으로 연결됩니다. 다른 서비스로 넘어갈 때는 송신 측 주입과 수신 측 추출이 필요합니다. HTTP 자동 계측을 사용하는 경우에도 실제 헤더 전파를 확인합니다. 외부 모델 서비스가 같은 trace를 받아 준다는 가정은 하지 않습니다.
분산 문맥의 기본 개념은 OpenTelemetry 문맥 전파 문서에 설명되어 있습니다. 요청 식별자를 속성에 넣는 것만으로 부모·자식 관계가 생기지는 않습니다. 추적 헤더는 인증 정보도 아닙니다. 개인정보나 질문 원문을 전파용 baggage에 넣지 않도록 범위를 정합니다.
7. 알림에서 원인까지 따라가기 🛠️
p95 지연이 늘었다는 알림을 받았다고 가정해 봅니다. 먼저 어떤 요청 유형과 배포 버전에서 변화가 생겼는지 봅니다. 느린 요청의 trace를 열고 오래 걸린 단계를 찾습니다. 같은 식별자의 JSONL에서 후보 수나 대체 경로를 확인합니다.
검색이 느리면 DB 실행과 연결 대기를 나눠 봅니다. 모델 호출이 느리면 입력 길이, 출력량, 재시도를 확인합니다. 후처리가 길어졌다면 문서 수와 직렬화 비용을 살펴봅니다. 어디가 느린지 확인한 뒤 그 단계의 설정을 바꿉니다.
그림 4. 집계 지표에서 요청을 찾고, 실행 단계와 사건 기록으로 원인을 좁힙니다. AI 생성 일러스트입니다.

그림 5. 개선 뒤에는 같은 조건의 지연과 품질을 다시 확인합니다.
7.1 장애 증상별로 확인할 기록
| 증상 | 먼저 볼 구간 | 연결해서 확인할 값 |
|---|---|---|
| 전체 응답 지연 | 업무 함수 밖의 대기와 요청 span | 연결 풀, 대기열, 전송 시간 |
| 검색 지연 | 검색 span | 후보 수, 필터, 인덱스 개정 |
| 모델 지연 | 모델 호출 span | 입력량, 출력량, 재시도 횟수 |
| 응답은 성공인데 품질 저하 | 대체 경로와 검색 결과 | 재정렬 실패, 근거 누락 |
| 로그는 있는데 trace가 없음 | SDK·수집기·샘플링 | exporter 실패, 비표본 요청 |
| 다른 요청의 기록이 섞임 | 문맥 설정·복원 | 공유 객체와 작업 수명 |
관측 기록에 없는 값을 추측해 채우지 않습니다. 공급자가 토큰 사용량을 반환하지 않았다면 알 수 없음으로 남깁니다. 토큰 수와 비용을 계산할 때도 모델 버전과 적용 조건을 구분합니다. 시간이 줄었다는 이유만으로 검색 품질이 유지됐다고 판단하지 않습니다.
7.2 집계 지표의 차원을 제한하기
지표 라벨에는 요청 식별자나 질문 원문을 넣지 않습니다. 고유 값이 계속 생기면 집계 조합이 급격히 늘어납니다. 단계, 결과 상태, 제한된 서비스 구분처럼 관리 가능한 값을 사용합니다. 개별 요청을 찾는 일은 로그와 trace에 맡깁니다.
| 지표 | 집계 기준 예 | 같이 표시할 것 |
|---|---|---|
| 요청 수 | 서비스, 완료 상태 | 대상 기간과 실제 표본 수 |
| 지연 분포 | 요청 유형, 실행 경로 | p50·p95와 실패 요청 처리 기준 |
| 오류율 | 오류 범주, 서비스 | 분모와 취소 포함 여부 |
| 검색 결과 없음 비율 | 검색 방식, 질문 유형 | 시스템 오류와의 구분 |
| 관측 유실 | 출력기·수집기 구분 | 큐 포화, 전송 실패, 누락 건수 |
평균 지연과 p95는 다른 통계입니다. 인스턴스별 p95를 평균 내서 전체 p95로 사용하지 않습니다. 합칠 수 있는 히스토그램 등으로 분포를 집계해야 합니다. 지연과 오류, 요청량을 함께 보는 관점은 Google SRE 모니터링 자료를 참고했습니다.
8. 기록이 운영을 방해하지 않도록 📦
JSONL은 단순하지만 저장량이 빠르게 늘 수 있습니다. 로그 회전, 압축, 보존, 삭제를 함께 관리합니다. 여러 워커가 같은 회전 파일을 직접 쓰는 구조는 별도로 검증해야 합니다. 표준 출력과 수집기를 활용할 때도 수집 실패와 저장 한도를 점검합니다.
8.1 원문과 민감정보를 필요한 범위로
기본 관측값은 개수, 상태, 시간, 버전으로 시작합니다. 프롬프트 전문과 답변 전문을 무조건 넣지 않습니다. 원문이 필요한 진단은 제한된 대상과 기간, 접근 권한으로 분리합니다. 예외 메시지, SQL 값, HTTP 헤더에도 민감정보가 들어갈 수 있습니다.
필드 허용 목록과 마스킹만으로 모든 노출을 막을 수는 없습니다. 자동 계측과 공급자 SDK가 추가하는 속성도 확인합니다. 서비스에서 삭제한 대화가 관측 저장소에 계속 남아 있는지도 점검합니다. 관측 데이터의 보존 목적을 대화 이력과 구분해야 합니다.
8.2 샘플링과 유실을 구별하기
trace를 일부만 남기는 샘플링 정책을 사용할 수 있습니다. 로그에 trace 식별자가 있어도 저장된 trace가 없을 수 있습니다. 이 상황과 exporter 장애로 기록이 유실된 상황은 다릅니다. 표본 비율과 전송 실패를 각각 관측합니다.
샘플링한 trace 개수를 그대로 전체 요청 수로 쓰지 않습니다. 요청 지표는 관측 대상 전체에서 별도로 집계하는 편이 좋습니다. 느린 요청이나 오류 요청의 수집 정책을 바꾸면 표본의 성격도 달라집니다. 전후 비교에서 이 변경을 함께 기록합니다.
8.3 코드 검증에서 확인할 것
| 시나리오 | 확인할 결과 |
|---|---|
| 정상 요청 | 전체·검색·모델 이벤트와 부모·자식 관계 |
| 동시 요청 | 요청 식별자와 trace가 서로 섞이지 않음 |
| 단계 오류 | 원래 예외 유지, 오류 종류 기록 |
| 취소·스트림 중단 | 성공과 구분된 종료 상태 |
| JSONL 출력 실패 | 업무 결과를 덮지 않고 실패 횟수 증가 |
| 추적 비활성화 | 로그는 유지하고 잘못된 trace ID를 만들지 않음 |
| 줄바꿈과 비정상 숫자 | JSONL 줄 경계 유지, 유효하지 않은 숫자 거절 |
테스트에서는 대역 검색기와 모델을 사용합니다. 메모리 exporter로 실제 span 관계를 확인할 수 있습니다. 운영 수집기 연결과 모델 응답 품질은 별도의 검증입니다. 관측 코드가 동작한다는 사실과 실제 장애를 잘 찾는다는 성과를 구분합니다.
9. 결론 — 문제를 설명할 수 있는 기록부터 🌱
상담 AI의 관측은 요청 전체와 개별 단계를 함께 보는 일입니다. JSONL은 발생한 사건을 남기고, span은 실행의 관계를 보여줍니다. 집계 지표는 평소와 다른 변화를 찾는 데 사용합니다. 같은 식별자로 연결하면 다음에 볼 곳을 좁힐 수 있습니다.
시간의 경계와 상태의 의미를 먼저 정합니다. 병렬 실행, 재시도, 스트리밍은 그 의미에 맞춰 기록합니다. 관측 실패가 업무 오류를 덮지 않도록 하면서 유실도 따로 확인합니다. 사용자가 겪은 문제를 처리 단계까지 설명할 수 있는가가 좋은 기준입니다.
10. 참조 출처 📚
- OpenTelemetry Documentation — 관측 신호와 구성 요소.
- OpenTelemetry Python Instrumentation — SDK와 span 계측.
- OpenTelemetry Context Propagation — 서비스 사이의 추적 문맥 전달.
- OpenTelemetry Semantic Conventions — 속성 이름과 의미 규약.
- Python Context Variables — 비동기 문맥별 상태 관리.
- JSON Lines — 한 줄 단위 JSON 형식.
- Google SRE — Monitoring Distributed Systems — 운영 지표와 장애 관측의 기본 관점.
11. 태그
#Observability #OpenTelemetry #JSONL #Tracing #Latency #AIAgent #Monitoring #FastAPI #Python #상담AI