データベースコレクターの登録

概要 — 何をする画面か

管理 ▸ コレクター は InfraGuard の コレクターレジストリ（infr_collector テーブル）です。ハードコードされた認証情報とホストマップをコードから引き上げ、データとして保存します。コレクターは アクセス方式（access） で抽象化されます。

本記事は access=database のコレクター を扱います。InfraGuard アプリは登録済みDBへ定期的に接続し、SHOW GLOBAL STATUS · information_schema.processlist · information_schema.tables を読み取って、時系列を infr_db_metric に書き込みます。データ行を読むことも書くこともありません — 負荷と構造の指標だけです。

DBコレクターは DB負荷監視画面 と 警報 の データ元 です。ここでDBを1つ登録すれば、両方の画面に自動的に現れます。

どんなときに使うか

• 稼働中の MySQL / MariaDB インスタンスの 接続飽和率・スループット・スロークエリ・スキーマ容量 を単一のコンソールから監視したいとき。
• 新しいDBサーバーを監視対象に組み込むとき。
• すでに .env にあるDBの認証情報を、シークレットを入力し直さずに 再利用 したいとき（cred_ref=env:PREFIX）。
• 複数のDBをまとめて管理するとき（共通の既定値＋項目の配列） — グループエディター を使います。

画面構成

コレクター一覧は、アクセス方式ごとにグループ化されたカードで表示されます。access=database の行は 1つの「データベース」グループカード にまとめられます（カードの乱立を防ぐためです）。グループカードの ［編集］ で グループエディター（2タブ）が開きます。

グループエディターのタブ

UI上は単一のグループカードに見えますが、保存すると各項目がそれぞれの db@{alias} 行として upsert されます（access=database）。収集パイプライン、サービス ▸ データベース、警報のターゲット指定は、いずれも コレクター単位 で動作します。項目を削除すると、その db@ 行も削除されます。

コレクターごとの項目（infr_collector）

使い方

1. 新しいDBを登録する（グループエディター）

1. 管理 ▸ コレクター を開きます。
2. 「データベース」グループカードで ［編集］ をクリックし、基本 タブで共通の値を入力します。
   • driver：mysql または mariadb
   • port：既定は 3306
   • database：接続時の既定スキーマにすぎません — 空にすると information_schema へ接続します（収集の対象範囲はアカウントの権限で決まります）
   • username：監視用のアカウント（例：infra_ro）
   • 待ち行列のしきい値（slow_time）：この秒数を超えて実行中のクエリを「待ち／滞留」として数えます（1〜60秒、既定は2）
   • cred_ref：.env の認証情報を再利用する場合は env:PREFIX
3. データベース タブ → ［DBを追加］ → 項目ごとに：alias（必須） · host／IP · 任意でパスワード。
4. ［保存］。各項目が db@{alias} 行として作成／更新されます。

2. シークレットの扱い — 2つの方法

（A）パスワードを直接入力する — パスワード欄に入力すると、暗号化されて secret_enc に保存されます。一覧やAPIの応答が 平文を露出することはありません。返されるのは has_secret／has_db_pw の真偽値だけです。

パスワードは書き込み専用です。編集時に パスワード欄を空のままにすると、既存の値が保持されます（上書きされません）。明示的に削除したい場合は、クリアの操作を使ってください。

（B）.env の認証情報を再利用する（cred_ref=env:PREFIX） — パスワードをDBに保存せず、すでに .env にある認証情報のセットを参照します。DbCollectorService::resolveConn() は次のキーを読み取ります。

config に入力された値が優先され、空の値は PREFIX_* の env（host/port/database/username/password）から補われます。

3. サーバー全体の待ちクエリ — PROCESS 権限

2つの中核指標（接続飽和率 ＝ Threads_running／Threads_connected／max_connections、および QPS · スロー率 ＝ ΔQuestions／ΔSlow_queries）は、素の（USAGE）アカウント でも収集できます。ただし、サーバー全体の待ちクエリの集計 と スキーマ全体の容量分析 には追加の権限が必要です。

• PROCESS がない場合 → 自分の接続のプロセスリストしか見えません（waiting_scope=0）。
• PROCESS がある場合 → すべてのセッションが集計されます（waiting_scope=1、サーバー全体）。

対象のDBホストごとに root で一度だけ実行する、最小権限アカウント用のスクリプトです：sql/infr_db_monitor_grant.sql。

