Prometheus で Python アプリを監視する

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)

バケットは判断に使うしきい値に合わせます。たとえば目標が 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)

最初の 2 件には同じ /orders/<int:order_id> が付きます。ルートに一致しないパスは unmatched にまとめ、スクレイプ自体は計測対象から外します。ユーザー ID、元の URL パス、クエリ文字列をラベルに含めると時系列が増えます。また、ここで計測が終わるのは Flask がフックにレスポンスを渡した時点です。ストリーミングでは、その後も本文の送信が続くことがあります。Flask のリクエスト処理順序(英語)

FastAPI にメトリクス用の ASGI アプリを組み込む

FastAPI では、クライアント付属の ASGI アプリで指標を公開できます。別のディレクトリに app.py として保存し、fastapi[standard] と prometheus-client をインストールしてから fastapi dev app.py で実行します。/orders/1 にアクセスして /metrics/ を取得します。マウントしたパスはプレフィックスとして扱われ、/metrics から末尾にスラッシュの付く URL へリダイレクトされます。取得先には最終 URL を指定します。

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 のワーカーがそれぞれメモリ上にレジストリを持つ場合、1 回のスクレイプで見えるのは応答したワーカーの分です。マルチプロセスモードでは、ワーカーグループごとに書き込み可能なディレクトリを用意します。起動前に 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 のベストプラクティス

最適なプランを相談する

お問い合わせ

コミュニティに参加

WeChatでスキャンして
コミュニティに参加

Guanceを試す

オンラインですぐに始めて、使った分だけお支払いください。

利用を開始

Guanceのプランを選択

コードリポジトリ