HQbird per gli sviluppatori
Per gli sviluppatori di applicazioni
Quale query ottimizzare per prima? Quale codice ha generato l'errore? Chi detiene il record in un conflitto? L'agente raccoglie le risposte dal trace e dalle statistiche direttamente sul server. Lo sviluppatore le vede in un browser e non effettua l'accesso al server.
- 1 min file di trace
- 3 finestre al giorno report sulle prestazioni
- per piano raggruppamento delle query
- 15 min ricerca dei conflitti
- REST API locale per script e CI
trace · process_traces · perf report
Report sulle prestazioni
L'agente mantiene sempre aperta una sessione di trace. Ogni minuto comprime l'output in un file e calcola i totali per ciascuna query. Al termine di una finestra, l'agente combina i minuti in un report: le query più lente e quelle più pesanti per fetches, letture e scritture. Per ogni query viene mostrato il numero di esecuzioni.
- 1Sessione di tracefbtracemgr è sempre in esecuzione; un watchdog riavvia una sessione persa
- 2File al minutooutput del trace compresso una volta al minuto
- 3Totali al minutoper ciascuna query: esecuzioni, tempo, fetches, letture, scritture, marks
- 4Report della finestraentro 5 minuti dalla fine della finestra; fino a 20 query in ciascuna classifica
- 5✓ HQ Monitorpagina Perf Report; link dal report sullo stato di salute
Perché raggruppare per piano
Se un programma inserisce i valori direttamente nel testo SQL, ogni valore genera un nuovo testo. In un caso reale, il numero di testi diversi è cresciuto da 204 a 83.825 al minuto. Migliaia di query “diverse” sono in realtà un'unica query con un unico piano. Pertanto, per impostazione predefinita, l'agente raggruppa le query per una chiave: i primi 10 caratteri dell'SQL senza commenti, più il piano di esecuzione. Una query senza piano mantiene il suo testo completo. Puoi modificare la modalità nelle impostazioni dell'agente, campo “Perf group by”: per piano o per testo SQL completo. Con il testo, i file e i report diventano molto più grandi. Cambia la modalità nell'esempio qui sotto e confronta le classifiche.
Query in un minuto
Classifica per fetches
| Tabella del report | Cosa mostra |
|---|---|
| Top SQL per durata | Le esecuzioni più lente: tempo e numero di record. |
| Top SQL per fetches, letture, scritture | Totali della finestra: esecuzioni, tempo, fetches, letture, scritture, marks; quota sull'intera finestra; media e massimo per esecuzione. |
| Processi e indirizzi | Carico per programma e per indirizzo client: connessioni, tempo, numero di piani e query diversi. |
| Riga della query | SQL completo, PLAN, parametri e statistiche per tabella: natural, index, update, insert, delete, backout, purge, expunge. |
| Dieci classifiche in schede | Durata, frequenza, tempo totale, fetches, letture, scritture, piani, tag, procedure e trigger. Per ciascuna metrica vedi la distribuzione dei valori. |
| Esecuzione di esempio | Quando è stata eseguita, quale client e da quale indirizzo, in quale database. Se l'esecuzione è terminata con un errore, lo vedi; ogni query ha un contatore delle esecuzioni fallite. |
| Esecuzioni per ora | Quante volte e per quanto tempo la query è stata eseguita in ciascuna ora della finestra. |
| Database | Totali per database del server e database principali di ciascuna query. |
Confronto, cronologia e report su richiesta
Il report della finestra risponde alla domanda “cosa è stato pesante oggi”. Tre nuove funzioni rispondono alle domande “cosa è cambiato” e “cosa è successo in questa ora”.
- Confronto tra due finestreDue report affiancati: quali query sono diventate più lente, quali sono comparse e quali sono scomparse.
- Cronologia delle query per 30 giorniCome sono cambiati il tempo e il numero di esecuzioni di una query da una finestra all'altra.
- Filtro per databaseUn report solo per un database. Un link nella pagina del database porta alla pagina del report.
- Ai trace del minutoDa una query nel report ai trace del minuto in cui è stata eseguita.
- Report su richiestaIl pulsante Build report… crea un report per qualsiasi intervallo fino a 24 ore. Filtri: database, durata minima, programma. L'agente crea un report alla volta e conserva gli ultimi 20.
- Ricerca e downloadUn campo di ricerca per il testo della query. Puoi scaricare il file sorgente del report.
- Il report incompleto è contrassegnatoSe alcuni file di trace non sono ancora arrivati, il report è contrassegnato come incompleto. Il report conserva solo la parte iniziale di ciascuna classifica, quindi la pagina indica “non in classifica”, non “non eseguita”.
- Procedure e triggerQueste classifiche si popolano quando le impostazioni del trace attivano la registrazione del termine di procedure e trigger. Per impostazione predefinita, questa registrazione è disattivata.
- Dal report sullo stato di saluteIl pulsante Perf report apre la finestra corretta. Le righe delle query sono contrassegnate e la prima è già espansa.
- Query e tabellaLa scheda Queries delle statistiche gstat collega le query alle tabelle e agli indici che leggono.
- Un minuto sul grafico del databaseUn clic su un minuto mostra le query pesanti dal trace e tutte le connessioni di quel minuto.
- Copia SQLCon o senza parametri, direttamente nel tuo strumento. In modalità demo i pulsanti sono nascosti.
trace · Errors
Errori SQL con i dati del client
Un utente dice “il programma ha dato un errore”. La pagina Errors mostra ogni errore Firebird dal trace: ora, connessione, database, testo e client. Con il nome del programma, l'indirizzo e la funzione Firebird, puoi trovare facilmente l'errore nel tuo codice.
Blocco di errore nel trace
Riga nella pagina Errors
- Stessi errori — una sola rigaUna riga per minuto, database e tipo di errore, con un conteggio ×N. Un suggerimento mostra la prima e l'ultima occorrenza e il numero di connessioni.
- FiltriIncludi ed Escludi per testo, database, programma, indirizzo e funzione. Un clic su un programma o un indirizzo mantiene solo i suoi errori.
- Esporta CSVTutte le righe con i filtri applicati, in UTF-8 con BOM: Excel apre subito il file in colonne.
- Se manca il programmaMolti driver JDBC e .NET non inviano il nome del programma. In tal caso la riga del client è più corta.
trace_monitor_conflicts · find_deadlocks
Conflitti e deadlock
L'errore “update conflicts with concurrent update” da solo dice poco. Devi sapere cosa ha fatto l'altra transazione. Per questo l'agente mantiene una seconda sessione di trace configurata per le modifiche ai dati e gli errori. Ogni 15 minuti cerca i conflitti e crea un report.
Come leggere il report
A sinistra c'è l'elenco dei minuti con conflitti. Ogni gruppo è una transazione che ha causato conflitti: il numero della transazione e l'ora dell'errore.
La colonna di sinistra mostra gli errori: connessione, programma, codici Firebird e la query fallita. La colonna di destra mostra le query riuscite della transazione concorrente: ora, connessione, numero di transazione, programma. Ogni query ha il suo SQL, i parametri, le statistiche e le tabelle.
L'indirizzo della pagina conserva la data e il minuto. Puoi inviare il link a un collega.
| Parametro | Predefinito | Significato |
|---|---|---|
| Ricerca dei conflitti | ogni 15 minuti | L'ultimo minuto viene saltato: il trace lo sta ancora scrivendo. |
| Profondità di ricerca | 3 ore | Quanta cronologia precedente al conflitto esaminare durante la ricerca delle query dell'altra transazione. |
| Conservazione del trace grezzo | 6 ore | I file grezzi della sessione di conflitto non si accumulano sul server. I report vengono conservati e inviati a HQ Monitor. |
gstat · indici · metadati
Come cambia il database
Una volta al giorno l'agente acquisisce le statistiche complete di gstat. HQ Monitor analizza il file: dimensione di tabelle e indici, versioni dei record, BLOB, profondità degli indici. La scheda "Analisi e raccomandazioni" indica cosa non va e cosa fare.
| Scheda | Cosa offre allo sviluppatore |
|---|---|
| Tabelle | Dimensione di dati, indici e BLOB, numero di record, versioni dei record e versioni massime di un singolo record. |
| Indici | Profondità, pagine, valori univoci, duplicati. Profondità 4 è una riga gialla, 5 e oltre è rossa. |
| Query e collegamenti | Quali query leggono una tabella o un indice. Dati dai report di prestazioni vicini nel tempo all'istantanea. |
| Tendenze | Confronto di 5, 10, 20 o 30 istantanee; soglia di variazione 10%, 2% o 0,5%. La previsione "+25%" da tre o più istantanee. |
| Esportazione | JSON con le misurazioni ed Excel con l'analisi completa. |
- Statistiche degli indiciDisattivate per impostazione predefinita; le attivi nelle impostazioni dell'agente. Poi ogni 6 ore l'agente conta gli indici inattivi e gli indici con scarsa selettività. Un indice non ricostruito dopo un restore è un problema serio nel report di salute.
- Previsione di crescitaIl chip "+25%" nella tabella del database mostra la tabella o l'indice in più rapida crescita e apre la previsione.
- Esportazione dello schemaL'agente esporta i metadati del database con
isql -xe conserva gli archivi per data. - Tracciamento dei metadatiDisattivato per impostazione predefinita; lo attivi nelle impostazioni dell'agente. Ogni 6 ore l'agente confronta la nuova esportazione dello schema con la precedente e registra quando lo schema è cambiato.
LWM · MON$ · client
Connessioni: transazioni lunghe e versioni dei client
Una transazione dimenticata rallenta l'intero database: le versioni dei record si accumulano e la garbage collection si ferma.
Ogni minuto l'agente registra i contatori delle transazioni e i dati delle connessioni. Nel grafico del database, Next − OAT cresce se una transazione resta aperta a lungo. La tabella delle connessioni per quel minuto, ordinata per Act.Tran, mostra il programma, l'indirizzo e il processo che mantiene la transazione. Maggiori informazioni sui contatori sono nella pagina di salute del server.
Una volta al giorno l'agente rileva quali librerie client si connettono al database e quante connessioni ha ciascuna. La riga "Non rilevato. Versione obsoleta?" di solito indica una libreria client obsoleta.
- Metriche MON$Una volta all'ora: memoria per programma, le 5 connessioni con più memoria e le 5 con il carico più alto.
- Client obsoleti senza falsi allarmiIl rilevamento "client obsoleti" conta solo le librerie fbclient. I driver che funzionano senza fbclient non vengono conteggiati.
- Transazioni lunghe nel reportIl report di salute segnala le transazioni lunghe e la crescita di Next − OAT. Il rilevamento indica l'utente, il programma e l'indirizzo e fornisce un comando pronto per la disconnessione.
Local API · Prometheus · HQbird MCP
I tuoi script, la CI e l'assistente AI
Tutto ciò che vedi in HQ Monitor è disponibile dai tuoi strumenti. La Local API dell'agente è in ascolto solo sul loopback e ogni richiesta porta un token Bearer. I lavori pesanti vengono eseguiti in modo asincrono: la risposta fornisce un numero di operazione e tramite esso leggi lo stato. L'agente registra nel log di audit ogni richiesta che modifica il server e ogni rifiuto 401 o 403. Le richieste di lettura non finiscono nel log.
# 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>
| Percorso | Cosa fornisce |
|---|---|
/v1/status | Istantanea dello stato del server, completa o per sezione, ad esempio i backup. |
/v1/databases | Elenco dei database attivi. |
/v1/artifacts/… | Dati dell'agente: LWM (Light-weight Monitoring) al minuto, gstat, statistiche degli indici, metriche, l'ultima esportazione dello schema, report di trace. |
/v1/jobs/{job}/run | Esegue un job: backup, restore, sweep, controllo del database, ricalcolo delle statistiche degli indici, script SQL. Una ripetizione con la stessa chiave non esegue il job due volte. |
Le metriche Prometheus non passano attraverso la Local API. Hanno un indirizzo proprio: per impostazione predefinita 127.0.0.1, porta 25000 + porta Firebird. Hanno un proprio token Bearer. L'esportazione è disattivata per impostazione predefinita; la attivi nelle impostazioni dell'agente. Metriche: LWM, CPU e memoria, dischi, limiti del sistema operativo, file temporanei.
Assistente AI nell'IDE
HQbird MCP collega Firebird e i dati dell'agente a Claude Code, Cursor, Codex e altri client MCP. L'assistente vede i report dell'agente e opera sul database sotto controllo umano: una persona conferma le azioni pericolose.
Piano e indice
Piano della query e consigli sugli indici, con ricontrollo del piano dopo la creazione dell'indice. Un controllo di compilazione della query prima dell'esecuzione.
Confronta due database
Differenze di schema e dati, ad esempio tra sviluppo e ambiente di test.
Pianifica, conferma, annulla
Una migrazione con piano, una conferma e un piano di rollback.
← Torna alla panoramica di HQbird 2027 · Salute del server in dettaglio →