サービス ▸ データベース — InfraGuard マニュアル

概要 — 何をする画面か

サービス ▸ データベース（/service/database）は、登録されたデータベースコレクター（access=database）に直接接続して負荷指標をサンプリングし、スキーマ構造を分析するライブ監視画面です。データベースごとに1枚のカードとして描画され、どのカードも2つの負荷軸を一目で示します。

データベース監視は2つの負荷軸を中心に組み立てられています。

軸	問い	主要指標
① 同時実行負荷	いま何がどれだけ滞留しているか	`threads_running`、接続飽和率（`conn_pct`）、待機クエリ（`waiting`）
② スループットと非効率	どれだけ処理し、どれだけ無駄があるか	QPS（`Δquestions/Δt`）、slow rate（`Δslow_queries/Δt`）

その上で、スキーマ分析（総容量・上位データベース・最大のテーブル・エンジン構成）、効率スコア（バッファプールのキャッシュヒット率・インデックス使用率）、そして InnoDB メモリ管理ブロック（ダーティページのフラッシュ・チェックポイント）を提供します。

この画面は対象 DB にエージェントを一切インストールしません。InfraGuard アプリは登録された認証情報でリモートの MySQL/MariaDB に接続し、SHOW GLOBAL STATUS / information_schema のクエリを発行するだけです。

こんなときに使う

データベースが急に遅くなった — 接続が飽和したのか、同時実行が急増したのか、スロークエリが増えたのかを即座に見分ける。
コネクションプール調整の前後 — threads_connected / max_connections の飽和率を時系列で観察する。
キャパシティ計画 — どのスキーマ／テーブルがディスクを最も消費しているか、エンジン構成はどうかを確認する。
InnoDB のフラッシュ圧の診断 — ダーティページがしきい値以下で健全に循環しているか、チェックポイント年齢が redo 容量に対してどこまで進んでいるか。
キャッシュ／インデックス効率のレビュー — バッファプールのヒット率とインデックス使用率をチューニングの根拠として読む。

画面構成

上部 KPI

KPI	意味
DB 数	登録された `access=database` コレクターの総数
Up / Degraded / Down	カード状態（`up`/`degraded`/`down`）の集計
合計 QPS	全カードの QPS の合計
接続数	全カードの `threads_connected` の合計

カードヘッダー

ホストラベル（コレクターの host_alias → config.host → cred_ref の env ホスト、の順）。
ドライバー（mysql/mariadb）、データベース名、稼働時間、状態バッジ。

① 同時実行負荷

接続飽和率のリングゲージ = threads_connected / max_connections。
Running（threads_running）— 実際に CPU を消費しているスレッド。
Waiting（滞留）（waiting）— 処理時間がしきい値（既定 2 秒）を超えたクエリ。PROCESS 権限の有無に応じて、サーバー全体を数えるか自身の接続のみを数えるかが決まります（スコープはカードに表示されます）。

② スループットと非効率

QPS スパークライン = Δquestions / Δt（直近 60 件の成功サンプル）。
slow rate = Δslow_queries / Δt、および slow total（slow_queries）。

カードフッター — 効率・ロック

指標	計算式	評価
キャッシュヒット率	`1 − Δinnodb_buffer_pool_reads / Δinnodb_buffer_pool_read_requests`	優秀 ≥99.5% · 良好 ≥98% · 普通 ≥90%
インデックス使用率	`Δhandler_read_key / (Δhandler_read_key + Δhandler_read_rnd_next)`	優秀 ≥90% · 良好 ≥70% · 普通 ≥40%
lock	`innodb_row_lock_time_avg`（行ロック待ちの平均、ミリ秒）	低いほど良い

各指標のラベル（cache・index・lock・checkpoint）には、原因と対処を説明する教育用ポップオーバーが付いています（例: innodb_buffer_pool_size を増やす、カバリングインデックスを使う、ギャップロックを避ける）。

スキーマ分析（折りたたみ）

既定では折りたたまれており、[展開] で開きます。information_schema.tables から集計し、総容量・テーブル数・スキーマ数・容量上位 8 スキーマ・容量上位 14 テーブル・エンジン構成を表示します。

