HQbird voor ontwikkelaars
Voor applicatieontwikkelaars
Welke query moet je eerst optimaliseren? Welke code gaf de fout? Wie houdt het record in een conflict? De agent verzamelt de antwoorden uit trace en statistieken op de server zelf. De ontwikkelaar ziet ze in een browser en logt niet in op de server.
- 1 min tracebestanden
- 3 vensters per dag prestatierapport
- op plan querygroepering
- 15 min conflictzoekopdracht
- REST Local API voor scripts en CI
trace · process_traces · perf report
Prestatierapport
De agent houdt permanent een tracesessie open. Elke minuut comprimeert hij de uitvoer naar een bestand en berekent hij totalen per query. Nadat een venster eindigt, combineert de agent de minuten tot een rapport: de traagste queries en de zwaarste op basis van fetches, reads en writes. Elke query toont het aantal uitvoeringen.
- 1Tracesessiefbtracemgr draait permanent; een watchdog herstart een verloren sessie
- 2Minuutbestandgecomprimeerde trace-uitvoer eens per minuut
- 3Minuuttotalenper query: uitvoeringen, tijd, fetches, reads, writes, marks
- 4Vensterrapportbinnen 5 minuten nadat het venster eindigt; tot 20 queries in elke ranglijst
- 5✓ HQ MonitorPerf Report-pagina; link vanuit het health-rapport
Waarom groeperen op plan
Als een programma waarden rechtstreeks in de SQL-tekst zet, geeft elke waarde een nieuwe tekst. In één reëel geval groeide het aantal verschillende teksten van 204 naar 83.825 per minuut. Duizenden “verschillende” queries zijn in feite één query met één plan. Daarom groepeert de agent queries standaard op een sleutel: de eerste 10 tekens van de SQL zonder commentaar, plus het uitvoeringsplan. Een query zonder plan behoudt zijn volledige tekst. Je wijzigt de modus in de agentinstellingen, veld “Perf group by”: op plan of op volledige SQL-tekst. Op tekst worden bestanden en rapporten veel groter. Schakel de modus in het onderstaande voorbeeld en vergelijk de ranglijsten.
Queries in één minuut
Ranglijst op fetches
| Rapporttabel | Wat deze toont |
|---|---|
| Top SQL op duur | De traagste uitvoeringen: tijd en aantal records. |
| Top SQL op fetches, reads, writes | Totalen voor het venster: uitvoeringen, tijd, fetches, reads, writes, marks; aandeel van het hele venster; gemiddelde en maximum per uitvoering. |
| Processen en adressen | Belasting per programma en per clientadres: verbindingen, tijd, aantal verschillende plannen en queries. |
| Queryrij | Volledige SQL, PLAN, parameters en statistieken per tabel: natural, index, update, insert, delete, backout, purge, expunge. |
| Tien ranglijsten in tabs | Duur, frequentie, totale tijd, fetches, reads, writes, plannen, tags, procedures en triggers. Voor elke metriek zie je de spreiding van waarden. |
| Voorbeelduitvoering | Wanneer deze liep, welke client en vanaf welk adres, in welke database. Als de uitvoering met een fout eindigde, zie je die; elke query heeft een teller van mislukte uitvoeringen. |
| Uitvoeringen per uur | Hoe vaak en hoe lang de query in elk uur van het venster liep. |
| Databases | Totalen per database van de server en de belangrijkste databases van elke query. |
Vergelijking, geschiedenis en rapport op aanvraag
Het vensterrapport beantwoordt de vraag “wat was vandaag zwaar”. Drie nieuwe functies beantwoorden de vragen “wat is er veranderd” en “wat gebeurde er in dit uur”.
- Twee vensters vergelijkenTwee rapporten naast elkaar: welke queries werden trager, welke verschenen en welke verdwenen.
- Querygeschiedenis voor 30 dagenHoe de tijd en het aantal uitvoeringen van één query van venster tot venster veranderden.
- Filter op databaseEen rapport voor slechts één database. Een link op de databasepagina leidt naar de rapportpagina.
- Naar de traces van de minuutVan een query in het rapport naar de traces van de minuut waarin deze liep.
- Rapport op aanvraagDe knop Build report… bouwt een rapport voor elk bereik tot 24 uur. Filters: database, minimale duur, programma. De agent bouwt één zo'n rapport tegelijk en bewaart de laatste 20.
- Zoeken en downloadenEen zoekveld voor de querytekst. Je kunt het bronbestand van het rapport downloaden.
- Onvolledig rapport is gemarkeerdAls sommige tracebestanden nog niet zijn aangekomen, wordt het rapport als onvolledig gemarkeerd. Het rapport bewaart alleen de top van elke ranglijst, dus de pagina zegt “niet in de ranglijst”, niet “niet uitgevoerd”.
- Procedures en triggersDeze ranglijsten worden gevuld wanneer de trace-instellingen de logging van procedure- en triggerafronding inschakelen. Standaard staat deze logging uit.
- Vanuit het health-rapportDe knop Perf report opent het juiste venster. De queryrijen zijn gemarkeerd en de eerste is al uitgevouwen.
- Query en tabelHet tabblad Queries van de gstat-statistieken koppelt queries aan de tabellen en indexen die ze lezen.
- Een minuut op de databasegrafiekEen klik op een minuut toont de zware queries uit trace en alle verbindingen van die minuut.
- SQL kopiërenMet of zonder parameters, rechtstreeks naar je eigen tool. In demomodus zijn de knoppen verborgen.
trace · Errors
SQL-fouten met clientgegevens
Een gebruiker zegt “het programma gaf een fout”. De pagina Errors toont elke Firebird-fout uit trace: tijd, verbinding, database, tekst en client. Met de programmanaam, het adres en de Firebird-functie vind je de fout gemakkelijk terug in je code.
Foutblok in trace
Rij op de pagina Errors
- Dezelfde fouten — één rijEén rij per minuut, database en fouttype, met een ×N-telling. Een hint toont de eerste en laatste keer en het aantal verbindingen.
- FiltersInclude en Exclude op tekst, database, programma, adres en functie. Een klik op een programma of adres behoudt alleen de fouten daarvan.
- CSV exporterenAlle rijen met de toegepaste filters, in UTF-8 met BOM: Excel opent het bestand meteen in kolommen.
- Als er geen programma isVeel JDBC- en .NET-drivers sturen de programmanaam niet mee. Dan is de clientrij korter.
trace_monitor_conflicts · find_deadlocks
Conflicten en deadlocks
De fout “update conflicts with concurrent update” zegt op zichzelf weinig. Je moet weten wat de andere transactie deed. Daarvoor houdt de agent een tweede tracesessie bij die is ingesteld voor gegevenswijzigingen en fouten. Elke 15 minuten zoekt hij naar conflicten en bouwt hij een rapport.
Het rapport lezen
Aan de linkerkant staat de lijst met minuten met conflicten. Elke groep is één transactie die conflicten veroorzaakte: het transactienummer en het tijdstip van de fout.
De linkerkolom toont de fouten: verbinding, programma, Firebird-codes en de query die mislukte. De rechterkolom toont de geslaagde queries van de concurrerende transactie: tijd, verbinding, transactienummer, programma. Elke query heeft zijn SQL, parameters, statistieken en tabellen.
Het adres van de pagina bevat de datum en de minuut. Je kunt de link naar een collega sturen.
| Parameter | Standaard | Betekenis |
|---|---|---|
| Conflictzoekopdracht | elke 15 minuten | De laatste minuut wordt overgeslagen: de trace schrijft er nog naar. |
| Zoekdiepte | 3 uur | Hoeveel geschiedenis vóór het conflict wordt doorzocht bij het zoeken naar de queries van de andere transactie. |
| Bewaring van ruwe trace | 6 uur | Ruwe bestanden van de conflictsessie hopen zich niet op op de server. Rapporten worden bewaard en naar HQ Monitor verzonden. |
gstat · indexen · metadata
Hoe de database verandert
Eén keer per dag neemt de agent volledige gstat-statistieken af. HQ Monitor parseert het bestand: grootte van tabellen en indexen, recordversies, BLOBs, indexdiepte. Het tabblad "Analyse en aanbevelingen" vertelt wat er mis is en wat je moet doen.
| Tabblad | Wat het de ontwikkelaar oplevert |
|---|---|
| Tabellen | Grootte van data, indexen en BLOBs, aantal records, recordversies en de maximale versies van één record. |
| Indexen | Diepte, pagina's, unieke waarden, duplicaten. Diepte 4 is een gele rij, 5 en meer is rood. |
| Queries en links | Welke queries een tabel of index lezen. Gegevens uit prestatierapporten die qua tijd dicht bij het snapshot liggen. |
| Trends | Vergelijking van 5, 10, 20 of 30 snapshots; wijzigingsdrempel 10%, 2% of 0,5%. De "+25%"-prognose vanaf drie of meer snapshots. |
| Export | JSON met de metingen en Excel met de volledige analyse. |
- IndexstatistiekenStandaard uit; je schakelt het in bij de agentinstellingen. Daarna telt de agent elke 6 uur inactieve indexen en indexen met slechte selectiviteit. Een index die na een restore niet is opgebouwd, is ernstig in het gezondheidsrapport.
- GroeiprognoseDe "+25%"-chip in de databasetabel toont de snelst groeiende tabel of index en opent de prognose.
- Schema-exportDe agent exporteert de databasemetadata met
isql -xen bewaart archieven per datum. - Metadata-trackingStandaard uit; je schakelt het in bij de agentinstellingen. Elke 6 uur vergelijkt de agent de nieuwe schema-export met de vorige en registreert wanneer het schema is gewijzigd.
LWM · MON$ · clients
Verbindingen: langdurige transacties en clientversies
Eén vergeten transactie vertraagt de hele database: recordversies hopen zich op en garbage collection stopt.
Elke minuut schrijft de agent de transactietellers en verbindingsgegevens. Op de databasegrafiek groeit Next − OAT als een transactie lang open blijft. De verbindingstabel voor die minuut, gesorteerd op Act.Tran, toont het programma, het adres en het proces dat de transactie vasthoudt. Meer over de tellers staat op de pagina over servergezondheid.
Eén keer per dag leest de agent welke clientbibliotheken verbinding maken met de database en hoeveel verbindingen elk heeft. De rij "Niet gedetecteerd. Oude versie?" betekent meestal een oude clientbibliotheek.
- MON$-metriekenEén keer per uur: geheugen per programma, de 5 verbindingen met het meeste geheugen en de 5 met de hoogste belasting.
- Oude clients zonder valse meldingenDe bevinding "oude clients" telt alleen fbclient-bibliotheken. Drivers die zonder fbclient werken, worden er niet in meegeteld.
- Langdurige transacties in het rapportHet gezondheidsrapport markeert langdurige transacties en de groei van Next − OAT. De bevinding noemt de gebruiker, het programma en het adres en geeft een kant-en-klaar commando om de verbinding te verbreken.
Local API · Prometheus · HQbird MCP
Je scripts, CI en AI-assistent
Alles wat je in HQ Monitor ziet, is beschikbaar vanuit je eigen tools. De Local API van de agent luistert alleen op loopback, en elk verzoek bevat een Bearer-token. Zware taken worden asynchroon uitgevoerd: het antwoord geeft een bewerkingsnummer, en daarmee lees je de status. De agent schrijft elk verzoek dat de server wijzigt, en elke 401- of 403-weigering, naar het auditlog. Leesverzoeken komen niet in het log.
# Local API-poort = 10000 + Firebird-poort: hier gebruikt Firebird 3055, dus 13055 # serverstatus: hetzelfde snapshot als in het gezondheidsrapport curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/status # laatste prestatierapport en laatste conflictenrapport 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 # voer een back-up uit vóór een migratie in CI en wacht op het resultaat 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>
| Pad | Wat het oplevert |
|---|---|
/v1/status | Snapshot van de serverstatus, volledig of per sectie, bijvoorbeeld back-ups. |
/v1/databases | Lijst van actieve databases. |
/v1/artifacts/… | Agentgegevens: LWM (Light-weight Monitoring) per minuut, gstat, indexstatistieken, metrieken, de laatste schema-export, trace-rapporten. |
/v1/jobs/{job}/run | Een taak uitvoeren: back-up, restore, sweep, databasecontrole, herberekening van indexstatistieken, SQL-script. Een herhaling met dezelfde sleutel voert de taak niet twee keer uit. |
Prometheus-metrieken gaan niet via de Local API. Ze hebben hun eigen adres: standaard 127.0.0.1, poort 25000 + Firebird-poort. Ze hebben hun eigen Bearer-token. De export staat standaard uit; je schakelt het in bij de agentinstellingen. Metrieken: LWM, CPU en geheugen, schijven, OS-limieten, tijdelijke bestanden.
AI-assistent in de IDE
HQbird MCP verbindt Firebird en de agentgegevens met Claude Code, Cursor, Codex en andere MCP-clients. De assistent ziet de agentrapporten en werkt met de database onder menselijke controle: een persoon bevestigt gevaarlijke acties.
Plan en index
Queryplan en indexadvies, met een hercontrole van het plan nadat de index is aangemaakt. Een compileercontrole van de query voordat deze wordt uitgevoerd.
Twee databases vergelijken
Verschillen in schema en data, bijvoorbeeld tussen ontwikkeling en de testomgeving.
Plannen, bevestigen, terugdraaien
Een migratie met een plan, één bevestiging en een rollback-plan.
← Terug naar het HQbird 2027-overzicht · Serverstatus in detail →