관측 가능성 - 로그·지표·추적으로 장애 찾기
이 장에서 배우는 것
앞 장에서 작은 온라인 서점의 백엔드를 프로세스로 실행하고, 앞단에서 요청을 넘기는 구성을 살펴봤다. 프로세스가 살아 있어도 독자가 보는 책 상세 화면은 늦게 열릴 수 있다. 관측 가능성(observability)은 서비스가 남긴 신호를 바탕으로 안에서 무슨 일이 일어났는지 알아내는 데 필요한 성질이다. 이 장에서는 서점의 요청 기록을 모아 어느 구간에서 시간을 썼는지 확인하고, 어떤 조건에서 담당자에게 알려야 하는지 정한다.
- 로그의 수준을 고르고, 요청마다 같은 이름과 단위로 필드를 기록한다.
- 요청 ID로 흩어진 기록을 모아 한 요청의 처리 구간을 복원한다.
- 요청 수, 오류율, 지연 백분위를 계산하고 표본 수와 함께 읽는다.
- 느린 질의와 외부 API 응답 지연을 구분하고, 경보와 조사에 필요한 증거를 정리한다.
문제 상황
서점의 책 상세 화면은 책 정보를 저장소에서 읽고, 배송 예상일을 외부 서비스에 물어본 뒤 응답을 돌려준다. 운영 중에 상세 화면이 늦게 열린다는 제보가 들어왔다. 같은 시각에 애플리케이션은 요청을 계속 받았고, 어떤 독자는 늦게나마 화면을 받았으며 다른 독자는 오류 화면을 받았다. 완료 로그에 상태 코드만 있다면 두 독자가 어느 구간에서 기다렸는지 알기 어렵다.
담당자는 두 가지 질문을 순서대로 푼다. 첫째, 상세 화면의 문제가 얼마나 넓게 나타났는가. 둘째, 실제로 느렸던 요청은 어디에서 시간을 썼는가. 첫 질문에는 같은 시간 창에 완료된 요청의 집계가 필요하다. 둘째 질문에는 개별 요청의 기록을 모을 수 있는 식별자와 구간별 시간이 필요하다. 예제에는 정상 요청 하나와 지연 요청 두 개를 넣었다. 두 지연 요청은 각각 책 조회와 배송 조회에서 가장 오래 걸린다.
로그와 요청 ID로 한 요청 복원하기
로그(log)는 어떤 사건이 일어났는지 남긴 기록이다. 구조화 로그(structured log)는 한 줄에 한 사건을 담고, 각 사건에 이름 있는 필드를 둔다. 완료 사건에 status와 duration_ms가 있으면 프로그램은 문장 속에서 숫자를 찾아낼 필요 없이 상태와 시간을 읽는다. JSON을 한 줄씩 저장하는 형식에서는 한 줄을 복사해도 그 사건의 값을 함께 볼 수 있다. 라우트는 개별 주소 대신 /books/{book_id}처럼 경로 패턴으로 남긴다. 독자 식별 정보나 배송 조회에 사용한 입력값은 이 조사에 필요하지 않다.
| 수준 | 기록할 사건 | 서점 예시 |
|---|---|---|
DEBUG | 조사나 개발 중에 보는 세부 단계 | 책 조회 구간이 끝났다. |
INFO | 평상시 처리 결과를 확인하는 사건 | 책 상세 요청이 성공 상태로 끝났다. |
WARNING | 요청은 처리할 수 있지만 살펴볼 이상 | 배송 예상일 조회가 늦어 응답에서 예상일을 생략했다. |
ERROR | 요청이나 작업을 끝내지 못한 사건 | 배송 응답을 기다리다 제한 시간이 지나 상세 요청이 504로 끝났다. |
같은 실패를 저장소, 서비스, 요청 처리기가 모두 오류로 기록하면 한 요청이 여러 번 실패한 것처럼 보일 수 있다. 예제는 구간 완료를 DEBUG로, 최종 결과를 상태에 따라 INFO 또는 ERROR로 기록한다. 오류율의 분자는 로그 수준이 ERROR인 줄의 개수가 아니라 완료 사건에서 5xx로 끝난 요청 수다. 이 장의 예제는 조사에 필요한 구간 로그를 모두 읽는다. 운영에서 DEBUG를 필터링한다면 이 구간을 다시 보려면 별도로 수집한 추적 데이터가 필요하다.
요청 ID는 요청이 들어올 때 정하고, 처리 중 남기는 여러 사건에 같은 값으로 전달한다. 여러 요청이 동시에 실행되면 로그 줄이 섞일 수 있다. 요청 ID가 같으면 기록이 파일에서 떨어져 있어도 같은 요청으로 묶을 수 있다. 그다음 각 구간의 시작 위치와 길이를 읽어 요청 안에서 처리 순서를 복원한다. 이 예제의 시작 위치는 요청 시작 후 경과한 밀리초다. 실제 코드에서 한 프로세스 안의 경과 시간을 잴 때는 time.monotonic_ns()처럼 벽시계 조정의 영향을 받지 않는 시계를 사용한다.
추적(trace)은 요청을 처리한 작업 구간과 그 관계를 보여 준다. 각각의 작업 구간을 스팬(span)이라고 한다. 여러 서비스가 참여하거나 작업이 병렬로 실행되면 추적 ID로 전체 작업을 묶고, 스팬 ID와 부모 스팬 ID로 작업 사이의 관계를 표현할 수 있다. 이 장의 코드는 한 프로세스에서 순차 실행한 구간만 다룬다. 요청 ID는 기록을 묶는 데 쓰고, 경과 시간은 그 안에서 구간을 정렬하는 데 쓴다. 여러 호스트의 벽시계 시각을 단순히 빼서 이와 같은 경과 시간을 구하면 시계 차이가 계산에 들어간다.
지표와 경보로 조사 범위 좁히기
지표(metric)는 시간에 따라 비교할 수 있도록 집계한 숫자다. 예제에서는 준비한 로그 전체를 하나의 관측 창으로 보고, 책 상세 라우트의 완료 사건만 집계한다. 운영에서는 같은 라우트와 같은 시간 창을 분자와 분모에 적용한다. 완료 기준으로 집계한다는 것은 창 안에서 시작한 요청이더라도 창 밖에서 끝나면 다음 집계에 들어갈 수 있다는 뜻이다. 완료 건수만으로는 아직 응답을 기다리는 요청의 수를 알 수 없다.
| 지표 | 계산 | 조사에 쓰는 방법 |
|---|---|---|
| 요청 수 | 창 안에서 완료된 요청을 센다. | 오류나 지연이 나타난 창의 표본 크기를 확인한다. |
| 오류율 | 5xx 완료 건수를 전체 완료 건수로 나눈다. | 실패 비중을 보고 분자와 분모도 함께 확인한다. |
| 95번째 백분위 지연(p95) | 지연을 오름차순으로 정렬하고, 건수에 0.95를 곱해 올림한 순번의 값을 고른다. | 느린 쪽 응답이 어느 정도 걸렸는지 살핀다. |
이 장은 가장 가까운 순위 방식(nearest rank)을 사용한다. 130, 870, 950ms가 있으면 순번은 3이므로 p95는 950ms다. 세 건에서 계산한 p95는 최댓값과 같다. 운영에서 백분위 계산 방식이 달라지면 같은 자료에서도 값이 달라질 수 있으므로 대시보드와 경보에서 쓰는 방식을 맞춰 둔다. 창에 완료 요청이 하나도 없으면 오류율과 p95는 계산할 자료가 없는 상태로 표시한다. 요청 ID는 개별 기록을 조회할 때 쓰고, 지표는 라우트처럼 여러 요청이 공유하는 값으로 묶는다.
경보(alert)에는 비교할 수치와 함께 관측 창, 필요한 최소 표본 수, 지속 조건, 담당자가 처음 확인할 항목을 적는다. 예를 들어 서점이 책 상세 화면의 p95 목표를 500ms로 정했다고 하자. 최근 5분을 1분마다 집계하고, 완료가 100건 이상인 창에서 p95가 500ms를 넘는 일이 세 번 연속 확인되면 담당자에게 알리는 규칙을 둘 수 있다. 오류율은 별도 목표를 적용한다. 예를 들어 같은 창과 표본 조건에서 5xx 비율이 2%를 넘는 평가가 세 번 이어질 때 알린다. 어느 한 평가라도 최소 표본 조건을 충족하지 못하거나 임계값 이하로 돌아오면 해당 규칙의 연속 횟수를 초기화한다.
이 수치는 서점의 가상 운영 기준이다. 평소 요청량이 적다면 충분한 표본을 얻도록 창을 늘릴 수 있다. 창을 늘리면 짧은 장애가 집계에서 덜 두드러질 수 있고, 연속 조건을 길게 잡으면 통보까지 더 걸린다. 요청이 평소에도 들어오던 시간에 완료 건수가 갑자기 사라지는 상황은 낮은 오류율로 해석하지 않고, 별도의 신호로 다룬다. 경보가 울리면 먼저 라우트의 완료 건수와 5xx 건수를 확인하고, 그 창의 느린 요청 몇 건을 골라 구간을 비교한다.
완성 코드
main.py에 저장한다. 프로그램은 세 요청의 예시 기록을 JSON 줄로 만든 다음, 서로 다른 요청의 기록을 번갈아 배치해 분석기에 넘긴다. 질의와 배송 조회를 실행하는 대신 이미 관측한 것으로 가정한 구간 시간을 입력한다. 지연 기준은 예제 전체에서 500ms이며, 기준을 넘은 요청에 대해 가장 긴 단일 구간을 병목 후보로 출력한다. 경보의 관측 창과 연속 조건은 운영 규칙을 설명하기 위한 것으로, 이 프로그램에서는 평가하지 않는다.
import json
from collections import defaultdict
ROUTE = "/books/{book_id}"
SLOW_MS = 500
SPAN_NAMES = {
"request_parse": "요청 해석",
"book_query": "책 조회",
"shipping_api": "배송 API",
}
def example_log_lines():
cases = [
("req-01", 200, 130, (20, 70, 30)),
("req-02", 200, 870, (20, 780, 50)),
("req-03", 504, 950, (20, 60, 840)),
]
requests = []
for request_id, status, total_ms, durations in cases:
events = []
offset_ms = 0
for span_name, duration_ms in zip(SPAN_NAMES, durations, strict=True):
events.append({
"event": "span_finished",
"level": "DEBUG",
"request_id": request_id,
"span": span_name,
"start_ms": offset_ms,
"duration_ms": duration_ms,
})
offset_ms += duration_ms
events.append({
"event": "request_finished",
"level": "ERROR" if 500 <= status < 600 else "INFO",
"request_id": request_id,
"route": ROUTE,
"status": status,
"duration_ms": total_ms,
})
requests.append(events)
return [
json.dumps(event)
for batch in zip(*requests, strict=True)
for event in batch
]
def collect_requests(lines):
spans_by_request = defaultdict(list)
completed = {}
for line in lines:
event = json.loads(line)
request_id = event["request_id"]
if event["event"] == "span_finished":
spans_by_request[request_id].append(event)
elif event["event"] == "request_finished":
if request_id in completed:
raise ValueError(f"완료 기록 중복: {request_id}")
completed[request_id] = event
return completed, spans_by_request
def percentile_95(durations):
ordered = sorted(durations)
rank = (95 * len(ordered) + 99) // 100
return ordered[rank - 1]
def print_request(request, spans):
request_id = request["request_id"]
total_ms = request["duration_ms"]
ordered = sorted(spans, key=lambda span: span["start_ms"])
previous_end = 0
recorded_ms = 0
for span in ordered:
start_ms = span["start_ms"]
duration_ms = span["duration_ms"]
end_ms = start_ms + duration_ms
if start_ms < previous_end or duration_ms < 0 or end_ms > total_ms:
raise ValueError(f"순차 구간 시간 오류: {request_id}")
previous_end = end_ms
recorded_ms += duration_ms
parts = [
f"{SPAN_NAMES[span['span']]} {span['duration_ms']}ms"
for span in ordered
]
parts.append(f"미계측 {total_ms - recorded_ms}ms")
route_detail = " → ".join(parts)
print(f"{request_id} | {request['status']} | 전체 {total_ms}ms")
print(f" {route_detail}")
if total_ms > SLOW_MS and ordered:
longest = max(ordered, key=lambda span: span["duration_ms"])
name = SPAN_NAMES[longest["span"]]
print(f" 병목 후보: {name} {longest['duration_ms']}ms")
elif total_ms > SLOW_MS:
print(" 병목 후보: 구간 기록 없음")
def main():
completed, spans_by_request = collect_requests(example_log_lines())
requests = [
event for event in completed.values() if event["route"] == ROUTE
]
print(f"라우트 {ROUTE}")
count = len(requests)
if count == 0:
print("완료 요청 0건 | 5xx 오류율 계산 불가 | p95 계산 불가")
return
errors = sum(500 <= request["status"] < 600 for request in requests)
p95 = percentile_95([request["duration_ms"] for request in requests])
print(f"완료 요청 {count}건 | 5xx {errors}건 ({errors / count:.1%}) | p95 {p95}ms")
for request in sorted(requests, key=lambda event: event["request_id"]):
request_id = request["request_id"]
print_request(request, spans_by_request.get(request_id, []))
if __name__ == "__main__":
main()
줄별 해설
cases의 각 줄은 요청 ID, 최종 상태, 전체 지연, 세 구간의 길이를 순서대로 담는다.SPAN_NAMES의 삽입 순서에 대응해 첫 숫자는 요청 해석, 둘째는 책 조회, 셋째는 배송 조회에 배정한다.zip의strict=True는 이름과 시간이 서로 다른 개수로 주어졌을 때 오류를 낸다.offset_ms는 한 요청 안에서 다음 구간이 시작할 위치다. 구간을 하나 추가할 때마다 그 길이만큼 더한다. 전체 시간은 완료 사건에 따로 넣는다. 이 자료에서 구간 합계와 전체 시간이 다른 이유는 끝부분에 계측하지 않은 시간이 있기 때문이다.zip(*requests, strict=True)는 세 요청에서 같은 위치의 사건을 하나씩 꺼낸다. 첫 묶음에는 요청 세 개의 해석 구간이, 마지막 묶음에는 완료 사건 세 개가 들어간다. 분석기는 JSON을 읽는 순서와 관계없이 요청 ID로 구간과 완료를 연결한다. 같은 요청 ID의 완료 사건이 두 번 오면 어떤 값을 고를지 임의로 정하지 않고 입력 오류를 드러낸다.rank의 정수 계산은95 * len(ordered)를 100으로 나눈 값을 올림한다. 순번은 1부터 세고 리스트 인덱스는 0부터 세므로rank - 1을 사용한다.main에서 빈 집계를 먼저 처리하므로 백분위 함수에는 값이 한 개 이상 전달된다.print_request는 시작 위치로 정렬한 뒤 구간이 겹치거나 요청 끝을 넘는지 확인한다. 순차 구간에서 전체 지연에서 구간 길이의 합을 빼면 관측하지 않은 시간의 합을 알 수 있다. 출력의미계측은 그 합계를 끝에 적은 것이다. 예시 자료를 바꿔 구간 사이에 빈틈을 넣어도 그 시간은 같은 합계에 들어간다.max는 느린 요청에서 기록된 구간 중 가장 긴 구간을 고른다. 이는 조사 순서를 정하기 위한 후보다. 미계측 시간이 크거나 필요한 구간의 기록이 빠졌다면, 계측 범위를 확인한 뒤에 원인을 판단한다.
실행 결과
파일이 있는 디렉터리에서 아래 명령을 실행한다. 코드 블록의 두 줄은 각각 문법 검사와 프로그램 실행 명령이다.
python3 -W error -m py_compile main.py
python3 main.py
문법 검사가 성공하면 메시지 없이 끝난다. 프로그램의 표준 출력은 다음과 같다.
라우트 /books/{book_id}
완료 요청 3건 | 5xx 1건 (33.3%) | p95 950ms
req-01 | 200 | 전체 130ms
요청 해석 20ms → 책 조회 70ms → 배송 API 30ms → 미계측 10ms
req-02 | 200 | 전체 870ms
요청 해석 20ms → 책 조회 780ms → 배송 API 50ms → 미계측 20ms
병목 후보: 책 조회 780ms
req-03 | 504 | 전체 950ms
요청 해석 20ms → 책 조회 60ms → 배송 API 840ms → 미계측 30ms
병목 후보: 배송 API 840ms
req-02의 상태는 200이다. 실패 요청만 골랐다면 책 조회가 780ms 걸린 사례를 지나쳤을 것이다. 정상 예시의 책 조회는 70ms이고, 같은 요청의 배송 조회는 50ms다. 책 조회 구간에는 연결을 빌리는 시간이나 결과를 읽는 시간도 들어갈 수 있다. 다음 조사에서는 그 구간을 더 나눠 연결 대기와 실제 질의 실행 중 어느 쪽에서 시간이 늘었는지 확인한다.
req-03은 504로 끝났고 배송 조회가 840ms다. 여기서는 배송 응답을 기다리다 제한 시간이 지나 실패한 상황을 가정했다. 실제 조사에서는 배송 호출 시작 및 종료 기록과 시간 초과 사건을 같은 요청 ID로 찾는다. 배송 구간이 길다는 사실만으로 외부 서비스 안에서 시간이 소비된 위치까지 알 수는 없다. 호출 준비, 연결, 응답 대기처럼 호출자가 구분해 잴 수 있는 단계부터 확인한다. 세 건으로 계산한 오류율과 p95는 이 자료의 집계이며, 앞에서 정한 100건 조건을 만족하지 않는다.
실무에서 자주 틀리는 것
로그마다 요청 ID를 새로 만든다
잘못된 예는 단계가 바뀔 때 요청 ID도 바뀐다. 이 상태에서 완료 기록을 조회하면 조회 구간을 이어 붙일 수 없다.
events = []
for number, event_name in enumerate(("book_query", "request_finished"), 1):
events.append({"request_id": f"req-{number:02d}", "event": event_name})
print(events)
고친 예는 한 요청에 ID를 한 번 정하고 각 단계에서 같은 값을 사용한다. 실제 스팬 여러 개를 따로 식별할 필요가 있다면 스팬 ID를 별도 필드로 둔다.
request_id = "req-02"
events = []
for event_name in ("book_query", "request_finished"):
events.append({"request_id": request_id, "event": event_name})
print(events)
오류 로그 줄을 오류 요청으로 센다
잘못된 예의 분자는 실패 한 건에서 생성된 오류 두 줄이고, 분모는 완료 두 건이다. 이 식은 오류율을 100%로 출력한다.
error_log_levels = ["ERROR", "ERROR"]
completed_statuses = [200, 504]
print(f"{error_log_levels.count('ERROR') / len(completed_statuses):.1%}")
고친 예는 완료 상태만 사용해 50.0%를 출력한다. 운영에서는 같은 라우트와 시간 창의 완료를 골라 이 계산에 넣는다.
completed_statuses = [200, 504]
errors = sum(500 <= status < 600 for status in completed_statuses)
print(f"{errors / len(completed_statuses):.1%}")
창마다 계산한 백분위를 평균 낸다
잘못된 예는 표본이 하나인 창의 p95 900ms와 표본이 19개인 창의 p95 100ms를 평균 내서 500ms를 얻는다. 합친 창의 95번째 백분위를 구하려면 합친 자료에서 순위를 다시 정해야 한다.
window_p95_values = [900, 100]
print(sum(window_p95_values) / len(window_p95_values))
고친 예는 관측값 20개를 정렬해 19번째 값인 100ms를 고른다. 운영에서 원자료 대신 버킷별 건수를 저장한다면 동일한 버킷 경계로 수집한 빈도를 먼저 합쳐 목표 순위가 속한 버킷을 찾을 수 있다. 이 경우 백분위의 정밀도는 버킷 폭에 영향을 받는다.
first_window = [900]
second_window = [100] * 19
durations = sorted(first_window + second_window)
rank = (95 * len(durations) + 99) // 100
print(durations[rank - 1])
한눈에 보기
| 구성요소 | 요청에 적을 내용 | 결과를 확인하는 방법 |
|---|---|---|
| 구조화 로그 | 사건 이름과 필드, 시간 단위, 로그 수준을 정해 달라고 한다. | 예시 한 줄을 JSON으로 파싱하고, 변경분에서 요청 본문이나 배송 입력값을 로그에 추가했는지 확인한다. |
| 요청 추적 | 구간과 완료에 같은 요청 ID를 쓰고, 섞인 입력을 처리하라고 한다. | 로그 줄 순서를 뒤집어도 요청별 출력이 같은지 실행해 본다. 구간 시간을 하나 바꿔 병목 후보가 달라지는지 확인한다. |
| 지표 집계 | 완료 기준, 5xx의 범위, p95의 순위 공식, 빈 집계 처리를 명시한다. | 세 건이면 p95가 최댓값인지 손으로 계산한다. 빈 입력과 499, 500, 599 상태도 확인한다. |
| 경보 | 시간 창, 평가 간격, 최소 표본, 비교 연산, 연속 횟수를 명시한다. | 경계값과 표본 부족 사례를 대입한다. 변경분에서 연속 횟수를 초기화하는 조건을 확인한다. |
예를 들어 수정 요청에는 입력 범위와 예상 결과를 함께 적는다.
예제 분석기에서 로그 줄 순서를 뒤집어도 표준 출력이 같도록 유지한다. 완료 사건이 없는 경우에는 요청 0건과 오류율 및 p95 계산 불가를 표시한다. Python 표준 라이브러리만 사용한다. 추가하거나 바꾼 줄마다 어떤 경우를 처리하는지 설명한다.
답을 받으면 변경 전후 차이(diff)에서 완료 사건을 고르는 조건, 빈 입력 분기, 요청 ID로 묶는 부분을 확인한다. 임시 복사본에서 로그를 뒤집어 기본 출력과 비교하고, 빈 입력에서는 안내 한 줄을 확인한다. 마지막으로 정상 자료를 다시 실행해 기본 결과가 그대로인지 본다. 실행 결과와 예상이 다르면 어긋난 입력과 실제 출력을 다음 수정 요청에 함께 넣는다.
연습 문제
req-02의 책 조회를 100ms로, 배송 조회를 730ms로 바꾼다. 전체 지연은 그대로 둔다. 미계측 시간과 병목 후보를 계산한 뒤 실행 결과로 확인한다.req-03의 구간 중 배송 API 사건만 분석기에 전달하기 전에 제거한다. 5xx 건수, p95, 미계측 시간, 병목 후보가 각각 어떻게 달라지는지 적고, 이 출력으로 장애를 조사할 때 무엇부터 확인할지 설명한다.- p95 경보를 평가하는 다섯 창의 완료 건수와 p95가 차례대로 (110건, 510ms), (99건, 700ms), (120건, 501ms), (130건, 520ms), (100건, 600ms)다. 어느 평가에서 처음 통보하는지 구한다.
- 지표에 사용한 표본에서 5xx가 모두 사라졌지만 p95가 여전히 높다. 책 조회와 배송 조회 중 어느 구간을 먼저 볼지 결정할 수 있도록, 로그에서 고를 요청과 비교할 값을 적는다.
정답과 해설
- 구간 합계는 20 + 100 + 730 = 850ms다. 전체 870ms에서 빼면 미계측 시간은 20ms다. 전체가 지연 기준인 500ms를 넘고 배송 API가 730ms로 가장 길므로 병목 후보는 배송 API다.
- 완료 사건을 건드리지 않았으므로 5xx는 1건이고 p95는 950ms다. 남은 두 구간의 합계는 80ms이고, 미계측 시간은 870ms다. 프로그램은 남은 구간 중 가장 긴 책 조회 60ms를 후보로 표시한다. 이 사례에서는 미계측 시간이 전체 지연의 대부분을 차지하므로 배송 구간 기록의 누락 여부와 수집 설정부터 확인한다.
- 다섯 번째 평가에서 처음 통보한다. 두 번째 평가는 p95가 기준을 넘지만 완료가 99건이어서 연속 횟수를 초기화한다. 세 번째부터 다섯 번째까지는 완료가 최소 100건이고 p95가 모두 500ms를 넘는다.
- 같은 라우트와 관측 창에서 200으로 끝난 요청 중 느린 사례 몇 건과 평소 범위에 드는 사례를 고른다. 요청 ID별로 책 조회, 배송 조회, 미계측 시간을 나란히 비교한다. 느린 사례에서 책 조회만 길어지는 패턴이 반복되면 그 구간을 먼저 나눠서 계측한다. 배송 조회에서 같은 패턴이 보이면 배송 호출의 단계별 기록을 확인한다. 다음 장에서 설계도를 작성할 때 이렇게 조사에 사용한 필드와 통보 조건을 구성요소를 고른 이유와 함께 남긴다.