正常性チェックと正常性エンドポイントを使用する

データ API ビルダーは、API のデータ ソースとエンティティの応答性と正常性を監視するための /health エンドポイントを提供します。 このエンドポイントは、構成されたデータ ソースとエンティティに対してチェックを実行し、設定したしきい値内で応答することを検証します。

ヘルスチェックの仕組み

• データ ソースごとに、単純なデータベース固有のクエリによって接続が検証され、応答時間が測定されます。
• REST または GraphQL が有効になっているエンティティごとに、クエリは最初の N 行を返して応答性を確認します。
• ストアド プロシージャは、パラメーターを必要とし、決定論的ではない可能性があるため、正常性チェックから自動的に除外されます。
• /health エンドポイントは、全体的な正常性を示す包括的なレポートにこれらの結果を集計します。

ランタイムの健全性設定

正常性チェックは、 runtime.health セクションで制御されます。

{
  "runtime": {
    "health": {
      "enabled": true,
      "roles": ["admin", "monitoring"],
      "cache-ttl-seconds": 10,
      "max-query-parallelism": 4
    }
  }
}

ロールベースのアクセス動作

• 開発モード (host.mode: development):

  • rolesが構成されていない場合: すべてのユーザーがアクセスできる正常性エンドポイント (匿名として扱われます)
  • rolesが構成されている場合: 指定されたロールのみがエンドポイントにアクセスできます

• 運用モード (host.mode: production):

  • roles 明示的に定義する必要があります
  • rolesを省略すると、すべての要求に対して 403 Forbidden が返されます
  • パブリック アクセスを許可するには、 "roles": ["anonymous"]

ルートパスの基本的なヘルスエンドポイント

/の簡略化された正常性エンドポイントは、認証なしで常にパブリックにアクセスできます。 正常性チェックを実行せずに、基本的なサービス情報 (バージョン、状態) を返します。

データ ソースの正常性の構成

各データ ソースは、 data-source.healthの正常性チェック用に構成できます。

{
  "data-source": {
    "health": {
      "enabled": true,
      "name": "primary-sql-db",
      "threshold-ms": 1500
    }
  }
}

エンティティのヘルス構成

エンティティ チェックは、 entities.{entity-name}.healthのエンティティごとに有効にすることができます。

{
  "entities": {
    "Book": {
      "health": {
        "enabled": true,
        "first": 50,
        "threshold-ms": 500
      }
    }
  }
}

エンティティの正常性チェックは、REST と GraphQL の両方 (有効な場合) に対して実行されます。 各エントリは、タグ (rest または graphql) を含むレポートに個別のエントリとして表示されます。

パフォーマンスとキャッシュに関する考慮事項

ヘルスチェック キャッシュ (cache-ttl-seconds):

• 迅速な要求によるシステムの過負荷を防ぎます
• 構成された TTL の完全な正常性レポートをキャッシュします
• キャッシュを無効にするには、 0 に設定します
• 既定値: 5 秒

クエリの並列処理 (max-query-parallelism):

• 同時に実行される正常性チェック クエリの数を制御します
• 値を大きくすると、チェックが高速化されますが、データベースの負荷が増加します
• 範囲: 1 ~ 8
• 既定値: 4
• エンティティが多い場合や、リソースの制限が厳しい場合は、より低い値を使用します

サンプルの正常性チェック応答

{
  "status": "Healthy",
  "version": "1.2.3",
  "app-name": "dab_oss_1.2.3",
  "timestamp": "2025-01-15T10:30:00Z",
  "configuration": {
    "rest": true,
    "graphql": true,
    "mcp": true,
    "caching": false,
    "telemetry": true,
    "mode": "Production"
  },
  "checks": [
    {
      "status": "Healthy",
      "name": "primary-sql-db",
      "tags": ["data-source"],
      "data": {
        "response-ms": 12,
        "threshold-ms": 1500
      }
    },
    {
      "status": "Healthy",
      "name": "Book",
      "tags": ["rest", "endpoint"],
      "data": {
        "response-ms": 45,
        "threshold-ms": 500
      }
    },
    {
      "status": "Healthy",
      "name": "Book",
      "tags": ["graphql", "endpoint"],
      "data": {
        "response-ms": 38,
        "threshold-ms": 500
      }
    }
  ]
}

その他の考慮事項

• 正常性チェックでは、エンティティとエンドポイントの承認が考慮されます。 ロールにエンティティにアクセスするためのアクセス許可がない場合は、ヘルスチェックが報告します。
• ストアド プロシージャは、パラメーターを必要とし、副作用が発生する可能性があるため、除外されます。
• rest.enabled: falseまたはgraphql.enabled: falseを持つエンティティは、これらのチェックから除外されます。
• data-source.health.enabled: falseすると、データ ソースのチェックはスキップされます。