スキーマ分析はサーバー側で本質的に重いクエリ（実測約3.5秒）のため、30分のロングキャッシュで回避します。スケジューラー（infr:collect-db）がキャッシュを温めるので、Web リクエストは常にキャッシュにヒットします。キャッシュが空のあいだセクションは一時的に隠れ、次のポーリングで現れます。

InnoDB メモリ管理（ダーティページのフラッシュ）

ダーティページの時系列 ＋ 「適正値」（しきい値）のオーバーレイ — MAX（innodb_max_dirty_pages_pct）と LWM（innodb_max_dirty_pages_pct_lwm）を絶対ページ数に換算したもの（恣意的な定数ではなく、InnoDB が実際に積極的なフラッシュを始める地点）。
チェックポイント年齢（Log sequence number − Last checkpoint at）を redo 容量に対する百分率で表示。
バッファプールのサイズと、サーバー RAM（alias で結合した OS インスタンスの mem_mb）に対する比率。

カードの並び

カードグリッドはドラッグでの並べ替え（SortableJS · 順序は localStorage に保持）と row-span マソンリーに対応します。画面は 30秒ポーリングで更新されます。

使い方

まず管理 ▸ コレクターで access=database のコレクターを登録します。host/port/database/username ＋パスワード（コレクターに Crypt 暗号化して保存）を入力するか、cred_ref = env:PREFIX を設定して既存の .env 認証情報セットを再利用します。
/service/database を開くと、登録済みのデータベースがカードとして並びます。入場時に最新サンプルが 60 秒より古い場合は、即時の単発サンプリング（ensureFresh）が行われます。
ヘッダーの状態バッジで問題のある DB を特定し、2つの負荷軸（同時実行／スループット）で原因を絞り込みます。
スキーマ分析を展開して最大のスキーマ／テーブルを確認します（高さが変わるとマソンリーが自動で再配置されます）。
カードをドラッグして、気になるデータベースを上部に浮かせます（順序はブラウザーに保存されます）。

cred_ref による認証情報の再利用

cred_ref = env:PREFIX を使うと、次のキーが .env から読み込まれるため、秘密情報を DB に保存せずに済みます。

例: env:STATS_DB → blue サーバー、env:STATS_GLORY_DB → glory サーバー。

サーバー全体の待機クエリを見るには

waiting をサーバー全体で集計するには、監視アカウントに PROCESS 権限が必要です。権限がなければ自身の接続だけが数えられます。最小権限の監視アカウントは次のとおりです。

CREATE USER 'infra_monitor'@'%' IDENTIFIED BY 'YOUR_DB_PASSWORD';
GRANT PROCESS, SELECT ON *.* TO 'infra_monitor'@'%';
FLUSH PRIVILEGES;

スコープの判定（PROCESS を持つかどうか）はアカウントごとに固定されるため、1時間キャッシュされます。あとから権限を付与した場合は1時間以内に反映されます（即時に反映するにはキャッシュをクリアしてください）。

データソース

起点となるクエリ（リモート DB で実行）

クエリ	目的
`SHOW GLOBAL STATUS`	全 threads · questions · slow_queries · bytes · バッファプール · handler · InnoDB カウンター
`SELECT @@GLOBAL.max_connections` など	max_connections、InnoDB のフラッシュ設定（1時間キャッシュ）
`information_schema.processlist`	待機クエリ数＋スコープ判定
`information_schema.tables`	スキーマ分析（30分キャッシュ）
`SHOW ENGINE INNODB STATUS`	チェックポイント年齢（LSN − 最終チェックポイント · `PROCESS` が必要）
`SHOW GRANTS FOR CURRENT_USER()`	`PROCESS` 権限の検出（スコープ）

保存テーブル

サンプリングしたデータは infr_db_metric 時系列（マイグレーション 000681）に書き込まれます。累積カウンター（questions/slow_queries/bytes_*）も保存され、次のサンプルが差分で QPS · slow rate · 効率スコアを計算できるようにします。

