次の方法で共有

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

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

正常性チェック フローを示す図。

[前提条件]

既存の DAB 構成ファイルが必要です。

ツールを実行

ランタイムの正常性設定には dab configure を使用します。 データ ソースとエンティティの正常性設定の場合は、構成ファイルを更新します。

  1. ランタイムの正常性設定を構成します。

    dab configure \
  --runtime.health.enabled true \
  --runtime.health.roles "admin,monitoring" \
  --runtime.health.cache-ttl-seconds 10 \
  --runtime.health.max-query-parallelism 4

  2. DAB を起動します。

    dab start

正常性エンドポイントをテストする

  1. /health エンドポイントを呼び出します。

    curl http://localhost:5000/health

  2. 応答の状態が Healthyされていることを確認します。

ヘルスチェックの仕組み

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

コンフィギュレーション

次の例を使用して、ランタイム、データ ソース、エンティティの正常性設定を構成します。

{
  "runtime": {
    "health": {
      "enabled": true,
      "roles": ["admin", "monitoring"],
      "cache-ttl-seconds": 10,
      "max-query-parallelism": 4
    }
  },
  "data-source": {
    "health": {
      "enabled": true,
      "name": "primary-sql-db",
      "threshold-ms": 1500
    }
  },
  "entities": {
    "Book": {
      "health": {
        "enabled": true,
        "first": 50,
        "threshold-ms": 500
      }
    }
  }
}

Command-line

dab configureを使用してランタイムの正常性設定を構成します。

  • --runtime.health.enabled
  • --runtime.health.roles
  • --runtime.health.cache-ttl-seconds
  • --runtime.health.max-query-parallelism

Example

dab configure \
  --runtime.health.enabled true \
  --runtime.health.roles "admin,monitoring" \
  --runtime.health.cache-ttl-seconds 10 \
  --runtime.health.max-query-parallelism 4

結果の構成

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

ランタイムの健全性設定

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

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

プロパティ

enabled (ブール値、既定値: true)は、包括的な正常性エンドポイントをグローバルに有効または無効にします。

roles (string[], default: null)は、 /health エンドポイントへのアクセスを制御します。

cache-ttl-seconds (整数、既定値: 5)は、キャッシュされた正常性レポートの有効期間 (TTL) を設定します。

max-query-parallelism (整数、既定値: 4)は、最大同時正常性チェック クエリ (範囲: 1-8) を設定します。

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

開発モード (host.mode: development) では、 roles が構成されていない場合は、すべてのユーザーが正常性エンドポイントにアクセスできます。 rolesを構成すると、指定されたロールのみがエンドポイントにアクセスできます。 運用モード (host.mode: production) では、 roles を明示的に定義する必要があります。 rolesを省略すると、すべての要求に対して 403 Forbidden が返されます。 パブリック アクセスを許可するには、 "roles": ["anonymous"]設定します。

Important

ここで構成されたロールは、個々のエンティティ操作のアクセス許可ではなく、正常性エンドポイントへのアクセスを制御します。 エンティティにクエリを実行するアクセス許可がないロールの場合、そのエンティティの正常性チェックにはエラーが反映されます。これは予期される動作です。

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

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

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

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

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

プロパティ

enabled (ブール値、既定値: true)では、このデータ ソースの正常性チェックが有効になります。

name (文字列、既定値: データベース型の値) は、正常性レポートに表示される一意の識別子です。

threshold-ms (整数、既定値: 1000)は、許可されるクエリの最大実行時間 (ミリ秒単位) です。

name プロパティは省略可能です。 正常性レポートで同じデータベースの種類 (たとえば、2 つの SQL データベース) を共有する複数のデータ ソースを区別するのに役立ちます。

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

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

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

プロパティ

enabled (ブール値、既定値: true)では、エンティティの正常性チェックが有効になります。

first (整数、既定値: 100)は、正常性クエリによって返される行の数を設定します (範囲: 1-500)。

threshold-ms (整数、既定値: 1000)は、許可されるクエリの最大実行時間をミリ秒単位で設定します。

注

firstの値は、max-page-sizeのランタイム構成以下である必要があります。 first値を小さくすると、パフォーマンスが向上します。 多数のエンティティを監視する場合、 first 値が大きいほどレポートの速度が低下する可能性があります。

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

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

cache-ttl-seconds は、迅速な要求がシステムを圧倒するのを防ぎ、構成された有効期間の完全な正常性レポートをキャッシュします。 キャッシュを無効にするには、 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すると、データ ソースのチェックはスキップされます。

  • Last updated on