Einen Datenbank-Collector registrieren

Überblick — was diese Seite leistet

Verwaltung ▸ Collectors ist die Collector-Registry von InfraGuard (die Tabelle infr_collector). Sie holt fest verdrahtete Zugangsdaten und Host-Zuordnungen aus dem Code heraus und speichert sie als Daten. Collectors werden über die Zugriffsmethode (access) abstrahiert.

Dieser Artikel behandelt den access=database-Collector. Die InfraGuard-Anwendung verbindet sich in regelmäßigen Abständen mit einer registrierten DB und liest SHOW GLOBAL STATUS · information_schema.processlist · information_schema.tables, wobei sie eine Zeitreihe nach infr_db_metric schreibt. Ihre Datenzeilen werden dabei niemals gelesen oder geschrieben — nur Last- und Strukturmetriken.

DB-Collectors sind die Quelle für die Ansicht zur DB-Lastüberwachung und die Alarme. Registrieren Sie hier eine DB, dann erscheint sie automatisch in beiden.

Wann Sie das brauchen

• Sie möchten Verbindungsauslastung, Durchsatz, langsame Abfragen und Schemagröße produktiver MySQL-/MariaDB-Instanzen aus einer einzigen Konsole überwachen.
• Sie nehmen einen neuen DB-Server in die Überwachung auf.
• Sie möchten DB-Zugangsdaten, die bereits in .env liegen, wiederverwenden, ohne das Geheimnis erneut einzugeben (cred_ref=env:PREFIX).
• Sie verwalten mehrere DBs gleichzeitig (gemeinsame Vorgaben + Eintrags-Array) — verwenden Sie den Gruppeneditor.

Aufbau

Die Collector-Liste zeigt Karten, gruppiert nach Zugriffsmethode. access=database-Zeilen werden in eine einzige Gruppenkarte „Datenbanken“ zusammengefaltet (um einen Wildwuchs an Karten zu vermeiden). Über [Bearbeiten] auf der Gruppenkarte öffnet sich der Gruppeneditor (2 Reiter).

Reiter des Gruppeneditors

Auch wenn die Oberfläche nur eine Gruppenkarte zeigt, werden beim Speichern alle Einträge jeweils als eigene db@{alias}-Zeile per Upsert geschrieben (access=database). Die Erfassungskette, Service ▸ Datenbank und die Alarmzuordnung arbeiten sämtlich pro Collector. Wird ein Eintrag entfernt, wird auch dessen db@-Zeile gelöscht.

Felder je Collector (infr_collector)

So gehen Sie vor

1. Eine neue DB registrieren (Gruppeneditor)

1. Öffnen Sie Verwaltung ▸ Collectors.
2. Klicken Sie auf der Gruppenkarte „Datenbanken“ auf [Bearbeiten] → Reiter Allgemein und tragen Sie die gemeinsamen Werte ein.
   • driver: mysql oder mariadb
   • port: Vorgabe 3306
   • database: nur das Standardschema beim Verbinden — leer lassen, um sich mit information_schema zu verbinden (den Erfassungsumfang bestimmen die Rechte des Kontos)
   • username: das Überwachungskonto (z. B. infra_ro)
   • Schwelle für Rückstau (slow_time): Abfragen, die länger als diese Anzahl Sekunden laufen, zählen als „wartend/aufgestaut“ (1–60 s, Vorgabe 2)
   • cred_ref: env:PREFIX, um Zugangsdaten aus .env wiederzuverwenden
3. Reiter Datenbanken → [DB hinzufügen] → je Eintrag: alias (erforderlich) · host/IP · optional ein Passwort.
4. [Speichern]. Jeder Eintrag wird als db@{alias}-Zeile angelegt bzw. aktualisiert.

2. Umgang mit dem Geheimnis — zwei Wege

(A) Das Passwort direkt eingeben — im Passwortfeld eingetippt, wird es verschlüsselt in secret_enc abgelegt. Liste und API-Antworten geben den Klartext niemals preis; zurückgegeben werden nur die booleschen Werte has_secret/has_db_pw.

Das Passwort ist nur schreibend. Beim Bearbeiten bleibt der vorhandene Wert erhalten, wenn Sie das Passwortfeld leer lassen (kein Überschreiben). Um es ausdrücklich zu entfernen, verwenden Sie die Löschoption.

(B) Zugangsdaten aus .env wiederverwenden (cred_ref=env:PREFIX) — speichern Sie das Passwort nicht in der DB, sondern verweisen Sie auf einen bereits in .env vorhandenen Zugangsdatensatz. DbCollectorService::resolveConn() liest diese Schlüssel:

In config eingetragene Werte haben Vorrang; leere werden aus den PREFIX_*-Umgebungsvariablen ergänzt (host/port/database/username/password).

3. Serverweit wartende Abfragen — das PROCESS-Recht

Die beiden Kernmetriken (Verbindungsauslastung = Threads_running/Threads_connected/max_connections sowie QPS · Rate langsamer Abfragen = ΔQuestions/ΔSlow_queries) lassen sich mit einem einfachen Konto (USAGE) erfassen. Die serverweite Aggregation wartender Abfragen und die Größenanalyse aller Schemata erfordern jedoch zusätzliche Rechte.

• Ohne PROCESS → sichtbar ist nur die Processlist der eigenen Verbindung (waiting_scope=0).
• Mit PROCESS → alle Sitzungen werden aggregiert (waiting_scope=1, serverweit).

