メインコンテンツまでスキップ

ゲートウェイアラートのランブック

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 が増加しています)。対処: シャドウの割合を止めるか狭めるか、実験の予算を補充します。シャドウ設定を参照してください。