Cette page a été traduite automatiquement. Lisez l'original en anglais. English

Pour les développeurs d'applications

Quelle requête optimiser en premier ? Quel code a provoqué l'erreur ? Qui détient l'enregistrement dans un conflit ? L'agent collecte les réponses à partir de la trace et des statistiques sur le serveur lui-même. Le développeur les consulte dans un navigateur et ne se connecte pas au serveur.

  • 1 min fichiers de trace
  • 3 fenêtres par jour rapport de performance
  • par plan regroupement des requêtes
  • 15 min recherche de conflits
  • REST API locale pour les scripts et la CI

trace · process_traces · perf report

Rapport de performance

L'agent maintient une session de trace ouverte en permanence. Chaque minute, il compresse la sortie dans un fichier et calcule les totaux pour chaque requête. Une fois une fenêtre terminée, l'agent combine les minutes en un rapport : les requêtes les plus lentes et les plus lourdes en fetches, lectures et écritures. Chaque requête affiche son nombre d'exécutions.

  1. 1Session de tracefbtracemgr s'exécute en permanence ; un watchdog redémarre une session perdue
  2. 2Fichier de la minutesortie de trace compressée une fois par minute
  3. 3Totaux de la minutepour chaque requête : exécutions, temps, fetches, lectures, écritures, marques
  4. 4Rapport de la fenêtredans les 5 minutes suivant la fin de la fenêtre ; jusqu'à 20 requêtes dans chaque classement
  5. 5✓ HQ MonitorPage Perf Report ; lien depuis le rapport de santé
Trois fenêtres de rapport par jour : matin 07:00–12:30, jour 12:31–18:00, nuit 18:01–06:59 ; l'agent vérifie les fenêtres toutes les 5 min, un rapport apparaît donc dans les 5 min suivant la fin d'une fenêtre
Fenêtres par défaut. Matin, jour et nuit. Vous pouvez modifier les fenêtres et leur nombre dans les paramètres de l'agent. Une minute sans données est ignorée ; le rapport est tout de même construit.

Pourquoi regrouper par plan

Si un programme insère des valeurs directement dans le texte SQL, chaque valeur produit un nouveau texte. Dans un cas réel, le nombre de textes différents est passé de 204 à 83 825 par minute. Des milliers de requêtes « différentes » ne sont en fait qu'une seule requête avec un seul plan. Par défaut, l'agent regroupe donc les requêtes par une clé : les 10 premiers caractères du SQL sans commentaires, plus le plan d'exécution. Une requête sans plan conserve son texte complet. Vous modifiez le mode dans les paramètres de l'agent, champ « Perf group by » : par plan ou par texte SQL complet. Par texte, les fichiers et les rapports deviennent beaucoup plus volumineux. Changez le mode dans l'exemple ci-dessous et comparez les classements.

