For application developers

Which query to optimize first? Which code got the error? Who holds the record in a conflict? The agent collects the answers from trace and statistics on the server itself. The developer sees them in a browser and does not log in to the server.

  • 1 min trace files
  • 3 windows a day performance report
  • by plan query grouping
  • 15 min conflict search
  • REST Local API for scripts and CI

trace · process_traces · perf report

Performance report

The agent keeps a trace session open all the time. Every minute it compresses the output into a file and computes totals for each query. After a window ends, the agent combines the minutes into a report: the slowest queries and the heaviest ones by fetches, reads and writes. Each query shows its number of executions.

  1. 1Trace sessionfbtracemgr runs all the time; a watchdog restarts a lost session
  2. 2Minute filecompressed trace output once a minute
  3. 3Minute totalsfor each query: executions, time, fetches, reads, writes, marks
  4. 4Window reportwithin 5 minutes after the window ends; up to 20 queries in each ranking
  5. 5✓ HQ MonitorPerf Report page; link from the health report
Three report windows a day: morning 07:00–12:30, day 12:31–18:00, night 18:01–06:59; the agent checks windows every 5 min, so a report appears within 5 min after a window ends
Default windows. Morning, day and night. You can change the windows and their number in the agent settings. A minute with no data is skipped; the report is still built.

Why group by plan

If a program puts values directly into the SQL text, each value gives a new text. In one real case, the number of different texts grew from 204 to 83,825 per minute. Thousands of “different” queries are in fact one query with one plan. So by default the agent groups queries by a key: the first 10 characters of the SQL without comments, plus the execution plan. A query without a plan keeps its full text. You change the mode in the agent settings, field “Perf group by”: by plan or by full SQL text. By text, files and reports become much larger. Switch the mode in the example below and compare the rankings.

