面向开发者的 HQbird
面向应用开发者
应该先优化哪个查询?哪段代码引发了错误?谁在冲突中持有记录?代理在服务器本身上从跟踪和统计中收集答案。开发者可以在浏览器中查看这些答案,无需登录服务器。
- 1 分钟跟踪文件
- 每天 3 个窗口性能报告
- 按计划查询分组
- 15 分钟冲突搜索
- REST用于脚本和 CI 的本地 API
trace · process_traces · perf report
性能报告
代理始终保持一个跟踪会话开启。每分钟它将输出压缩到一个文件中,并为每个查询计算总计。窗口结束后,代理将各分钟的数据合并成一份报告:最慢的查询以及按获取、读取和写入计算的最重查询。每个查询都会显示其执行次数。
- 1跟踪会话fbtracemgr 持续运行;看门狗会重启丢失的会话
- 2分钟文件每分钟压缩一次跟踪输出
- 3分钟总计针对每个查询:执行次数、时间、获取、读取、写入、标记
- 4窗口报告窗口结束后 5 分钟内;每个排名最多 20 个查询
- 5✓ HQ Monitor性能报告页面;从健康报告链接进入
为什么按计划分组
如果程序将值直接放入 SQL 文本中,每个值都会产生新的文本。在一个真实案例中,不同文本的数量每分钟从 204 增长到 83,825。成千上万个“不同”的查询实际上是一个具有一个计划的查询。因此,默认情况下,代理按一个键对查询进行分组:不含注释的 SQL 的前 10 个字符,加上执行计划。没有计划的查询保留其完整文本。你可以在代理设置中的“Perf group by”字段更改模式:按计划或按完整 SQL 文本。按文本分组时,文件和报告会变得大得多。在下面的示例中切换模式并比较排名。
一分钟内的查询
按获取排名
| 报告表格 | 显示内容 |
|---|---|
| 按持续时间排序的 Top SQL | 最慢的执行:时间和记录数。 |
| 按获取、读取、写入排序的 Top SQL | 窗口总计:执行次数、时间、获取、读取、写入、标记;占整个窗口的份额;每次执行的平均值和最大值。 |
| 进程和地址 | 按程序和客户端地址的负载:连接数、时间、不同计划和查询的数量。 |
| 查询行 | 完整 SQL、PLAN、参数和按表统计:natural、index、update、insert、delete、backout、purge、expunge。 |
| 选项卡中的十个排名 | 持续时间、频率、总时间、获取、读取、写入、计划、标签、存储过程和触发器。对于每个指标,你可以看到值的分布。 |
| 示例执行 | 何时运行、哪个客户端以及从哪个地址、在哪个数据库中。如果执行以错误结束,你可以看到该错误;每个查询都有一个失败执行计数器。 |
| 按小时统计的执行 | 查询在窗口的每个小时内运行了多少次以及运行了多长时间。 |
| 数据库 | 按服务器数据库以及每个查询的主要数据库统计的总计。 |
比较、历史和按需报告
窗口报告回答了“今天什么比较重”的问题。三个新功能回答了“什么发生了变化”和“这个小时内发生了什么”的问题。
- 比较两个窗口并排显示两份报告:哪些查询变慢了、哪些出现了、哪些消失了。
- 30 天查询历史一个查询的时间和执行次数如何从一个窗口到另一个窗口变化。
- 按数据库筛选仅针对一个数据库的报告。数据库页面上的链接会跳转到报告页面。
- 跳转到分钟跟踪从报告中的查询跳转到其运行时的分钟跟踪。
- 按需报告Build report… 按钮可为最长 24 小时的任意范围生成报告。筛选条件:数据库、最短持续时间、程序。代理一次生成一份此类报告,并保留最近 20 份。
- 搜索和下载用于查询文本的搜索字段。你可以下载报告的源文件。
- 不完整报告会被标记如果某些跟踪文件尚未到达,报告会被标记为不完整。报告只保留每个排名的顶部,因此页面显示的是“不在排名中”,而不是“未运行”。
- 存储过程和触发器当跟踪设置开启存储过程和触发器完成日志记录时,这些排名才会填充。默认情况下,此日志记录是关闭的。
- 从健康报告进入Perf report 按钮会打开正确的窗口。查询行会被标记,第一行已经展开。
- 查询与表gstat 统计信息的“查询”选项卡将查询与其读取的表和索引关联起来。
- 数据库图表上的一分钟点击某一分钟,即可显示该分钟内来自 trace 的重查询以及所有连接。
- 复制 SQL带参数或不带参数,直接复制到你自己的工具中。在演示模式下,这些按钮会被隐藏。
trace · 错误
带客户端数据的 SQL 错误
用户说“程序报错了”。“错误”页面会显示来自 trace 的每个 Firebird 错误:时间、连接、数据库、文本和客户端。借助程序名称、地址和 Firebird 函数,你可以轻松在代码中找到该错误。
trace 中的错误块
“错误”页面上的行
- 相同错误 — 一行按分钟、数据库和错误类型各一行,并带有 ×N 计数。提示信息会显示首次和最后出现的时间以及连接数。
- 筛选按文本、数据库、程序、地址和函数进行包含与排除。点击某个程序或地址,只保留其错误。
- 导出 CSV应用筛选后的所有行,采用带 BOM 的 UTF-8 编码:Excel 打开文件即可按列显示。
- 如果没有程序许多 JDBC 和 .NET 驱动程序不发送程序名称。此时客户端行会更短。
trace_monitor_conflicts · find_deadlocks
冲突与死锁
“更新与并发更新冲突”这一错误本身说明不了什么。你需要知道另一个事务做了什么。为此,代理会维护第二个 trace 会话,专门用于数据变更和错误。它每 15 分钟搜索一次冲突并生成报告。
如何阅读报告
左侧是发生冲突的分钟列表。每组是一个引发冲突的事务:事务编号和错误时间。
左栏显示错误:连接、程序、Firebird 代码以及失败的查询。右栏显示竞争事务的成功查询:时间、连接、事务编号、程序。每个查询都有其 SQL、参数、统计信息和表。
页面地址会保留日期和分钟。你可以把链接发给同事。
| 参数 | 默认值 | 含义 |
|---|---|---|
| 冲突搜索 | 每 15 分钟 | 跳过最后一分钟:trace 仍在写入该分钟。 |
| 搜索深度 | 3 小时 | 在搜索另一个事务的查询时,向前追溯冲突之前多久的历史。 |
| 原始 trace 保留时间 | 6 小时 | 冲突会话的原始文件不会在服务器上堆积。报告会被保留并发送到 HQ Monitor。 |
gstat · 索引 · 元数据
数据库如何变化
代理每天执行一次完整的 gstat 统计。HQ Monitor 会解析该文件:表和索引的大小、记录版本、BLOB、索引深度。“分析与建议”选项卡会说明存在什么问题以及该怎么做。
| 选项卡 | 它为开发者提供什么 |
|---|---|
| 表 | 数据、索引和 BLOB 的大小,记录数、记录版本以及单条记录的最大版本数。 |
| 索引 | 深度、页数、唯一值、重复值。深度为 4 时显示为黄色行,5 及以上显示为红色。 |
| 查询与链接 | 哪些查询读取了某个表或索引。数据来自与快照时间接近的性能报告。 |
| 趋势 | 比较 5、10、20 或 30 个快照;变化阈值为 10%、2% 或 0.5%。基于三个或更多快照的“+25%”预测。 |
| 导出 | 包含测量数据的 JSON 和包含完整分析的 Excel。 |
- 索引统计默认关闭;需在代理设置中开启。开启后,代理每 6 小时统计一次非活动索引和选择性较差的索引。恢复后未重建的索引在健康报告中属于严重问题。
- 增长预测数据库表中的“+25%”标签显示增长最快的表或索引,并打开预测。
- 架构导出代理使用
isql -x导出数据库元数据,并按日期保留归档。 - 元数据跟踪默认关闭;需在代理设置中开启。开启后,代理每 6 小时将新的架构导出与上一次比较,并记录架构变更的时间。
LWM · MON$ · 客户端
连接:长事务和客户端版本
一个被遗忘的事务会拖慢整个数据库:记录版本不断堆积,垃圾回收停止。
代理每分钟写入事务计数器和连接数据。在数据库图表中,如果某个事务长时间保持打开,Next − OAT 会增长。该分钟的连接表按 Act.Tran 排序,显示持有该事务的程序、地址和进程。有关计数器的更多信息,请参阅服务器健康页面。
代理每天读取一次哪些客户端库连接到数据库,以及每个客户端库有多少连接。“未检测到。旧版本?”这一行通常表示客户端库版本过旧。
- MON$ 指标每小时一次:按程序划分的内存、内存占用最多的 5 个连接以及负载最高的 5 个连接。
- 旧客户端且无误报“旧客户端”发现仅统计 fbclient 库。不使用 fbclient 的驱动程序不计入其中。
- 报告中的长事务健康报告会标记长事务以及 Next − OAT 的增长。该发现会列出用户、程序和地址,并给出可直接执行的断开连接命令。
本地 API · Prometheus · HQbird MCP
你的脚本、CI 和 AI 助手
你在 HQ Monitor 中看到的一切都可以通过你自己的工具获取。代理的本地 API 仅监听回环地址,每个请求都携带 Bearer 令牌。繁重任务以异步方式运行:响应会返回一个操作编号,你通过该编号读取状态。代理会将每个更改服务器的请求以及每次 401 或 403 拒绝写入审计日志。读取请求不会写入日志。
# 本地 API 端口 = 10000 + Firebird 端口:此处 Firebird 使用 3055,因此为 13055 # 服务器状态:与健康报告中相同的快照 curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/status # 最新的性能报告和最新的冲突报告 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 # 在 CI 中于迁移前运行备份并等待结果 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>
| 路径 | 提供的内容 |
|---|---|
/v1/status | 服务器状态快照,可获取全部或按部分获取,例如备份。 |
/v1/databases | 活动数据库列表。 |
/v1/artifacts/… | 代理数据:每分钟的 LWM(轻量级监控)、gstat、索引统计、指标、最新的架构导出、跟踪报告。 |
/v1/jobs/{job}/run | 运行任务:备份、恢复、sweep、数据库检查、索引统计重算、SQL 脚本。使用相同键重复请求不会重复运行该任务。 |
Prometheus 指标不经过本地 API。它们有自己的地址:默认为 127.0.0.1,端口为 25000 + Firebird 端口。它们有自己的 Bearer 令牌。导出默认关闭;需在代理设置中开启。指标包括:LWM、CPU 和内存、磁盘、操作系统限制、临时文件。
IDE 中的 AI 助手
HQbird MCP 将 Firebird 和代理数据连接到 Claude Code、Cursor、Codex 及其他 MCP 客户端。助手可以查看代理报告并在人工控制下操作数据库:危险操作由人工确认。
计划与索引
查询计划和索引建议,并在创建索引后重新检查计划。查询运行前进行编译检查。
比较两个数据库
架构和数据差异,例如开发环境与测试台之间的差异。
计划、确认、回滚
带计划的迁移,一次确认和回滚方案。