Requêtes en une minute

    Classement par fetches

      Table du rapportCe qu'elle montre
      Top SQL par duréeLes exécutions les plus lentes : temps et nombre d'enregistrements.
      Top SQL par fetches, lectures, écrituresTotaux pour la fenêtre : exécutions, temps, fetches, lectures, écritures, marques ; part de la fenêtre entière ; moyenne et maximum par exécution.
      Processus et adressesCharge par programme et par adresse client : connexions, temps, nombre de plans et de requêtes différents.
      Ligne de requêteSQL complet, PLAN, paramètres et statistiques par table : natural, index, update, insert, delete, backout, purge, expunge.
      Dix classements en ongletsDurée, fréquence, temps total, fetches, lectures, écritures, plans, tags, procédures et triggers. Pour chaque métrique, vous voyez la répartition des valeurs.
      Exécution échantillonQuand elle a eu lieu, quel client et depuis quelle adresse, dans quelle base de données. Si l'exécution s'est terminée par une erreur, vous la voyez ; chaque requête a un compteur d'exécutions échouées.
      Exécutions par heureCombien de fois et pendant combien de temps la requête s'est exécutée dans chaque heure de la fenêtre.
      Bases de donnéesTotaux par base de données du serveur et bases principales de chaque requête.

      Comparaison, historique et rapport à la demande

      Le rapport de fenêtre répond à la question « qu'est-ce qui était lourd aujourd'hui ». Trois nouvelles fonctions répondent aux questions « qu'est-ce qui a changé » et « que s'est-il passé dans cette heure ».

      • Comparaison de deux fenêtresDeux rapports côte à côte : quelles requêtes sont devenues plus lentes, lesquelles sont apparues et lesquelles ont disparu.
      • Historique des requêtes sur 30 joursComment le temps et le nombre d'exécutions d'une requête ont évolué d'une fenêtre à l'autre.
      • Filtre par base de donnéesUn rapport pour une seule base de données. Un lien sur la page de la base mène à la page du rapport.
      • Vers les traces de la minuteDepuis une requête du rapport vers les traces de la minute où elle s'est exécutée.
      • Rapport à la demandeLe bouton Build report… construit un rapport pour n'importe quelle plage allant jusqu'à 24 heures. Filtres : base de données, durée minimale, programme. L'agent construit un seul rapport de ce type à la fois et conserve les 20 derniers.
      • Recherche et téléchargementUn champ de recherche pour le texte de la requête. Vous pouvez télécharger le fichier source du rapport.
      • Un rapport incomplet est signaléSi certains fichiers de trace ne sont pas encore arrivés, le rapport est marqué comme incomplet. Le rapport ne conserve que le haut de chaque classement, la page indique donc « absent du classement », et non « ne s'est pas exécuté ».
      • Procédures et triggersCes classements se remplissent lorsque les paramètres de trace activent la journalisation de la fin des procédures et des triggers. Par défaut, cette journalisation est désactivée.
      • Depuis le rapport de santéLe bouton Perf report ouvre la bonne fenêtre. Les lignes de requête sont marquées, et la première est déjà développée.
      • Requête et tableL'onglet Queries des statistiques gstat relie les requêtes aux tables et index qu'elles lisent.
      • Une minute sur le graphique de la baseUn clic sur une minute affiche les requêtes lourdes issues de la trace et toutes les connexions de cette minute.
      • Copier le SQLAvec ou sans paramètres, directement dans votre propre outil. En mode démo, les boutons sont masqués.

      trace · Errors

      Erreurs SQL avec les données du client

      Un utilisateur dit « le programme a donné une erreur ». La page Errors affiche chaque erreur Firebird issue de la trace : heure, connexion, base de données, texte et client. Avec le nom du programme, l'adresse et la fonction Firebird, vous trouvez facilement l'erreur dans votre code.

      Bloc d'erreur dans la 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"

      Ligne sur la page 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

      • Mêmes erreurs — une seule ligneUne ligne par minute, base de données et type d'erreur, avec un compteur ×N. Une infobulle affiche la première et la dernière heure et le nombre de connexions.
      • FiltresInclude et Exclude par texte, base de données, programme, adresse et fonction. Un clic sur un programme ou une adresse ne conserve que ses erreurs.
      • Export CSVToutes les lignes avec les filtres appliqués, en UTF-8 avec BOM : Excel ouvre le fichier directement en colonnes.
      • S'il n'y a pas de programmeDe nombreux pilotes JDBC et .NET n'envoient pas le nom du programme. La ligne client est alors plus courte.

      trace_monitor_conflicts · find_deadlocks

      Conflits et deadlocks

      L'erreur « update conflicts with concurrent update » n'apprend pas grand-chose à elle seule. Il faut savoir ce que l'autre transaction a fait. Pour cela, l'agent maintient une seconde session de trace configurée pour les modifications de données et les erreurs. Toutes les 15 minutes, il recherche les conflits et construit un rapport.

      La transaction 1001 a modifié un enregistrement ; 1002 tente de modifier le même enregistrement et reçoit une erreur ; le rapport retrouve les requêtes de 1001 par son numéro

      Comment lire le rapport

      À gauche se trouve la liste des minutes comportant des conflits. Chaque groupe correspond à une transaction qui a provoqué des conflits : le numéro de transaction et l'heure de l'erreur.

      La colonne de gauche affiche les erreurs : connexion, programme, codes Firebird et la requête qui a échoué. La colonne de droite affiche les requêtes réussies de la transaction concurrente : heure, connexion, numéro de transaction, programme. Chaque requête dispose de son SQL, de ses paramètres, de ses statistiques et de ses tables.

      L'adresse de la page conserve la date et la minute. Vous pouvez envoyer le lien à un collègue.

      Page des conflits. Les minutes à gauche, le groupe de transactions à droite : codes de processus et d'erreur.
      ParamètreValeur par défautSignification
      Recherche de conflitstoutes les 15 minutesLa dernière minute est ignorée : la trace est encore en cours d'écriture.
      Profondeur de recherche3 heuresCombien d'historique avant le conflit parcourir lors de la recherche des requêtes de l'autre transaction.
      Conservation de la trace brute6 heuresLes fichiers bruts de la session de conflit ne s'accumulent pas sur le serveur. Les rapports sont conservés et envoyés à HQ Monitor.

      gstat · indexes · metadata

      Comment la base de données évolue

      Une fois par jour, l'agent collecte les statistiques complètes de gstat. HQ Monitor analyse le fichier : taille des tables et des index, versions d'enregistrements, BLOBs, profondeur des index. L'onglet « Analyse et recommandations » indique ce qui ne va pas et ce qu'il faut faire.

      Analyse et recommandations. Problème, nombre de cas, objets liés, recommandation et action.
      Tendances. Comparaison des derniers instantanés : ce qui a augmenté, et quand un objet augmentera de 25 %.
      OngletCe qu'il apporte au développeur
      TablesTaille des données, des index et des BLOBs, nombre d'enregistrements, versions d'enregistrements et nombre maximal de versions d'un enregistrement.
      IndexProfondeur, pages, valeurs uniques, doublons. Une profondeur de 4 correspond à une ligne jaune, 5 et plus à une ligne rouge.
      Requêtes et liensQuelles requêtes lisent une table ou un index. Données issues des rapports de performance proches dans le temps de l'instantané.
      TendancesComparaison de 5, 10, 20 ou 30 instantanés ; seuil de variation de 10 %, 2 % ou 0,5 %. La prévision « +25 % » à partir de trois instantanés ou plus.
      ExportJSON avec les mesures et Excel avec l'analyse complète.
      • Statistiques des indexDésactivées par défaut ; vous les activez dans les paramètres de l'agent. Ensuite, toutes les 6 heures, l'agent compte les index inactifs et les index à faible sélectivité. Un index non reconstruit après une restauration est un point sérieux dans le rapport de santé.
      • Prévision de croissanceLa pastille « +25 % » dans la table de la base de données indique la table ou l'index qui croît le plus vite et ouvre la prévision.
      • Export du schémaL'agent exporte les métadonnées de la base de données avec isql -x et conserve les archives par date.
      • Suivi des métadonnéesDésactivé par défaut ; vous l'activez dans les paramètres de l'agent. Toutes les 6 heures, l'agent compare le nouvel export du schéma avec le précédent et enregistre le moment où le schéma a changé.

      LWM · MON$ · clients

      Connexions : transactions longues et versions des clients

      Une transaction oubliée ralentit toute la base de données : les versions d'enregistrements s'accumulent et le ramassage des ordures s'arrête.

      Chaque minute, l'agent enregistre les compteurs de transactions et les données de connexion. Sur le graphique de la base de données, Next − OAT augmente si une transaction reste ouverte longtemps. La table des connexions de cette minute, triée par Act.Tran, indique le programme, l'adresse et le processus qui détient la transaction. Pour en savoir plus sur les compteurs, consultez la page de santé du serveur.

      Une fois par jour, l'agent relève quelles bibliothèques clientes se connectent à la base de données et combien de connexions chacune possède. La ligne « Non détecté. Ancienne version ? » signifie généralement une ancienne bibliothèque cliente.

      Versions des clients. La chaîne de version du client et le nombre de connexions. Les connexions propres à l'agent apparaissent sur une ligne distincte.
      • Métriques MON$Une fois par heure : mémoire par programme, les 5 connexions consommant le plus de mémoire et les 5 les plus chargées.
      • Clients anciens sans fausses alertesLe constat « clients anciens » ne compte que les bibliothèques fbclient. Les pilotes qui fonctionnent sans fbclient n'y sont pas comptés.
      • Transactions longues dans le rapportLe rapport de santé signale les transactions longues et la croissance de Next − OAT. Le constat nomme l'utilisateur, le programme et l'adresse et fournit une commande prête à l'emploi pour déconnecter.

      Local API · Prometheus · HQbird MCP

      Vos scripts, la CI et l'assistant IA

      Tout ce que vous voyez dans HQ Monitor est accessible depuis vos propres outils. La Local API de l'agent n'écoute que sur l'interface de bouclage, et chaque requête porte un jeton Bearer. Les tâches lourdes s'exécutent de manière asynchrone : la réponse fournit un numéro d'opération, et vous lisez l'état par ce numéro. L'agent consigne dans le journal d'audit chaque requête qui modifie le serveur, ainsi que chaque refus 401 ou 403. Les requêtes de lecture ne sont pas consignées.

      # 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>
      CheminCe qu'il fournit
      /v1/statusInstantané de l'état du serveur, complet ou par section, par exemple les sauvegardes.
      /v1/databasesListe des bases de données actives.
      /v1/artifacts/…Données de l'agent : LWM (Light-weight Monitoring) par minute, gstat, statistiques des index, métriques, dernier export du schéma, rapports de trace.
      /v1/jobs/{job}/runExécuter une tâche : sauvegarde, restauration, sweep, vérification de la base de données, recalcul des statistiques des index, script SQL. Une répétition avec la même clé n'exécute pas la tâche deux fois.

      Les métriques Prometheus ne passent pas par la Local API. Elles ont leur propre adresse : par défaut 127.0.0.1, port 25000 + port Firebird. Elles ont leur propre jeton Bearer. L'export est désactivé par défaut ; vous l'activez dans les paramètres de l'agent. Métriques : LWM, CPU et mémoire, disques, limites de l'OS, fichiers temporaires.

      Assistant IA dans l'IDE

      HQbird MCP connecte Firebird et les données de l'agent à Claude Code, Cursor, Codex et d'autres clients MCP. L'assistant voit les rapports de l'agent et travaille avec la base de données sous contrôle humain : une personne confirme les actions dangereuses.

      Requête

      Plan et index

      Plan de requête et conseils d'index, avec une revérification du plan après la création de l'index. Une vérification de compilation de la requête avant son exécution.

      Schéma

      Comparer deux bases de données

      Différences de schéma et de données, par exemple entre le développement et le banc de test.

      Migration

      Planifier, confirmer, annuler

      Une migration avec un plan, une confirmation et un plan d'annulation.

      Plus : HQbird MCP

      ← Retour à la présentation de HQbird 2027 · État du serveur en détail →