コンテンツにスキップ

2026-04 Uptime Kuma monitor automation 要件

背景

  • production の継続監視は Sentry Uptime を正規運用としているが、release / trace 相関に寄った SaaS 内導線だけではなく、独立した外部 watchdog として Uptime Kuma でも同じ safe probe を監視したい。
  • 監視先の運用 URL は https://milestone-monitoring.exe.xyz を前提とする。Uptime Kuma 自体は エリアルのサーバー内にホストされており、一般的な外部 SaaS と同じ前提では扱わない。ただし ingress が exe.dev ログインで保護されるため、CLI 適用時は追加 header または内部到達 URL が必要になる場合がある。
  • 既存の scheduled-safe-probes.yml は staging・version・WordPress admin redirect を含む manual fallback として残し、Uptime Kuma は continuous-safe な endpoint に限定する。
  • 現時点では Grafana / Prometheus / Loki / log shipper を Fly.io の正式運用 app として常設しない。observability/ 配下の該当設定はローカル確認または将来導入用テンプレートとして保持し、独立 watchdog の主系は Uptime Kuma とする。

合意事項

1. 正本

  • 外形監視 endpoint の checked-in 正本は observability/external-monitor-endpoints.json とする。
  • endpoint catalog から Kuma 向け monitor 定義を構築する導線は scripts/ops/external-monitor-endpoints.mjs とする。
  • shared endpoint catalog の手動確認は scripts/ops/check-external-monitor-endpoints.mjs からのみ実行する。
  • monitor の list / upsert は scripts/ops/uptime-kuma-monitors.mjs からのみ実行する。
  • Uptime Kuma への反映は generated JSON を native import する方式ではなく、 scripts/ops/uptime-kuma-monitors.mjs が shared catalog を読んで Socket.IO 管理 API へ upsert する方式とする。
  • 実行導線は pnpm run monitor:endpoints:check、just monitor-endpoints-check --target uptime-kuma、 pnpm run uptime:kuma、just uptime-kuma-list、just uptime-kuma-upsert を正規とする。pnpm run uptime:kuma は shared catalog を直接読んで runtime に Kuma monitor 定義を構築する。

2. 初期 monitor セット

  • 初期セットは production 限定 とし、以下 4 本を正規運用とする。
  • Production Storefront readiness
    • type: json-query
    • url: https://order.ritsubi-platform.com/api/health/ready
    • interval: 300s
    • verification: 2xx かつ $.status == "ok"
  • Production Vendure readiness
    • type: json-query
    • url: https://commerce.ritsubi-platform.com/health/ready
    • interval: 300s
    • verification: 2xx かつ $.status == "ok"
  • Production Vendure schema drift
    • type: json-query
    • url: https://commerce.ritsubi-platform.com/health/ready
    • interval: 300s
    • verification: 2xx かつ $.dependencies.schemaDrift == "ok"
    • 目的: schemaDrift dependency が ok であることを外部 watchdog でも継続監視し、 drift 検知そのものが欠落したケースも down として扱う。
  • Production WordPress login
    • type: http
    • url: https://cms.ritsubi-platform.com/wp-login.php
    • interval: 300s
    • verification: HTTP 200
  • Production Storefront readiness / Production Vendure readiness / Production Vendure schema drift は shared endpoint catalog 上で Sentry / Uptime Kuma の両方に enable する。
  • Production WordPress login は client-facing external watchdog としては有効だが、 現時点では対応する Sentry project slug を固定できないため Uptime Kuma only とする。
  • React Dashboard は専用 health endpoint が無いため monitor 対象に含めない。
  • storefront /api/health/cms と version endpoint は診断 / metadata 用途なので monitor 初期セットに含めない。

3. 認証と接続前提

  • UPTIME_KUMA_URL の既定 target は https://milestone-monitoring.exe.xyz とする。
  • ただし、この URL の実体は エリアルのサーバー内の Uptime Kuma である。接続障害の切り分けでは、対象アプリ endpoint の健全性だけでなく、エリアル側サーバーからの疎通 / 認証 / ingress 条件も確認対象に含める。
  • 認証は UPTIME_KUMA_TOKEN を優先し、代替として UPTIME_KUMA_USERNAME / UPTIME_KUMA_PASSWORD を許可する。
  • exe.dev ログイン配下で追加 header が必要な場合は UPTIME_KUMA_HEADERS_JSON を使う。header に機密情報を含むため checked-in config やドキュメントへ具体値を保存しない。
  • self-signed な内部経路を使う場合のみ UPTIME_KUMA_INSECURE=1 を許可する。
  • token / password / session cookie は local / CI ともにコードへ保存しない。

4. upsert セマンティクス

  • monitor は name 一致で既存 monitor を照合し、同名があれば update、無ければ create する。
  • config に notificationIDList を書かない限り、既存 monitor の通知アタッチメントは維持する。
  • shared catalog に存在しない monitor を delete しない。
  • --dry-run は live auth が無い環境でも config validation と planned payload の確認ができること。

5. GitHub Actions fallback に残す範囲

  • 以下は引き続き scheduled-safe-probes.yml の正式運用とする。
  • staging の safe probe
  • version endpoint の確認
  • WordPress admin redirect (/wp-admin/post-new.php?post_type=product_detail)
  • deploy 前 gate / browser synthetic / Sentry observability canary は既存の GitHub Actions を継続する。

受け入れ観点

  1. shared endpoint catalog を直接読んだ --dry-run が成功し、live auth が無くても plan を確認できること。
  2. Uptime Kuma へ接続できる認証情報がある環境では list / upsert が動作し、同名 monitor を create / update できること。
  3. just monitor-endpoints-check --target uptime-kuma または pnpm run monitor:endpoints:check で shared catalog の endpoint 群を一発確認でき、--target uptime-kuma で Uptime Kuma と同じ json assertion を評価できること。
  4. monitoring runbook に prerequisite / usage / shared catalog の位置づけ / monitor の意味、exe.dev 配下での auth caveat、manual fallback の位置づけが記載されていること。
  5. docs 上で「Sentry は release / trace 相関の主系」「Uptime Kuma は独立 watchdog」「staging / version / deep probe は manual fallback」「Grafana / Prometheus / Loki は現時点で Fly.io 正式運用対象ではない」という整理が明示されていること。