Queries in one minute

    Ranking by fetches

      Report tableWhat it shows
      Top SQL by durationThe slowest executions: time and number of records.
      Top SQL by fetches, reads, writesTotals for the window: executions, time, fetches, reads, writes, marks; share of the whole window; average and maximum per execution.
      Processes and AddressesLoad by program and by client address: connections, time, number of different plans and queries.
      Query rowFull SQL, PLAN, parameters and per-table statistics: natural, index, update, insert, delete, backout, purge, expunge.
      Ten rankings in tabsDuration, frequency, total time, fetches, reads, writes, plans, tags, procedures and triggers. For each metric, you see the spread of values.
      Sample executionWhen it ran, which client and from which address, in which database. If the execution ended with an error, you see it; each query has a counter of failed executions.
      Executions by hourHow many times and how long the query ran in each hour of the window.
      DatabasesTotals by database of the server and the main databases of each query.

      Comparison, history and report on request

      The window report answers the question “what was heavy today”. Three new functions answer the questions “what changed” and “what happened in this hour”.

      • Comparing two windowsTwo reports side by side: which queries became slower, which appeared and which went away.
      • Query history for 30 daysHow the time and the number of executions of one query changed from window to window.
      • Filter by databaseA report for one database only. A link on the database page leads to the report page.
      • To the traces of the minuteFrom a query in the report to the traces of the minute when it ran.
      • Report on requestThe Build report… button builds a report for any range up to 24 hours. Filters: database, minimum duration, program. The agent builds one such report at a time and keeps the last 20.
      • Search and downloadA search field for the query text. You can download the source file of the report.
      • Incomplete report is markedIf some trace files have not arrived yet, the report is marked as incomplete. The report keeps only the top of each ranking, so the page says “not in the ranking”, not “did not run”.
      • Procedures and triggersThese rankings fill when the trace settings turn on the logging of procedure and trigger finish. By default, this logging is off.
      • From the health reportThe Perf report button opens the right window. The query rows are marked, and the first one is already expanded.
      • Query and tableThe Queries tab of the gstat statistics links queries to the tables and indexes they read.
      • A minute on the database chartA click on a minute shows the heavy queries from trace and all connections of that minute.
      • Copy SQLWith or without parameters, straight into your own tool. In demo mode the buttons are hidden.

      trace · Errors

      SQL errors with client data

      A user says “the program gave an error”. The Errors page shows each Firebird error from trace: time, connection, database, text and client. With the program name, address and Firebird function, you can easily find the error in your code.

      Error block in 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"

      Row on the Errors page

      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

      • Same errors — one rowOne row per minute, database and error type, with a ×N count. A hint shows the first and last time and the number of connections.
      • FiltersInclude and Exclude by text, database, program, address and function. A click on a program or address keeps only its errors.
      • Export CSVAll rows with the filters applied, in UTF-8 with BOM: Excel opens the file in columns right away.
      • If there is no programMany JDBC and .NET drivers do not send the program name. Then the client row is shorter.

      trace_monitor_conflicts · find_deadlocks

      Conflicts and deadlocks

      The error “update conflicts with concurrent update” tells little by itself. You need to know what the other transaction did. For this, the agent keeps a second trace session set up for data changes and errors. Every 15 minutes it searches for conflicts and builds a report.

      Transaction 1001 changed a record; 1002 tries to change the same record and gets an error; the report finds the queries of 1001 by its number

      How to read the report

      On the left is the list of minutes with conflicts. Each group is one transaction that caused conflicts: the transaction number and the error time.

      The left column shows the errors: connection, program, Firebird codes and the query that failed. The right column shows the successful queries of the competing transaction: time, connection, transaction number, program. Each query has its SQL, parameters, statistics and tables.

      The page address keeps the date and minute. You can send the link to a colleague.

      Conflicts page. Minutes on the left, the transaction group on the right: process and error codes.
      ParameterDefaultMeaning
      Conflict searchevery 15 minutesThe last minute is skipped: trace is still writing it.
      Search depth3 hoursHow much history before the conflict to look through when searching for the queries of the other transaction.
      Raw trace retention6 hoursRaw files of the conflict session do not pile up on the server. Reports are kept and sent to HQ Monitor.

      gstat · indexes · metadata

      How the database changes

      Once a day the agent takes full gstat statistics. HQ Monitor parses the file: size of tables and indexes, record versions, BLOBs, index depth. The “Analysis and recommendations” tab tells what is wrong and what to do.

      Analysis and recommendations. Problem, number of cases, linked objects, recommendation and action.
      Trends. Comparison of the latest snapshots: what grew, and when an object will grow by 25%.
      TabWhat it gives the developer
      TablesSize of data, indexes and BLOBs, number of records, record versions and the maximum versions of one record.
      IndexesDepth, pages, unique values, duplicates. Depth 4 is a yellow row, 5 and more is red.
      Queries and LinksWhich queries read a table or index. Data from performance reports close in time to the snapshot.
      TrendsComparison of 5, 10, 20 or 30 snapshots; change threshold 10%, 2% or 0.5%. The “+25%” forecast from three or more snapshots.
      ExportJSON with the measurements and Excel with the full analysis.
      • Index statisticsOff by default; you turn it on in the agent settings. Then every 6 hours the agent counts inactive indexes and indexes with poor selectivity. An index not built after a restore is serious in the health report.
      • Growth forecastThe “+25%” chip in the database table shows the fastest-growing table or index and opens the forecast.
      • Schema exportThe agent exports the database metadata with isql -x and keeps archives by date.
      • Metadata trackingOff by default; you turn it on in the agent settings. Every 6 hours the agent compares the new schema export with the previous one and records when the schema changed.

      LWM · MON$ · clients

      Connections: long transactions and client versions

      One forgotten transaction slows down the whole database: record versions pile up, and garbage collection stops.

      Every minute the agent writes the transaction counters and connection data. On the database chart, Next − OAT grows if a transaction stays open for a long time. The connection table for that minute, sorted by Act.Tran, shows the program, address and process that holds the transaction. More about the counters is on the server health page.

      Once a day the agent reads which client libraries connect to the database and how many connections each one has. The row “Not detected. Old version?” usually means an old client library.

      Client versions. The version string from the client and the number of connections. The agent's own connections show as a separate row.
      • MON$ metricsOnce an hour: memory by program, the 5 connections with the most memory and the 5 with the highest load.
      • Old clients without false alarmsThe “old clients” finding counts only fbclient libraries. Drivers that work without fbclient are not counted in it.
      • Long transactions in the reportThe health report marks long transactions and growth of Next − OAT. The finding names the user, the program and the address and gives a ready command to disconnect.

      Local API · Prometheus · HQbird MCP

      Your scripts, CI and AI assistant

      Everything you see in HQ Monitor is available from your own tools. The agent's Local API listens only on loopback, and each request carries a Bearer token. Heavy jobs run asynchronously: the response gives an operation number, and you read the status by it. The agent writes each request that changes the server, and each 401 or 403 refusal, to the audit log. Read requests do not go to the 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>
      PathWhat it gives
      /v1/statusSnapshot of the server status, whole or by section, for example backups.
      /v1/databasesList of active databases.
      /v1/artifacts/…Agent data: LWM (Light-weight Monitoring) per minute, gstat, index statistics, metrics, the latest schema export, trace reports.
      /v1/jobs/{job}/runRun a job: backup, restore, sweep, database check, index statistics recalculation, SQL script. A repeat with the same key does not run the job twice.

      Prometheus metrics do not go through the Local API. They have their own address: by default 127.0.0.1, port 25000 + Firebird port. They have their own Bearer token. The export is off by default; you turn it on in the agent settings. Metrics: LWM, CPU and memory, disks, OS limits, temp files.

      AI assistant in the IDE

      HQbird MCP connects Firebird and the agent data to Claude Code, Cursor, Codex and other MCP clients. The assistant sees the agent reports and works with the database under human control: a person confirms dangerous actions.

      Query

      Plan and index

      Query plan and index advice, with a plan re-check after the index is created. A compile check of the query before it runs.

      Schema

      Compare two databases

      Schema and data differences, for example between development and the test stand.

      Migration

      Plan, confirm, roll back

      A migration with a plan, one confirmation and a rollback plan.

      More: HQbird MCP

      ← Back to the HQbird 2027 overview · Server health in detail →