Questa pagina è stata tradotta automaticamente. Leggi l'originale in inglese. English

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.

  1. 1Sessione di tracefbtracemgr è sempre in esecuzione; un watchdog riavvia una sessione persa
  2. 2File al minutooutput del trace compresso una volta al minuto
  3. 3Totali al minutoper ciascuna query: esecuzioni, tempo, fetches, letture, scritture, marks
  4. 4Report della finestraentro 5 minuti dalla fine della finestra; fino a 20 query in ciascuna classifica
  5. 5✓ HQ Monitorpagina Perf Report; link dal report sullo stato di salute
Tre finestre di report al giorno: mattina 07:00–12:30, giorno 12:31–18:00, notte 18:01–06:59; l'agente controlla le finestre ogni 5 min, quindi un report compare entro 5 min dalla fine di una finestra
Finestre predefinite. Mattina, giorno e notte. Puoi modificare le finestre e il loro numero nelle impostazioni dell'agente. Un minuto senza dati viene saltato; il report viene comunque creato.

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 reportCosa mostra
      Top SQL per durataLe esecuzioni più lente: tempo e numero di record.
      Top SQL per fetches, letture, scrittureTotali della finestra: esecuzioni, tempo, fetches, letture, scritture, marks; quota sull'intera finestra; media e massimo per esecuzione.
      Processi e indirizziCarico per programma e per indirizzo client: connessioni, tempo, numero di piani e query diversi.
      Riga della querySQL completo, PLAN, parametri e statistiche per tabella: natural, index, update, insert, delete, backout, purge, expunge.
      Dieci classifiche in schedeDurata, frequenza, tempo totale, fetches, letture, scritture, piani, tag, procedure e trigger. Per ciascuna metrica vedi la distribuzione dei valori.
      Esecuzione di esempioQuando è 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 oraQuante volte e per quanto tempo la query è stata eseguita in ciascuna ora della finestra.
      DatabaseTotali 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

      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"

      Riga nella pagina 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

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

      La transazione 1001 ha modificato un record; la 1002 tenta di modificare lo stesso record e riceve un errore; il report individua le query della 1001 tramite il suo numero

      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.

      Pagina dei conflitti. Minuti a sinistra, il gruppo di transazioni a destra: processo e codici di errore.
      ParametroPredefinitoSignificato
      Ricerca dei conflittiogni 15 minutiL'ultimo minuto viene saltato: il trace lo sta ancora scrivendo.
      Profondità di ricerca3 oreQuanta cronologia precedente al conflitto esaminare durante la ricerca delle query dell'altra transazione.
      Conservazione del trace grezzo6 oreI 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.

      Analisi e raccomandazioni. Problema, numero di casi, oggetti collegati, raccomandazione e azione.
      Tendenze. Confronto delle ultime istantanee: cosa è cresciuto e quando un oggetto crescerà del 25%.
      SchedaCosa offre allo sviluppatore
      TabelleDimensione di dati, indici e BLOB, numero di record, versioni dei record e versioni massime di un singolo record.
      IndiciProfondità, pagine, valori univoci, duplicati. Profondità 4 è una riga gialla, 5 e oltre è rossa.
      Query e collegamentiQuali query leggono una tabella o un indice. Dati dai report di prestazioni vicini nel tempo all'istantanea.
      TendenzeConfronto di 5, 10, 20 o 30 istantanee; soglia di variazione 10%, 2% o 0,5%. La previsione "+25%" da tre o più istantanee.
      EsportazioneJSON 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 -x e 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.

      Versioni dei client. La stringa di versione del client e il numero di connessioni. Le connessioni dell'agente stesso compaiono come riga separata.
      • 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>
      PercorsoCosa fornisce
      /v1/statusIstantanea dello stato del server, completa o per sezione, ad esempio i backup.
      /v1/databasesElenco 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}/runEsegue 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.

      Query

      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.

      Schema

      Confronta due database

      Differenze di schema e dati, ad esempio tra sviluppo e ambiente di test.

      Migrazione

      Pianifica, conferma, annulla

      Una migrazione con piano, una conferma e un piano di rollback.

      Altro: HQbird MCP

      ← Torna alla panoramica di HQbird 2027 · Salute del server in dettaglio →