HQbird für Entwickler
Für Anwendungsentwickler
Welche Abfrage zuerst optimieren? Welcher Code hat den Fehler verursacht? Wer hält den Rekord bei einem Konflikt? Der Agent sammelt die Antworten aus Trace und Statistiken direkt auf dem Server. Der Entwickler sieht sie im Browser und meldet sich nicht am Server an.
- 1 Min. Trace-Dateien
- 3 Fenster pro Tag Performance-Bericht
- nach Plan Abfragegruppierung
- 15 Min. Konfliktsuche
- REST Lokale API für Skripte und CI
trace · process_traces · perf report
Performance-Bericht
Der Agent hält ständig eine Trace-Sitzung offen. Jede Minute komprimiert er die Ausgabe in eine Datei und berechnet Summen für jede Abfrage. Nach Ende eines Fensters fasst der Agent die Minuten zu einem Bericht zusammen: die langsamsten Abfragen und die schwersten nach Fetches, Lese- und Schreibvorgängen. Jede Abfrage zeigt ihre Anzahl an Ausführungen.
- 1Trace-Sitzungfbtracemgr läuft ständig; ein Watchdog startet eine verlorene Sitzung neu
- 2Minutendateikomprimierte Trace-Ausgabe einmal pro Minute
- 3Minutensummenfür jede Abfrage: Ausführungen, Zeit, Fetches, Lese- und Schreibvorgänge, Marks
- 4Fensterberichtinnerhalb von 5 Minuten nach Ende des Fensters; bis zu 20 Abfragen in jeder Rangliste
- 5✓ HQ MonitorSeite Perf Report; Link aus dem Health-Bericht
Warum nach Plan gruppieren
Wenn ein Programm Werte direkt in den SQL-Text schreibt, ergibt jeder Wert einen neuen Text. In einem realen Fall wuchs die Anzahl verschiedener Texte pro Minute von 204 auf 83.825. Tausende „verschiedene“ Abfragen sind in Wirklichkeit eine Abfrage mit einem Plan. Daher gruppiert der Agent Abfragen standardmäßig nach einem Schlüssel: die ersten 10 Zeichen des SQL ohne Kommentare plus den Ausführungsplan. Eine Abfrage ohne Plan behält ihren vollständigen Text. Sie ändern den Modus in den Agent-Einstellungen, Feld „Perf group by“: nach Plan oder nach vollständigem SQL-Text. Nach Text werden Dateien und Berichte deutlich größer. Wechseln Sie im Beispiel unten den Modus und vergleichen Sie die Ranglisten.
Abfragen in einer Minute
Rangliste nach Fetches
| Berichtstabelle | Was sie zeigt |
|---|---|
| Top SQL nach Dauer | Die langsamsten Ausführungen: Zeit und Anzahl der Datensätze. |
| Top SQL nach Fetches, Lese- und Schreibvorgängen | Summen für das Fenster: Ausführungen, Zeit, Fetches, Lese- und Schreibvorgänge, Marks; Anteil am gesamten Fenster; Durchschnitt und Maximum pro Ausführung. |
| Prozesse und Adressen | Last nach Programm und nach Client-Adresse: Verbindungen, Zeit, Anzahl verschiedener Pläne und Abfragen. |
| Abfragezeile | Vollständiges SQL, PLAN, Parameter und Statistiken pro Tabelle: natural, index, update, insert, delete, backout, purge, expunge. |
| Zehn Ranglisten in Tabs | Dauer, Häufigkeit, Gesamtzeit, Fetches, Lese- und Schreibvorgänge, Pläne, Tags, Prozeduren und Trigger. Für jede Metrik sehen Sie die Streuung der Werte. |
| Beispielausführung | Wann sie lief, welcher Client und von welcher Adresse, in welcher Datenbank. Wenn die Ausführung mit einem Fehler endete, sehen Sie ihn; jede Abfrage hat einen Zähler für fehlgeschlagene Ausführungen. |
| Ausführungen pro Stunde | Wie oft und wie lange die Abfrage in jeder Stunde des Fensters lief. |
| Datenbanken | Summen nach Datenbank des Servers und den Hauptdatenbanken jeder Abfrage. |
Vergleich, Verlauf und Bericht auf Anfrage
Der Fensterbericht beantwortet die Frage „Was war heute schwer“. Drei neue Funktionen beantworten die Fragen „Was hat sich geändert“ und „Was ist in dieser Stunde passiert“.
- Zwei Fenster vergleichenZwei Berichte nebeneinander: welche Abfragen langsamer wurden, welche neu hinzukamen und welche verschwanden.
- Abfrageverlauf für 30 TageWie sich Zeit und Anzahl der Ausführungen einer Abfrage von Fenster zu Fenster änderten.
- Filter nach DatenbankEin Bericht nur für eine Datenbank. Ein Link auf der Datenbankseite führt zur Berichtsseite.
- Zu den Traces der MinuteVon einer Abfrage im Bericht zu den Traces der Minute, in der sie lief.
- Bericht auf AnfrageDie Schaltfläche Build report… erstellt einen Bericht für einen beliebigen Zeitraum bis zu 24 Stunden. Filter: Datenbank, Mindestdauer, Programm. Der Agent erstellt jeweils einen solchen Bericht und behält die letzten 20.
- Suchen und HerunterladenEin Suchfeld für den Abfragetext. Sie können die Quelldatei des Berichts herunterladen.
- Unvollständiger Bericht wird markiertWenn einige Trace-Dateien noch nicht angekommen sind, wird der Bericht als unvollständig markiert. Der Bericht behält nur die Spitze jeder Rangliste, daher steht auf der Seite „nicht in der Rangliste“, nicht „nicht ausgeführt“.
- Prozeduren und TriggerDiese Ranglisten füllen sich, wenn die Trace-Einstellungen die Protokollierung von Prozedur- und Trigger-Ende aktivieren. Standardmäßig ist diese Protokollierung aus.
- Aus dem Health-BerichtDie Schaltfläche Perf report öffnet das richtige Fenster. Die Abfragezeilen sind markiert, und die erste ist bereits aufgeklappt.
- Abfrage und TabelleDer Tab Queries der gstat-Statistiken verknüpft Abfragen mit den Tabellen und Indizes, die sie lesen.
- Eine Minute im DatenbankdiagrammEin Klick auf eine Minute zeigt die schweren Abfragen aus Trace und alle Verbindungen dieser Minute.
- SQL kopierenMit oder ohne Parameter, direkt in Ihr eigenes Tool. Im Demo-Modus sind die Schaltflächen ausgeblendet.
trace · Errors
SQL-Fehler mit Client-Daten
Ein Benutzer sagt „das Programm hat einen Fehler gemeldet“. Die Seite Errors zeigt jeden Firebird-Fehler aus Trace: Zeit, Verbindung, Datenbank, Text und Client. Mit Programmname, Adresse und Firebird-Funktion finden Sie den Fehler in Ihrem Code leicht.
Fehlerblock im Trace
Zeile auf der Seite Errors
- Gleiche Fehler — eine ZeileEine Zeile pro Minute, Datenbank und Fehlertyp, mit einem ×N-Zähler. Ein Hinweis zeigt die erste und letzte Zeit und die Anzahl der Verbindungen.
- FilterInclude und Exclude nach Text, Datenbank, Programm, Adresse und Funktion. Ein Klick auf ein Programm oder eine Adresse behält nur dessen Fehler.
- CSV exportierenAlle Zeilen mit angewendeten Filtern, in UTF-8 mit BOM: Excel öffnet die Datei sofort in Spalten.
- Wenn kein Programm vorhanden istViele JDBC- und .NET-Treiber senden den Programmnamen nicht. Dann ist die Client-Zeile kürzer.
trace_monitor_conflicts · find_deadlocks
Konflikte und Deadlocks
Der Fehler „update conflicts with concurrent update“ sagt für sich genommen wenig aus. Sie müssen wissen, was die andere Transaktion getan hat. Dafür hält der Agent eine zweite Trace-Sitzung offen, die für Datenänderungen und Fehler eingerichtet ist. Alle 15 Minuten sucht er nach Konflikten und erstellt einen Bericht.
So liest man den Bericht
Links ist die Liste der Minuten mit Konflikten. Jede Gruppe ist eine Transaktion, die Konflikte verursacht hat: die Transaktionsnummer und der Zeitpunkt des Fehlers.
Die linke Spalte zeigt die Fehler: Verbindung, Programm, Firebird-Codes und die fehlgeschlagene Abfrage. Die rechte Spalte zeigt die erfolgreichen Abfragen der konkurrierenden Transaktion: Zeit, Verbindung, Transaktionsnummer, Programm. Jede Abfrage hat ihr SQL, ihre Parameter, Statistiken und Tabellen.
Die Seitenadresse enthält Datum und Minute. Sie können den Link an einen Kollegen senden.
| Parameter | Standard | Bedeutung |
|---|---|---|
| Konfliktsuche | alle 15 Minuten | Die letzte Minute wird übersprungen: Der Trace schreibt sie noch. |
| Suchtiefe | 3 Stunden | Wie viel Verlauf vor dem Konflikt durchsucht wird, um die Abfragen der anderen Transaktion zu finden. |
| Aufbewahrung des Roh-Trace | 6 Stunden | Rohdateien der Konfliktsitzung sammeln sich nicht auf dem Server an. Berichte werden aufbewahrt und an HQ Monitor gesendet. |
gstat · Indizes · Metadaten
Wie sich die Datenbank verändert
Einmal täglich erstellt der Agent vollständige gstat-Statistiken. HQ Monitor analysiert die Datei: Größe von Tabellen und Indizes, Datensatzversionen, BLOBs, Indextiefe. Der Tab „Analyse und Empfehlungen“ zeigt, was nicht stimmt und was zu tun ist.
| Tab | Was er dem Entwickler bietet |
|---|---|
| Tabellen | Größe von Daten, Indizes und BLOBs, Anzahl der Datensätze, Datensatzversionen und die maximale Anzahl Versionen eines Datensatzes. |
| Indizes | Tiefe, Seiten, eindeutige Werte, Duplikate. Tiefe 4 ist eine gelbe Zeile, 5 und mehr ist rot. |
| Abfragen und Verknüpfungen | Welche Abfragen eine Tabelle oder einen Index lesen. Daten aus Performance-Berichten zeitlich nahe am Snapshot. |
| Trends | Vergleich von 5, 10, 20 oder 30 Snapshots; Änderungsschwelle 10 %, 2 % oder 0,5 %. Die „+25 %“-Prognose ab drei oder mehr Snapshots. |
| Export | JSON mit den Messwerten und Excel mit der vollständigen Analyse. |
- IndexstatistikenStandardmäßig aus; Sie aktivieren sie in den Agent-Einstellungen. Dann zählt der Agent alle 6 Stunden inaktive Indizes und Indizes mit schlechter Selektivität. Ein nach einem Restore nicht neu erstellter Index ist im Health-Bericht schwerwiegend.
- WachstumsprognoseDer Chip „+25 %“ in der Datenbanktabelle zeigt die am schnellsten wachsende Tabelle oder den Index und öffnet die Prognose.
- Schema-ExportDer Agent exportiert die Datenbank-Metadaten mit
isql -xund bewahrt Archive nach Datum auf. - Metadaten-VerfolgungStandardmäßig aus; Sie aktivieren sie in den Agent-Einstellungen. Alle 6 Stunden vergleicht der Agent den neuen Schema-Export mit dem vorherigen und zeichnet auf, wann sich das Schema geändert hat.
LWM · MON$ · Clients
Verbindungen: lang laufende Transaktionen und Client-Versionen
Eine vergessene Transaktion bremst die gesamte Datenbank aus: Datensatzversionen sammeln sich an, und die Garbage Collection kommt zum Stillstand.
Jede Minute schreibt der Agent die Transaktionszähler und Verbindungsdaten. Im Datenbankdiagramm wächst Next − OAT, wenn eine Transaktion lange offen bleibt. Die Verbindungstabelle für diese Minute, sortiert nach Act.Tran, zeigt das Programm, die Adresse und den Prozess, der die Transaktion hält. Mehr zu den Zählern finden Sie auf der Server-Health-Seite.
Einmal täglich liest der Agent, welche Client-Bibliotheken sich mit der Datenbank verbinden und wie viele Verbindungen jede hat. Die Zeile „Nicht erkannt. Alte Version?“ bedeutet meist eine alte Client-Bibliothek.
- MON$-MetrikenEinmal pro Stunde: Speicher nach Programm, die 5 Verbindungen mit dem meisten Speicher und die 5 mit der höchsten Last.
- Alte Clients ohne FehlalarmeDer Befund „alte Clients“ zählt nur fbclient-Bibliotheken. Treiber, die ohne fbclient arbeiten, werden darin nicht gezählt.
- Lang laufende Transaktionen im BerichtDer Health-Bericht markiert lang laufende Transaktionen und das Wachstum von Next − OAT. Der Befund nennt Benutzer, Programm und Adresse und liefert einen fertigen Befehl zum Trennen der Verbindung.
Local API · Prometheus · HQbird MCP
Ihre Skripte, CI und KI-Assistent
Alles, was Sie in HQ Monitor sehen, ist auch aus Ihren eigenen Tools verfügbar. Die Local API des Agenten lauscht nur auf Loopback, und jede Anfrage trägt ein Bearer-Token. Schwere Aufgaben laufen asynchron: Die Antwort liefert eine Vorgangsnummer, über die Sie den Status abrufen. Der Agent schreibt jede Anfrage, die den Server verändert, und jede 401- oder 403-Ablehnung ins Audit-Log. Leseanfragen werden nicht protokolliert.
# Local API port = 10000 + Firebird port: here Firebird uses 3055, so 13055 # server status: the same snapshot as in the health report curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/status # latest performance report and latest conflict report curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/artifacts/server/traces/perf-report/latest curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/artifacts/server/traces/deadlocks/latest # run a backup before a migration in CI and wait for the result curl -X POST -H "Authorization: Bearer $TOKEN" -d '{"job_id":"nightly","reason":"before migration"}' \ http://127.0.0.1:13055/v1/jobs/vbackup/run curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/runs/<run_id>
| Pfad | Was er liefert |
|---|---|
/v1/status | Snapshot des Serverstatus, vollständig oder nach Abschnitt, zum Beispiel Backups. |
/v1/databases | Liste der aktiven Datenbanken. |
/v1/artifacts/… | Agent-Daten: LWM (Light-weight Monitoring) pro Minute, gstat, Indexstatistiken, Metriken, der neueste Schema-Export, Trace-Berichte. |
/v1/jobs/{job}/run | Einen Job ausführen: Backup, Restore, Sweep, Datenbankprüfung, Neuberechnung der Indexstatistiken, SQL-Skript. Eine Wiederholung mit demselben Schlüssel führt den Job nicht zweimal aus. |
Prometheus-Metriken laufen nicht über die Local API. Sie haben eine eigene Adresse: standardmäßig 127.0.0.1, Port 25000 + Firebird-Port. Sie haben ein eigenes Bearer-Token. Der Export ist standardmäßig aus; Sie aktivieren ihn in den Agent-Einstellungen. Metriken: LWM, CPU und Speicher, Festplatten, OS-Limits, Temp-Dateien.
KI-Assistent in der IDE
HQbird MCP verbindet Firebird und die Agent-Daten mit Claude Code, Cursor, Codex und anderen MCP-Clients. Der Assistent sieht die Agent-Berichte und arbeitet unter menschlicher Kontrolle mit der Datenbank: Eine Person bestätigt gefährliche Aktionen.
Plan und Index
Abfrageplan und Indexempfehlung, mit erneuter Planprüfung nach dem Erstellen des Index. Eine Kompilierungsprüfung der Abfrage vor ihrer Ausführung.
Zwei Datenbanken vergleichen
Unterschiede in Schema und Daten, zum Beispiel zwischen Entwicklung und Teststand.
Planen, bestätigen, zurückrollen
Eine Migration mit Plan, einer Bestätigung und einem Rollback-Plan.
← Zurück zur HQbird 2027 Übersicht · Serverzustand im Detail →