用 Prometheus 監控 Python 應用程式

以 Prometheus Python 用戶端埋點並公開 Flask 與 FastAPI 指標,設定路由標籤和延遲桶,彙整多個 worker 的觀測值。

最佳實務
觀測設施與遙測資料流的插畫

訂單 API 變慢時,Python 的垃圾回收指標可能毫無變化。先量測各路由的請求數與延遲分布,再確認 Prometheus 一次抓取涵蓋的是單一程序,還是你要觀察的整組 worker。

在本機端點公開計數器

在虛擬環境安裝 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)

桶界線要配合你判斷延遲的門檻。如果目標是 300 ms,就把 0.3 設成桶界線,從累積桶得知在 300 ms 內處理的請求數。每組標籤值都會產生獨立的時間序列。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 請求生命週期(英文)

把 ASGI 指標應用掛載到 FastAPI

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 範例(英文)

抓取多個 worker 的指標

前面的範例採用單一程序。Gunicorn 的各個 worker 如果只把指標登錄留在各自的記憶體,一次抓取就只會看到回應的那個 worker。使用用戶端的多程序模式時,為每組 worker 準備可寫入的專用目錄,在啟動前設定 PROMETHEUS_MULTIPROC_DIR。整組重啟時,等舊程序結束再清空目錄。處理抓取請求時,在新的 CollectorRegistry 上註冊 MultiProcessCollector。如果又把同一組應用指標直接註冊到該登錄,可能會重複輸出。

Gunicorn 可在 child_exit 呼叫 multiprocess.mark_process_dead(worker.pid),移除退出 worker 的 live 模式 Gauge 檔案。Counter 和 Histogram 的檔案要留到這一輪程序結束,才能保留先前的觀測值。要將每個 worker 正在處理的請求數加總,可以使用 Gauge 的 livesum。這個機制不會把程序 CPU 和記憶體的收集器合併為整組指標。Python 用戶端多程序模式(英文)

Celery 使用 prefork 時也要注意程序邊界。只從父程序開 HTTP 端點,讀不到各子程序在記憶體裡的計數器。如果是綁定主機的批次工作,可以用 Node Exporter 的 textfile collector 讀取快照。佇列深度和積壓則要看訊息代理的指標。Python 用戶端 textfile collector 說明(英文)

從延遲桶估算 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,讓 Prometheus 處理各自的計數器重設,再進行加總。保留 le 桶界線,並確保一起聚合的各實例使用相同桶設定。結果是以秒為單位的估計值,應與請求量一起看。Python 用戶端的 Summary 提供觀測次數及總和,分位數需要其他方式計算。Python Summary 文件(英文)

限制抓取端點只對獲授權的監控用戶端開放。如果用觀測雲收集指標,在 DataKit Prom 收集器設定(簡體中文)填入 Python 服務的抓取網址。送出成功與錯誤請求,確認計數器和桶的變化符合預期,並檢查同一組 worker 是否被重複收集。接著可對照同一時段的應用程式指標和 APM 追蹤。Prometheus 最佳實務

取得專屬方案

聯絡我們

加入社群

微信扫码
加入官方交流群

立即體驗

在线开通,按量计费,真正的云服务!

立即開始

选择观测云版本

代码托管平台