-- 専用の読み取り専用アカウント（接続元ホストは InfraGuard アプリサーバーのIPに絞ってください）
CREATE USER 'infra_ro'@'%' IDENTIFIED BY 'CHANGE_ME_TO_A_STRONG_SECRET';

-- グローバルな観測権限（データへのアクセスではありません）
GRANT PROCESS, REPLICATION CLIENT ON *.* TO 'infra_ro'@'%';

-- スキーマ容量の分析（全DB · 読み取り専用）。1つのDBだけなら design.* に絞ってください
GRANT SELECT ON *.* TO 'infra_ro'@'%';

-- 影響範囲の隔離 — 接続の独占を防ぎます（2026-08-06 の [1040] 障害からの教訓）
ALTER USER 'infra_ro'@'%' WITH MAX_USER_CONNECTIONS 5;
FLUSH PRIVILEGES;

MariaDB 10.5以降では REPLICATION CLIENT の代わりに BINLOG MONITOR を使えます。PROCESS と SELECT は同じです。

4. 収集を実行して確認する

収集は infr:collect-db artisan コマンドが行います。開発用ランチャー（composer dev）のスケジューラーペインが、毎分これを呼び出します。

# 1つのコレクターを今すぐ1回サンプリングします（運用ポリシーのゲートを迂回）
php artisan infr:collect-db --key=db@blue --force

# 登録済みの全DB（is_run=1）をポリシーに従って収集します
php artisan infr:collect-db

収集を実行するかどうかは 運用ポリシー が決めます。

特定のデータベースコレクターをテストするには --key を使ってください。［テスト］／［コード同期］ ボタンは access=web のコレクター専用で、データベースコレクターには適用されません。上記のコマンドで確認してください。

5. 状態のしきい値

DbCollectorService::statusOf() は、運用ポリシー のしきい値と照らして up／degraded を判定します。

データソース

接続リークはありません。 DbCollectorService::withConn() はサンプルごとにランタイム接続を作り、finally の中で DB::purge により即座に閉じます。PDOのタイムアウト（既定5秒）により、リモートの遅延でWebリクエストやスケジュールがブロックされることはありません。無限ループのデーモンをスケジューラーから起動してはいけません — 共有 MySQL の接続プールを枯渇させます（2026-08-06 の [1040] Too many connections 障害）。

アクセス権限

• 画面へのアクセスとすべてのCRUD：管理者（レベル10以上） — CollectorController::isAdmin() がセッションの infr_user_level >= 10 を確認します（demo＝1 と staff＝5 は入れません）。
• 失敗した場合は 403。保存・削除・fill はいずれも infr_audit_log／ログに監査記録されます。
• fill/{key}（インベントリ ▸ ツール のマッシュアップへ設定を注入する機能）は シークレット注入の例外（§オプションB として文書化）です — 管理者専用＋監査あり。

体系の全体は アクセスレベル を参照してください。

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

• 待ちクエリに自分の接続しか表示されない — PROCESS 権限がないため waiting_scope=0 です。sql/infr_db_monitor_grant.sql で付与してください。
• スキーマ容量が一部のDBしか表示されない — グローバルな SELECT 権限（または対象DBへの SELECT）が必要です。
• パスワードを変えたのに反映されない — 編集時にパスワード欄が空だと、既存の値が保持されます。置き換えるには新しい値を入力してください。
• economy モードでカードが一瞬 down（赤）になる — コンソールの利用者がいないため収集が遅れています。画面を開けばオンデマンドで1回サンプリングされます（ensureFresh）。あるいは always モードに切り替えてください（サービス ▸ データベースの false-red 回避を参照）。
• キーを変更したい — db@{alias} のキーは編集時には変更できません（警報のターゲット指定を安定させるためです）。新しい alias の項目を追加して、新しいキーを作ってください。
• レベル5なのにアクセスを拒否される — 「レベル5以上」と書かれた記述もありますが、実際のゲートは 管理者（レベル10以上） です。

関連項目

• サービス ▸ データベース — DBの負荷／構造を監視する画面
• DB チューニングの概念 — ロック・キャッシュ・インデックスの概念
• インフラ ▸ 警報 — DB条件の警報（待ち行列 · スロークエリ）
• 運用ポリシー — 収集モード、間隔、状態のしきい値
• アクセスレベル — 管理者レベルのゲート
• 監査ログ — コレクターの変更履歴