infr_db_metric
  collector_id  host  sampled_at  uptime_sec
  threads_connected/running/cached  max_connections  conn_pct
  waiting  waiting_scope
  questions  slow_queries  qps  slow_qps
  bytes_received/sent  recv_bps/sent_bps  innodb_row_lock_waits
  ok  message  raw(json: efficiency + InnoDB memory-management derivations)

接続リークを起こさない（[1040] の教訓）。 すべてのサンプリングは実行時に接続を作り、finally で直ちに DB::purge します。PDO タイムアウト（既定 5 秒）により、遅いリモート相手に Web リクエストやスケジューラーが固まることを防ぎます。この規律が崩れると、共有 MySQL の max_connections を使い切り、本番にまで影響が及びます。

収集スケジュール · ゲーティング

時系列は artisan コマンド infr:collect-db が埋めます。これは1回実行して終了します（デーモンではありません）。スケジューラーが毎分呼び出します。

# 単一のコレクターについて即時に1回サンプリングする（ゲートを迂回）
php artisan infr:collect-db --key=db@blue --force

運用ポリシー（管理 ▸ 運用ポリシー · OpsPolicy）がスケジュール実行をゲーティングします。

設定	既定値	意味
`db_collect_mode`	`economy`	economy ＝コンソール利用者（プレゼンス）がいるときだけ収集 · always ＝常時収集
`db_collect_interval_sec`	`60`	収集間隔（秒）。毎分ティックしますが、実効周期はこの値です

degraded/down のしきい値

DbCollectorService::statusOf が OpsPolicy::dbThresholds() を通じて状態を判定します。

理由	条件	既定しきい値
`conn_saturation`	`conn_pct ≥`	80%
`high_concurrency`	`threads_running ≥`	40
`query_backlog`	`waiting ≥`	5
`slow_query_rate`	`slow_qps ≥`	1/秒
`down`	サンプルなし／`ok=false`、または最新サンプルが 5 分より古い（`stale`）	—

理由が1つでもあれば degraded、1つもなければ up です。

アクセス権限

この画面は infr.auth グループ内の読み取り専用コンソールで、最小読み取りレベルは demo=1 です。
このページに書き込みエンドポイントはありません。対象 DB の認証情報の登録・編集は管理 ▸ コレクター（admin=10、level≥5 ゲート）で行います。
しきい値と収集モードの変更は管理 ▸ 運用ポリシー（admin）で行います。

トラブルシューティングと FAQ

カードが「down」と表示される

no_credentials — config の host/username が空、または cred_ref=env:PREFIX に対応する env キーが存在しない。
stale — 最新サンプルが 5 分より古い。スケジューラー（infr:collect-db）が動いているか、economy モードならコンソール利用者がいるかを確認します。
その他のメッセージ — 接続失敗の原因（認証拒否、ホスト到達不能、タイムアウト）がそのまま表示されます。php artisan infr:collect-db --key=<key> --force で診断します。

QPS ／ slow rate ／効率スコアが「—」になる

派生値は直前の成功サンプルとの差分として計算されます。最初のサンプル時、DB 再起動後（uptime が減少 → カウンターがリセット）、またはカウンターが逆行したときは値が信頼できないため、null (—) のままになります。2回目のサンプルからは正常に表示されます。

待機クエリが「自身の接続のみ」と表示される

監視アカウントにグローバルな PROCESS 権限がないため、information_schema.processlist では自身の接続しか見えません。サーバー全体の待機クエリを見るにはの SQL で PROCESS を付与してください（スコープキャッシュが切れる1時間以内に反映されます）。

メモリ管理／チェックポイントのセクションが空

メモリ管理には innodb_buffer_pool_pages_total が必要です（古いサンプルでは非表示）。
チェックポイント年齢は SHOW ENGINE INNODB STATUS から解析します（→ PROCESS が必要）。権限がない場合、チェックポイントの線と注釈は穏当に省略されます。

スキーマ分析が一瞬空になってから現れる

analysisCached はキャッシュ限定のルックアップです。初回の入場時はキャッシュが空でセクションは隠れ、スケジューラーが温めた後、次の30秒ポーリングで現れます。失敗は 30 秒しかキャッシュされない（成功は30分）ため、一時的なエラーが長く固定されることはありません。