Diese Seite wurde maschinell übersetzt. Lesen Sie das englische Original. English

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.

  1. 1Trace-Sitzungfbtracemgr läuft ständig; ein Watchdog startet eine verlorene Sitzung neu
  2. 2Minutendateikomprimierte Trace-Ausgabe einmal pro Minute
  3. 3Minutensummenfür jede Abfrage: Ausführungen, Zeit, Fetches, Lese- und Schreibvorgänge, Marks
  4. 4Fensterberichtinnerhalb von 5 Minuten nach Ende des Fensters; bis zu 20 Abfragen in jeder Rangliste
  5. 5✓ HQ MonitorSeite Perf Report; Link aus dem Health-Bericht
Drei Berichtsfenster pro Tag: Morgen 07:00–12:30, Tag 12:31–18:00, Nacht 18:01–06:59; der Agent prüft die Fenster alle 5 Min., daher erscheint ein Bericht innerhalb von 5 Min. nach Ende eines Fensters
Standardfenster. Morgen, Tag und Nacht. Sie können die Fenster und ihre Anzahl in den Agent-Einstellungen ändern. Eine Minute ohne Daten wird übersprungen; der Bericht wird trotzdem erstellt.

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

      BerichtstabelleWas sie zeigt
      Top SQL nach DauerDie langsamsten Ausführungen: Zeit und Anzahl der Datensätze.
      Top SQL nach Fetches, Lese- und SchreibvorgängenSummen 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 AdressenLast nach Programm und nach Client-Adresse: Verbindungen, Zeit, Anzahl verschiedener Pläne und Abfragen.
      AbfragezeileVollständiges SQL, PLAN, Parameter und Statistiken pro Tabelle: natural, index, update, insert, delete, backout, purge, expunge.
      Zehn Ranglisten in TabsDauer, 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ührungWann 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 StundeWie oft und wie lange die Abfrage in jeder Stunde des Fensters lief.
      DatenbankenSummen 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

      2026-10-17T12:00:05.0000 (4521:0x7f..) ERROR AT JStatement::execute /db/shop.fdb (ATT_370201, SHOP_APP:NONE, UTF8, TCPv4:10.0.0.5/50123) C:\Shop\shop.exe:7712 335544665 : violation of PRIMARY or UNIQUE KEY constraint "UK_ITEM"

      Zeile auf der Seite Errors

      tstmpattIDdb · errTxt 12:00370201/db/shop.fdb ×3 335544665 : violation of PRIMARY or UNIQUE KEY constraint "UK_ITEM" C:\Shop\shop.exe:7712 · 10.0.0.5/50123 · JStatement::execute

      • 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.

      Transaktion 1001 hat einen Datensatz geändert; 1002 versucht, denselben Datensatz zu ändern, und erhält einen Fehler; der Bericht findet die Abfragen von 1001 anhand ihrer Nummer

      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.

      Konfliktseite. Minuten links, die Transaktionsgruppe rechts: Prozess- und Fehlercodes.
      ParameterStandardBedeutung
      Konfliktsuchealle 15 MinutenDie letzte Minute wird übersprungen: Der Trace schreibt sie noch.
      Suchtiefe3 StundenWie viel Verlauf vor dem Konflikt durchsucht wird, um die Abfragen der anderen Transaktion zu finden.
      Aufbewahrung des Roh-Trace6 StundenRohdateien 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.

      Analyse und Empfehlungen. Problem, Anzahl der Fälle, verknüpfte Objekte, Empfehlung und Aktion.
      Trends. Vergleich der neuesten Snapshots: was gewachsen ist und wann ein Objekt um 25 % wächst.
      TabWas er dem Entwickler bietet
      TabellenGröße von Daten, Indizes und BLOBs, Anzahl der Datensätze, Datensatzversionen und die maximale Anzahl Versionen eines Datensatzes.
      IndizesTiefe, Seiten, eindeutige Werte, Duplikate. Tiefe 4 ist eine gelbe Zeile, 5 und mehr ist rot.
      Abfragen und VerknüpfungenWelche Abfragen eine Tabelle oder einen Index lesen. Daten aus Performance-Berichten zeitlich nahe am Snapshot.
      TrendsVergleich von 5, 10, 20 oder 30 Snapshots; Änderungsschwelle 10 %, 2 % oder 0,5 %. Die „+25 %“-Prognose ab drei oder mehr Snapshots.
      ExportJSON 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 -x und 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.

      Client-Versionen. Der Versionsstring des Clients und die Anzahl der Verbindungen. Die eigenen Verbindungen des Agenten erscheinen als separate Zeile.
      • 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>
      PfadWas er liefert
      /v1/statusSnapshot des Serverstatus, vollständig oder nach Abschnitt, zum Beispiel Backups.
      /v1/databasesListe 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}/runEinen 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.

      Abfrage

      Plan und Index

      Abfrageplan und Indexempfehlung, mit erneuter Planprüfung nach dem Erstellen des Index. Eine Kompilierungsprüfung der Abfrage vor ihrer Ausführung.

      Schema

      Zwei Datenbanken vergleichen

      Unterschiede in Schema und Daten, zum Beispiel zwischen Entwicklung und Teststand.

      Migration

      Planen, bestätigen, zurückrollen

      Eine Migration mit Plan, einer Bestätigung und einem Rollback-Plan.

      Mehr: HQbird MCP

      ← Zurück zur HQbird 2027 Übersicht · Serverzustand im Detail →