Ein Skript für ein Konto mit minimalen Rechten, das einmalig als root auf jedem Ziel-DB-Host auszuführen ist: sql/infr_db_monitor_grant.sql.

-- Dediziertes Nur-Lese-Konto (schränken Sie den Quell-Host auf die IP des InfraGuard-Anwendungsservers ein)
CREATE USER 'infra_ro'@'%' IDENTIFIED BY 'CHANGE_ME_TO_A_STRONG_SECRET';

-- Globale Beobachtungsrechte (KEIN Datenzugriff)
GRANT PROCESS, REPLICATION CLIENT ON *.* TO 'infra_ro'@'%';

-- Größenanalyse der Schemata (alle DBs · nur lesend). Für nur eine DB auf design.* einschränken
GRANT SELECT ON *.* TO 'infra_ro'@'%';

-- Begrenzung des Schadensradius — verhindert das Monopolisieren von Verbindungen (Lehre aus dem Vorfall [1040] vom 2026-08-06)
ALTER USER 'infra_ro'@'%' WITH MAX_USER_CONNECTIONS 5;
FLUSH PRIVILEGES;

MariaDB 10.5+ kann BINLOG MONITOR statt REPLICATION CLIENT verwenden. PROCESS und SELECT sind identisch.

4. Die Erfassung ausführen und prüfen

Die Erfassung übernimmt der artisan-Befehl infr:collect-db. Der Scheduler-Bereich des Entwicklungs-Launchers (composer dev) ruft ihn jede Minute auf.

# Einen Collector sofort einmalig abtasten (unter Umgehung der Sperre aus der Betriebsrichtlinie)
php artisan infr:collect-db --key=db@blue --force

# Alle registrierten DBs (is_run=1) gemäß der Richtlinie erfassen
php artisan infr:collect-db

Ob erfasst wird, entscheidet die Betriebsrichtlinie.

Verwenden Sie --key, um einen bestimmten Datenbank-Collector zu testen. Die Schaltflächen [Testen] / [Code abgleichen] gelten nur für access=web-Collectors und nicht für Datenbank-Collectors — prüfen Sie mit dem obigen Befehl.

5. Statusschwellen

DbCollectorService::statusOf() entscheidet anhand der Schwellenwerte aus der Betriebsrichtlinie zwischen up und degraded.

Datenquellen

Keine Verbindungslecks. DbCollectorService::withConn() erzeugt je Messung eine Laufzeitverbindung und schließt sie sofort im finally per DB::purge. Ein PDO-Timeout (Vorgabe 5 s) verhindert, dass Web-Requests und geplante Aufgaben an entfernter Latenz hängen bleiben. Starten Sie niemals einen Daemon mit Endlosschleife aus dem Scheduler — er erschöpft den gemeinsam genutzten MySQL-Verbindungspool (der Vorfall [1040] Too many connections vom 2026-08-06).

Zugriff

• Zugriff auf die Ansicht und sämtliches CRUD: Administrator (Stufe ≥ 10) — CollectorController::isAdmin() prüft in der Sitzung infr_user_level >= 10 (demo=1 und staff=5 kommen nicht hinein).
• Bei Fehlschlag 403. Speichern, Löschen und fill werden allesamt in infr_audit_log/den Logs auditiert.
• fill/{key} (das Einspeisen der Konfiguration in ein Mash-up unter Inventar ▸ Werkzeuge) ist eine Ausnahme für die Injektion von Geheimnissen (dokumentiert als §Option B) — nur für Administratoren und mit Audit.

Das vollständige Schema finden Sie unter Zugriffsstufen.

Fehlerbehebung und FAQ

• Bei wartenden Abfragen erscheint nur meine eigene Verbindung — das Recht PROCESS fehlt, daher waiting_scope=0. Vergeben Sie es über sql/infr_db_monitor_grant.sql.
• Die Schemagröße zeigt nur einige DBs — Sie benötigen ein globales SELECT-Recht (oder SELECT auf die betreffende DB).
• Ich habe das Passwort geändert, aber es wurde nicht übernommen — beim Bearbeiten erhält ein leeres Passwortfeld den vorhandenen Wert. Geben Sie einen neuen Wert ein, um ihn zu ersetzen.
• Die Karte zeigt im economy-Modus kurz down (rot) — die Erfassung ist im Rückstand, weil kein Konsolenbenutzer anwesend ist. Das Öffnen der Ansicht löst eine Messung auf Abruf aus (ensureFresh), oder Sie wechseln in den Modus always (siehe die Vermeidung von falschem Rot in Service ▸ Datenbank).
• Ich möchte den Schlüssel ändern — der Schlüssel db@{alias} ist beim Bearbeiten unveränderlich (zugunsten stabiler Alarmzuordnung). Fügen Sie einen Eintrag mit einem neuen Alias hinzu, um einen neuen Schlüssel zu erzeugen.
• Ich habe Stufe 5, bekomme aber keinen Zugriff — mancher Text spricht von „Stufe 5+“, die tatsächliche Hürde ist jedoch Administrator (Stufe ≥ 10).

Verwandte Themen

• Service ▸ Datenbank — die Ansicht zur Überwachung von DB-Last und -Struktur
• DB-Tuning-Konzepte — Konzepte zu Sperren, Cache und Index
• Infrastruktur ▸ Alarme — Alarme auf DB-Bedingungen (Warteschlange · langsame Abfragen)
• Betriebsrichtlinie — Erfassungsmodus, Intervall, Statusschwellen
• Zugriffsstufen — die Hürde der Administratorstufe
• Audit-Protokoll — Änderungshistorie der Collectors