Next.js ヘルスチェック & 可観測性スキル

Next.js ヘルスチェック & 可観測性スキル (nextjs-healthcheck)

Next.js App Router アプリケーションで、ヘルスチェックエンドポイント (/api/health)、ゼロ依存の Docker Compose ヘルスプローブ、Node.js ランタイムメトリクスを作成・維持するための、モジュール式で本番環境に即したワークフローです。

---

ワークフロー概要

flowchart TD
    A["1. プロジェクトスキャン<br/>(データベース & Docker Compose)"] --> B["2. /api/health 生成<br/>(メトリクス付きテンプレート)"]
    B --> C["3. Docker プローブ注入<br/>(docker-compose.yml)"]
    C --> D["4. 検証 & 確認<br/>(curl & docker compose ps)"]

---

ステップバイステップ実行手順書

アプリケーションのヘルスモニタリングを実装・検証するには、以下のチェックリストを順に実行してください。

1. プロジェクトの確認と依存関係の調査

• ルートハンドラパスの特定: プロジェクトが app/ または src/app/ のどちらを使用しているか確認します（対象: app/api/health/route.ts または src/app/api/health/route.ts）。
• データベース/外部ストアの検出: package.json をスキャンして ORM やクライアント（Prisma、Drizzle、Supabase、Mongoose、PostgreSQL、Redis）を特定します。database-probes.md を参照。
• Docker Compose ファイルの特定: docker-compose.yml、docker-compose.prod.yml、その他のコンポーズスタックを発見します。docker-compose-probes.md を参照。

2. ヘルスチェックルートハンドラの実装

• ルートテンプレートの選択:
  • データベースなしの場合: route-no-db.ts.template をデプロイ。
  • データベースありの場合: route-with-db.ts.template をデプロイし、プロジェクト固有のDBクライアントを厳密な2秒タイムアウトで配線。
• 動的実行の強制: export const dynamic = "force-dynamic"; と Cache-Control: no-store, no-cache, must-revalidate ヘッダーが存在することを確認。
• 非ブロッキングメトリクスの設定: V8 ヒープ使用率、イベントループ遅延（perf_hooks による p99 遅延）、プロセス稼働時間を収集。status-and-metrics.md を参照。
• HTTP ステータスコードの規律の徹底: healthy/degraded には 200 OK、unhealthy には 503 Service Unavailable を返す。

3. Docker Compose ヘルスプローブの設定

• Next.js サービスの識別: 検出したコンポーズファイル内の Next.js サービスブロック（nextjs-app、web、app）を調査。
• ヘルスチェックブロックの注入: docker-compose.healthcheck.template.yml から、ゼロ依存の Node.js fetch ヘルスプローブを追加。

4. 検証とテスト

• ローカル API テスト:

  curl -i http://localhost:3000/api/health
  

  有効な JSON ペイロード（status、timestamp、uptimeSeconds、checks）を含む HTTP 200 応答を確認。
• Compose ヘルスステータス確認:

  docker compose ps
  

  初期起動期間後、サービスの状態が (healthy) に遷移することを確認。

---

エッジケースと既知の AI 落とし穴

[!WARNING]

• force-dynamic の欠落: Next.js App Router は export const dynamic = "force-dynamic" を省略すると、ルート応答を静的に評価またはキャッシュし、タイムスタンプが古くなり、稼働時間メトリクスが凍結される可能性があります。
• ハングするデータベース接続: レースタイムアウト（最大2000ms）なしに外部データベースにクエリを実行しないでください。未処理のネットワークレイテンシはリクエストプールの枯渇に連鎖します。
• コンテナ内の外部ツール依存: Docker ヘルスチェックで curl や wget に依存しないでください。本番用の最小イメージ（例: node:alpine や distroless）にはこれらが含まれていないことがよくあります。Node.js のネイティブ fetch を node -e 経由で使用してください。
• シークレットの漏洩: 公開 /api/health 応答ペイロードに、データベース接続URL、パスワード、または内部の生のエラートレースを決して出力しないでください。

---

出力サマリースキーマ

ヘルスチェックの設定が完了したら、簡潔なサマリーレポートを提供します。

### ヘルスモニタリング設定完了

- **ルートハンドラ**: `[app/api/health/route.ts](file:///...)`
- **データベースプローブ**: [設定済み: Prisma / Drizzle / なし] (タイムアウト: 2000ms)
- **ランタイムメトリクス**: V8 ヒープ使用率 & イベントループ遅延 (p99)
- **更新された Docker Compose スタック**: `docker-compose.yml`、`docker-compose.prod.yml`
- **検証ステータス**: PASSED (HTTP 200 / コンテナ正常)

---

リファレンスガイドとテンプレート

• ステータスコードとメトリクスリファレンス — アーキテクチャステータスマトリックス、メモリ計算式、遅延しきい値。
• データベースプローブリファレンス — 検出チェックリスト、タイムアウトラッピング、ORMプローブパターン。
• Docker Compose プローブリファレンス — サービス照合ルールとゼロ依存 fetch 定義。
• ルートテンプレート (DBなし) — ステートレスアプリケーション用の完全なルートハンドラ。
• ルートテンプレート (DBあり) — 依存関係プローブ付きの完全なルートハンドラ。
• Docker Compose ヘルスチェックテンプレート — 再利用可能なコンポーズスニペット。