環境
- litellm v1.91.0
やりたいこと
litellm proxyを自前でデプロイするにあたってちゃんと動いているかをヘルスチェックしたい。litellmにはいくつかヘルスチェックのエンドポイントがあるのでまとめた。
ヘルスチェックエンドポイント一覧
認証不要
GET /health/liveliness/GET /health/liveness- ワーカープロセスの生死確認（Kubernetes liveness probe向け）
- uvicornワーカーが応答できるかを監視する
- 正常時は
"I'm alive!"を返す - グレースフルシャットダウン中はHTTP 503 +
{"status": "shutting_down"}を返す
GET /health/readiness- ロードバランサーやKubernetes readiness probe向けの準備状態確認
- DB接続状態（DB設定がある場合）やシャットダウン中かどうかを監視する
- 正常時は
{"status": "healthy", "db": "connected"}などを返す - DB切断中またはグレースフルシャットダウン中はHTTP 503を返す
general_settings.allow_public_health_readiness_details: trueで詳細情報も返せる
GET /health/drain- Kubernetes preStopフック向け。ワーカーを安全に排出する
- in-flightリクエストが0になるか
GRACEFUL_SHUTDOWN_TIMEOUT経過するまでブロックし、以降のreadiness/livelinessを503に切り替える - デフォルトは無効で、
general_settings.enable_drain_endpoint: trueが必要 - オプションでトークン認証（
X-Drain-Token）を設定可能
認証必要（Authorization: Bearer <API_KEY>）
GET /health- config.yamlに定義した全LLMエンドポイントの疎通確認
- 各モデルへの実際のリクエスト送信結果（healthy / unhealthy一覧）を監視する
?model=<名前>/?model_id=<ID>で絞り込み可能- 指定モデルが全てunhealthyの場合はHTTP 503を返す
background_health_checks: trueの場合はキャッシュ済み結果を返す。非管理者にはapi_base/api_versionが隠蔽される
GET /health/readiness/details- 認証ありの詳細な準備状態診断
- DB接続状態・キャッシュ種別（Redis Semantic Cacheの場合はインデックス情報）・コールバック一覧・litellmバージョン・ログレベルを監視する
- DB接続不能時はHTTP 503を返す
GET /health/liveliness- 認証なしと同一エンドポイントで、認証なしでもアクセス可能なためプローブに認証は不要
GET /health/services- 外部連携サービスの疎通確認（管理者専用）
- Slack / Datadog / Langfuse / Arize / Galileo / New Relic / SQS / Email / Webhookなどを監視対象とする
?service=<サービス名>が必須- 各サービスにモックリクエストを送信して疎通を確認する
GET /health/history- 過去のヘルスチェック結果の履歴確認
- DB（
LiteLLM_HealthCheckResultsテーブル）に保存されたヘルスチェック履歴を監視する ?model=/?status_filter=healthy|unhealthy/?limit=/?offset=が指定可能- DB設定が必要
GET /health/latest- 各モデルの最新ヘルスチェック結果を一括取得する
- DBに保存されたmodel_id / model_nameごとの最新1件を監視対象とする
- DB設定が必要
GET /health/shared-status- 複数Pod間でのヘルスチェック協調状態の確認
- Redisロック状態・キャッシュ状態（
use_shared_health_check: true時）を監視する - Redis設定が必要で、無効な場合は
{"shared_health_check_enabled": false}を返す
GET /health/backlog- このワーカーの現在処理中リクエスト数（キュー深度）の確認
- uvicornワーカー上でin-flight中のHTTPリクエスト数を監視する
- Pod単位の負荷計測・スロットリング判断に使う
GET /health/license- ライセンス情報の確認
has_license/license_type（community/enterprise）/expiration_date/ 利用可能フィーチャー / 上限値（max_users, max_teams）を監視対象とする- ライセンスキー自体は返さない
POST /health/test_connection- 特定モデルへの接続テスト（手動確認・デバッグ用）
- 指定したモデル・パラメータで実際にリクエストを送信し疎通を確認する
- リクエストボディには
mode（chat / embedding / image_generationなど）、litellm_params、model_infoを指定する - config登録済みモデルは
model_info.id指定で資格情報を自動補完する。os.environ/参照はセキュリティ上禁止
廃止済み
GET /test- プロキシの到達性確認（deprecated）
- 代替として
/health/livelinessを使用すること
ざっくり目的別使い分け
- プロセスが生きているかの死活監視（Uptime Kuma、監視SaaS、nginx/ALBのヘルスチェック先など）:
GET /health/liveliness - LLMエンドポイントの疎通確認（実際にモデルへリクエストが通るか）:
GET /health - デプロイ直後・再起動後にDB接続が確立できているかの確認:
GET /health/readiness - 外部サービス連携（Slack通知やログ基盤など）の疎通確認:
GET /health/services?service=<名前> - ヘルスチェックの実行履歴を後から追いたい場合:
GET /health/latest/GET /health/history - 現在の処理中リクエスト数から負荷状況を見たい場合:
GET /health/backlog - ライセンス情報や上限値を確認したい場合:
GET /health/license
