Prometheus로 Python 애플리케이션 모니터링하기
Prometheus Python 클라이언트로 Flask와 FastAPI 지표를 노출하고, 라우트 레이블과 지연 시간 버킷을 설정하며 여러 워커의 지표를 집계합니다.
주문 API의 응답이 느려졌는데도 Python의 가비지 컬렉션 지표는 그대로일 수 있습니다. 먼저 라우트별 요청 수와 지연 시간 분포를 측정합니다. 그런 다음 Prometheus가 가져온 지표가 의도한 프로세스나 워커 그룹 전체를 포함하는지 확인합니다.
로컬 엔드포인트에서 카운터 노출하기
가상 환경에 prometheus-client를 설치합니다. 아래 예제를 demo.py로 저장한 뒤 python demo.py를 실행하고 http://127.0.0.1:8000/metrics에 접속합니다. 클라이언트는 데몬 스레드에서 HTTP 서버를 띄웁니다. 메인 스레드가 요청을 흉내 내며 계속 실행되므로 여러 번 수집하면 카운터가 늘어나는 것을 확인할 수 있습니다.
from prometheus_client import start_http_server, Counter
import random, time
REQUEST_COUNT = Counter('app_requests_total', 'Total requests', ['method', 'endpoint'])
def handle_request():
REQUEST_COUNT.labels(method='GET', endpoint='/api').inc()
if __name__ == '__main__':
start_http_server(8000, addr='127.0.0.1')
while True:
handle_request()
time.sleep(random.random())
기본 레지스트리에는 python_gc_objects_collected_total 같은 지표도 포함됩니다. 스크레이프가 성공했다면 엔드포인트에는 도달한 것입니다. 애플리케이션 카운터가 증가하려면 값을 올리는 코드가 실제로 실행되어야 합니다. Python 클라이언트의 HTTP 노출 방식(영문)
측정하려는 값에 맞게 지표 유형 고르기
Counter는 이벤트의 누적 횟수이며 프로세스가 재시작하면 초기화됩니다. Gauge는 큐 깊이처럼 오르내리는 값에 적합합니다. Histogram은 각 버킷의 경계값 이하인 관측 횟수를 세고 전체 횟수와 합계도 내보냅니다. 지연 시간에는 초 단위를 씁니다. 다음 예제는 애플리케이션 작업을 대신하는 짧은 대기 시간을 측정합니다.
from prometheus_client import Counter, Gauge, Histogram
from time import sleep
errors = Counter('app_errors_total', 'Total errors', ['type'])
queue_depth = Gauge('job_queue_depth', 'Current queue depth')
queue_depth.set(42)
latency = Histogram('request_duration_seconds', 'Request latency',
buckets=[0.01, 0.05, 0.1, 0.5, 1, 5])
with latency.time():
sleep(0.02)
버킷 경계는 실제 판단에 쓰는 기준에 맞춥니다. 목표가 300ms라면 0.3을 경계에 넣어 300ms 안에 처리한 요청 수를 누적 버킷에서 구할 수 있습니다. 레이블 값의 조합마다 별도 시계열이 생긴다는 점도 고려합니다. Prometheus의 Histogram과 Summary(영문)
Flask 라우트를 계측하고 레이블 확인하기
아래 예제를 app.py로 저장합니다. Flask와 클라이언트를 설치한 다음 로컬에서 flask --app app run을 실행합니다. /orders/1과 /orders/2, 그리고 존재하지 않는 경로에 요청을 보낸 뒤 /metrics를 확인합니다.
from flask import Flask, Response, g, request
from prometheus_client import Counter, Histogram, generate_latest, CONTENT_TYPE_LATEST
import time
app = Flask(__name__)
REQS = Counter('http_requests_total', 'Requests', ['method', 'endpoint', 'status'])
LAT = Histogram('http_request_duration_seconds', 'Latency', ['endpoint'],
buckets=[0.01, 0.05, 0.1, 0.3, 0.5, 1, 5])
@app.get('/orders/<int:order_id>')
def order(order_id):
return {'order_id': order_id}
@app.before_request
def before():
g.start_time = time.perf_counter()
@app.after_request
def after(resp):
if request.endpoint != 'metrics':
endpoint = request.url_rule.rule if request.url_rule else 'unmatched'
method = request.method if request.method in {'GET', 'HEAD', 'OPTIONS'} else 'OTHER'
REQS.labels(method, endpoint, str(resp.status_code)).inc()
LAT.labels(endpoint).observe(time.perf_counter() - g.start_time)
return resp
@app.route('/metrics')
def metrics():
return Response(generate_latest(), content_type=CONTENT_TYPE_LATEST)
두 주문 요청에는 같은 /orders/<int:order_id> 레이블이 붙습니다. 라우트에 일치하지 않는 요청은 unmatched로 묶고 지표 수집 요청은 계측에서 제외합니다. 사용자 ID나 원본 경로, 쿼리 문자열은 지표 레이블에서 빼 둡니다. 이 타이머는 Flask가 훅에 응답 객체를 전달한 시점에 멈춥니다. 스트리밍 응답이라면 그 뒤에도 본문 전송이 이어질 수 있습니다. Flask 요청 처리 순서(영문)
FastAPI에 ASGI 지표 앱 마운트하기
FastAPI에서는 클라이언트가 제공하는 ASGI 앱으로 지표를 노출할 수 있습니다. 아래 예제를 별도 디렉터리의 app.py에 저장하고 fastapi[standard]와 prometheus-client를 설치한 뒤 fastapi dev app.py로 실행합니다. /orders/1에 요청을 보내고 /metrics/를 조회합니다. 마운트는 경로 접두사를 등록하므로 /metrics 요청은 끝에 슬래시가 붙은 주소로 리디렉션됩니다. 수집기는 최종 경로를 사용하도록 설정합니다.
from fastapi import FastAPI
from prometheus_client import Counter, make_asgi_app
app = FastAPI()
ORDERS_READ = Counter('orders_read_total', 'Completed order reads')
@app.get('/orders/{order_id}')
def order(order_id: int):
ORDERS_READ.inc()
return {'order_id': order_id}
app.mount('/metrics', make_asgi_app())
마운트는 레지스트리를 노출합니다. 이 예제의 업무 카운터는 주문 조회 라우트에서 직접 증가시킵니다. 여러 라우트의 처리 시간과 상태를 기록하려면 어떤 라우트에 일치했는지 확인할 수 있도록 계측하고 오류와 처리 종료를 언제 기록할지 정합니다. Python 클라이언트의 FastAPI 예제(영문)
여러 워커의 지표를 한 번에 수집하기
앞의 예제는 단일 프로세스용입니다. Gunicorn 워커마다 레지스트리가 메모리에 따로 있으면 스크레이프 요청에 응답한 워커의 지표만 보입니다. 멀티프로세스 모드에서는 워커 그룹별로 쓰기 가능한 디렉터리를 준비하고 시작 전에 PROMETHEUS_MULTIPROC_DIR을 지정합니다. 그룹 전체를 재시작할 때는 이전 그룹이 종료된 뒤 디렉터리를 비웁니다. 수집 요청을 처리할 때 새 CollectorRegistry에 MultiProcessCollector를 등록합니다. 같은 애플리케이션 지표를 그 레지스트리에 직접 등록하면 중복으로 노출될 수 있습니다.
Gunicorn의 child_exit에서 multiprocess.mark_process_dead(worker.pid)를 호출하면 종료한 워커의 live 모드 Gauge 파일이 삭제됩니다. Counter와 Histogram 파일은 실행 중의 누적 관측값이 사라지지 않도록 유지합니다. 워커별 처리 중 요청 수를 합하려면 Gauge의 livesum 모드를 사용할 수 있습니다. 프로세스 CPU나 메모리 컬렉터가 이 방식으로 워커 그룹 전체의 지표로 합쳐지지는 않습니다. Python 클라이언트의 멀티프로세스 모드(영문)
Celery의 prefork 모드에도 같은 경계가 적용됩니다. 부모 프로세스에서만 HTTP로 노출하면 자식 프로세스의 메모리에 있는 카운터는 보이지 않습니다. 호스트에 종속된 배치 작업의 스냅샷에는 Node Exporter의 textfile collector를 사용할 수 있습니다. 큐 깊이와 적체는 브로커 지표에서 확인합니다. Python 클라이언트의 textfile 연동(영문)
버킷으로 P99 지연 시간 추정하기
Flask 예제의 Histogram을 사용하는 쿼리입니다. 수집 작업 python-api에 속한 인스턴스를 합쳐 라우트별 P99를 추정합니다.
histogram_quantile(
0.99,
sum by (le, endpoint) (
rate(http_request_duration_seconds_bucket{job="python-api"}[5m])
)
)
먼저 각 시계열에 rate를 적용해 재시작으로 인한 카운터 초기화를 처리하고, 그다음 합산합니다. 버킷 경계인 le를 남기고 합산하는 인스턴스에는 같은 경계를 씁니다. 결과는 초 단위의 추정값이므로 요청량과 함께 봅니다. Python 클라이언트의 Summary는 횟수와 합계를 노출하며 클라이언트에서 분위수를 계산하지 않습니다. Python Summary 설명(영문)
수집 엔드포인트는 권한이 있는 모니터링 클라이언트만 접근할 수 있게 둡니다. Guance로 수집하려면 Python 서비스의 스크레이프 URL을 DataKit Prom 입력 설정(영문)에 지정합니다. 성공 요청과 오류 요청을 발생시켜 카운터와 버킷의 변화를 확인하고 같은 워커 그룹을 중복 수집하지 않는지 살펴봅니다. 이후 같은 시간 범위의 애플리케이션 지표와 APM 트레이스를 나란히 볼 수 있습니다. Prometheus 운영 모범 사례
