ゲートウェイアラートのランブック
deploy/prometheus/alert-rules.yml にあるすべてのアラートの runbook_url アノテーションは、このファイルの節を指します(アンカー = アラート名)。scripts/quality/alert_check.py チェッカーは、式で使うメトリクスが pkg/metrics で宣言されていること、ランブックのアンカーが存在すること、SLO メトリクス(レイテンシ/エラー/キュー)が存在することを検証します。
オーナーチャネルのテスト発火(webhook + Telegram)
オーナーへの配信は deploy/alertmanager/alertmanager.yml で配線されています。デフォルトルートは汎用 webhook レシーバ(ALERT_WEBHOOK_URL)へ行き、severity=" critical" のアラートは webhook と Telegram bot の 両方 を持つレシーバへファンアウトします(ALERT_TG_BOT_TOKEN / ALERT_TG_CHAT_ID)。3 つとも、起動時に deploy/docker-compose.prod.yml によって設定へレンダリングされる環境変数です(プレースホルダ + sed)。未設定の値は無効なブラックホールのままなので、スタックは起動し続けます。
合成の critical アラートを発火させ、約 1 分以内(group_wait 10s)に Telegram チャットと webhook へ届くことを期待します。
curl -sS -X POST http://127.0.0.1:9093/api/v2/alerts \
-H 'Content-Type: application/json' -d '[{
"labels": {
"alertname": "TestFireCritical",
"severity": "critical",
"job": "manual-test"
},
"annotations": {
"summary": "Manual delivery test — ignore",
"runbook_url": "https://example.com/test"
}
}]'
確認:
- Telegram: bot が設定済みチャットへ投稿します(約 5 分後に "resolved" メッセージ、
resolve_timeout)。 - Webhook: レシーバへのヒットごとに POST が 1 回です。
- 設定エラーまたは送信失敗:
docker compose -f deploy/docker-compose.prod.yml logs alertmanager(送信失敗はtelegram/apiまたはwebhookのエラーとして、401/400 とともに出ます。通常は誤ったトークン/チャット id、または無効なブラックホールのデフォルトです)。 - 設定変更にはコンテナの再起動が必要です(ファイルは起動時にレンダリングされます)。
severity: "warning" のテストアラートは、デフォルトの webhook のみのルートを試します。critical と warning の経路の違いを確認するのに有用です。
HighGatewayLatencyP99
P99 レイテンシが 100 ms を超えています。確認箇所: どのモデル/プロバイダが gateway_http_request_duration_seconds_bucket の上位か。上流の健全性(UpstreamDown)とサーキットブレーカーを確認します。対処: 問題のモデルをルール/ティアの変更で移動し、プロバイダへのネットワーク到達性を確認します。
HighGatewayErrorRate
5 分間で 5xx が 5% を超えています。path/status 別の gateway_http_requests_total と、ゲートウェイログを確認します。よくある原因: プロバイダの 401(キー)、429(クォータ。クールダウンを参照)、上流の 5xx(フォールバックが発火しているはずです。HighFallbackRate を参照)。
UpstreamDown
上流が 1 分を超えて不健全です。url ごとの gateway_upstream_health_state を確認し、環境変数のキーでプロバイダへ curl します。対処: モデルを無効化する(enabled=false)か、フォールバック優先度を上げます。
CircuitBreakerOpen
ブレーカーが開いています。上流が系統的に失敗しています。gateway_circuit_breaker_*。対処: ブレーカーを「リセット」しないでください。上流を修正します。一時的にモデルをローテーションから外します。
HighFallbackRate
リクエストの 20% 超がフォールバックへ行っています。プライマリチャネルが不安定です。プライマリモデルのレイテンシ/エラーを確認します。フォールバックモデルの方が高額になることがあります。予算への影響を監視します。
LowClassifierAccuracy
hard の割合が 30% を超えています。複雑なリクエストが疑わしいほど多い(またはトラフィックのドリフト)状態です。source 別の gateway_classifier_class_total を確 認し、再較正します。
DiskSpaceLow
パーティションの空きが 10% 未満です。wal/ログを掃除し、保持を確認します。
HighDeductionFailureRate
残高不足のため、1 秒あたり 0.5 件を超える控除がスキップされています。組織残高(負の上位)を確認します。急なクレジット枯渇の可能性があります(オーバーシュートの計測、NEXT-17 を参照)。
HighGatewayErrorRateV2
より厳しい閾値(10%)です。HighGatewayErrorRate と同様に扱います。
ServiceDown
スクレイプ対象に到達できません。サービスのコンテナ/プロセスと、/metrics の可用性(Prometheus の bearer キー)を確認します。
SLO
- レイテンシ:
gateway_http_request_duration_seconds(ヒストグラム)。 - エラー:
gateway_http_requests_total{status=~"5.."}。 - loggerd キュー:
gateway_loggerd_events_in_flight/events_consumed。
ShadowHighErrorRate
シャドウミラーリングが高いエラー率を示しています(シャドウトラフィックが流れている間、15 分間で 50% 超)。シャドウはクライアントに影響しません(トラフィックはミラーされます)が、比較データが信頼できなくなります。yabanin_shadow_* を確認します。ミラー先上流の可用性と、そのキーです。
ShadowBudgetBurn
シャドウ実験の予算が尽きています(shadow_budget_exhausted_total が増加しています)。対処: シャドウの割合を止めるか狭めるか、実験の予算を補充します。シャドウ設定を参照してください。