Hive Agent 基准测试指南：在 dbx 仓库中对 Go 原生 Agent 与 JDBC Agent 做功能对等与性能对比-平芜编程栈

数据库客户端
数据库
桌面应用
CLI
后端
MCP 服务
AI 应用

【免费下载链接】dbx

20 MB lightweight cross-platform database client for 90+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具，支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90+ 数据库，提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。

项目地址：https://gitcode.com/gh_mirrors/dbx7/dbx

点击查看免费下载

本篇指南以 agents/drivers/hive-go/bench/README.md 为核心，系统讲解 dbx 项目中 Hive 数据库连接 Agent 的基准测试方法论：如何在同一主机、同一 HiveServer2 实例上，用同一套 DBX JSON-RPC 操作对比原生 Go Hive Agent 与已归档的 JDBC Hive Agent，涵盖功能对等探针（functional probe）、性能基准（performance benchmark）与 Kerberos 测试夹具（fixture）三大部分。读完本文，你将掌握夹具准备、运行命令、全部环境变量配置、输出指标解读，以及源码层面的执行细节，能够独立复现并扩展这套 Hive Agent 评测流程。

背景：为什么要做 Hive Agent 基准测试

dbx 仓库将 Hive 连接能力以 Agent 形式提供给上层客户端。历史上 Hive Agent 基于 JDBC（Java）实现，而当前正在迁移为原生 Go 实现，核心入口位于 agents/drivers/hive-go/main.go（main 包，协议版本为protocolVersion = 2）。迁移过程中必须回答两个问题：

功能是否对等：Go Agent 是否实现了与 JDBC Agent 相同的 DBX JSON-RPC 方法语义（连接、会话、查询、元数据、分页、失败 SQL 语义、干净关闭等）；
性能是否可接受：原生 Go 进程在启动、连接、结果解码、并发会话等维度上的表现，是否能支撑真实桌面端与 CLI 场景。

benchmark 目录为此提供了两套互补的 Python 驱动脚本：

functional_probe.py：功能对等探针，无并发负载，逐项验证行为一致性；
agent_compare.py：性能基准，测量延迟分布、吞吐量、内存占用与关闭行为。

两者共享同一套 Agent 进程管理、候选编排和连接参数解析逻辑，均由 agent_compare.py 中的AgentProcess、Candidate与connection_params()提供。此外，kdc_fixture 提供一个仅供隔离测试环境使用的进程内 KDC 夹具，用于 Kerberos 场景验证。

基准测试总体设计

README 明确了基准测试的对比前提与测度范围：

对比对象：同一 DBX JSON-RPC 操作集合，分别在原生 Go Hive Agent 与已归档的 JDBC Hive Agent 上执行；
运行环境：两个候选进程必须在同一主机上运行，并连接同一个 HiveServer2 实例；
测度范围（由 README 列出，脚本逐项实现）：
- 进程启动延迟与全新连接延迟；
- 产物（artifact）大小、空闲 RSS 与峰值 RSS；
- SELECT 1形状查询，以及 100 / 1,000 / 10,000 行的结果解码；
- list_databases、list_tables与完整分页读取；
- 1、8、32 个并发 DBX Agent 会话；
- 输出指标：mean、p50、p95、p99、吞吐量（ops/sec）与干净关闭行为。

顺序轮换（rotation）机制是保证公平性的关键：候选者在多轮之间轮换执行顺序，以削弱热缓存与服务端处理顺序带来的偏差；启动与连接采样每次都使用全新的 Agent 进程，避免复用进程造成污染。对应源码实现见 agent_compare.py 中的rotated(values, offset)（按轮次取模轮换候选列表）。

第一步：准备测试夹具（fixture）

在运行任何基准之前，需要先准备 Hive 侧的数据表。README 给出的默认夹具期望：

数据库：dbx_agent_bench
表：dbx_agent_bench.agent_bench
行数：恰好 10,000 行或更多
列：id与payload

建表 SQL 如下（STORED AS ORC指定 ORC 存储格式）：

CREATE DATABASE IF NOT EXISTS dbx_agent_bench; CREATE TABLE IF NOT EXISTS dbx_agent_bench.agent_bench ( id BIGINT, payload STRING ) STORED AS ORC;

建表后需填充确定性（deterministic）数据行。README 特别强调三处约束，任何一处不满足都会破坏对比有效性：

夹具不变：基准运行期间不要修改夹具数据；
环境不变：HiveServer2 配置、Agent 主机、Java 运行时（对 JDBC 候选而言）在候选之间保持一致；
对标公平：不要用本地 Go 进程去对比远程 JDBC 进程，不要使用不同的 HS2 端点，也不要在候选之间变更夹具。

从源码看，夹具表名由HIVE_BENCH_TABLE环境变量覆盖，默认agent_bench；工作负载 SQL 通过configured_workloads()构造，其中限定表名使用反引号包裹的database.table形式（见 agent_compare.py）。

第二步：运行功能对等探针（functional probe）

在性能基准之前，必须先用功能探针验证候选 Agent 的行为正确性。README 给出的命令：

GO_AGENT=/tmp/dbx-hive-bench/hive-agent-linux-amd64 \ JDBC_AGENT_JAR=/tmp/dbx-hive-bench/dbx-agent-hive.jar \ JAVA_BIN=/tmp/dbx-hive-bench/jre21/bin/java \ HIVE_HOST=127.0.0.1 \ HIVE_PORT=10000 \ HIVE_DATABASE=dbx_agent_bench \ HIVE_URL_PARAMS=auth=noSasl \ python3 agents/drivers/hive-go/bench/functional_probe.py \ > /tmp/dbx-hive-bench/functional-result.json

几点说明：

GO_AGENT指向 Go 原生 Agent 的可执行文件，JDBC_AGENT_JAR指向 JDBC Agent 的 jar 包，JAVA_BIN指定启动 jar 所用的 Java 运行时；
默认只运行 Go 候选（functional probe 的BENCH_CANDIDATES默认值为go，由脚本开头的os.environ.setdefault("BENCH_CANDIDATES", "go")设定）；
仅在需要与历史 JDBC 实现做显式对比时，才设置BENCH_CANDIDATES=go,jdbc；
输出重定向到functional-result.json，供后续人工或工具解析。

探针验证的检查项（源码probe_candidate()逐一执行）：

检查项	JSON-RPC 方法	验证内容
连接测试	`test_connection`	能否建立连接
会话打开	`open_session`	按`agentSessionId`打开会话
会话校验	`validate_session`	会话是否可用
单值查询	`execute_query`	默认`SELECT 1 AS value`的列、类型与行值
库列表	`list_databases`	返回数据库名集合
表列表	`list_tables`	返回指定 schema 下表名集合
分页读取	`execute_query_page`/`fetch_query_page`	逐页取完`LIMIT 3`的`id, payload`，统计页数与`has_more`终止
失败 SQL 语义	`execute_query`	针对不存在表的查询必须报错（`invalid_sql.failed = true`）
失败后恢复	`execute_query`	失败语句后紧接着的`SELECT 2 AS value`必须成功（验证"失败 SQL 不会被重放"）
会话关闭	`close_session`	干净关闭会话
干净退出	`shutdown`	进程收到`shutdown`后能在限定时间内退出

其中分页探针probe_paging()的逻辑值得注意：先发execute_query_page拿到首页与查询会话 id（session_id），在has_more为真时循环调用fetch_query_page直到取完，最后汇总所有页的行并统计page_count；失败语义探针probe_failure_semantics()则通过捕获异常断言 SQL 确实失败。

**对等性比较（parity）**由compare_results()完成：当存在两个及以上成功候选时，以第一个成功候选为基线，逐字段比较select_one、databases、tables、paging、after_failure，并断言每个候选的invalid_sql.failed均为true；任一差异都会记录到differences列表，最终parity.ok为false。任何候选未通过或存在差异时，探针脚本以退出码 1 结束（见main()中对SystemExit(1)的抛出逻辑）。探针输出的 JSON 还包含：

server：形如host:port的服务端标识；
connection：连接参数（密码会被脱敏为***，见sanitized_connection()）；
artifacts：每个候选产物的路径、SHA-256 摘要与字节大小（见sha256()分块计算实现）；
results：各候选逐项检查结果；
parity：对等性结论。

第三步：运行性能基准（performance benchmark）

功能探针通过后，再运行性能基准：

GO_AGENT=/tmp/dbx-hive-bench/hive-agent-linux-amd64 \ JDBC_AGENT_JAR=/tmp/dbx-hive-bench/dbx-agent-hive.jar \ HIVE_HOST=127.0.0.1 \ HIVE_PORT=10000 \ HIVE_DATABASE=dbx_agent_bench \ HIVE_URL_PARAMS=auth=noSasl \ python3 agents/drivers/hive-go/bench/agent_compare.py \ > /tmp/dbx-hive-bench/result.json

注意：与功能探针不同，性能基准的BENCH_CANDIDATES默认值为go,jdbc（源码默认值），因此上面的命令会同时压测两个候选。若只想测 Go，可显式设置BENCH_CANDIDATES=go。

基准执行流程（源码视角）

agent_compare.py的main()按以下阶段推进：

启动采样：BENCH_STARTUPS（默认 8）次，每次旋转候选顺序，对每个候选启动全新进程并立即关闭，记录启动耗时（benchmark_startup()）；
连接采样：BENCH_CONNECTS（默认 8）次，对每个候选启动进程、调用connect、关闭进程，记录连接耗时（benchmark_connect()）；
稳态工作负载：BENCH_ROUNDS（默认 3）轮，每轮内对每个候选：启动进程 →connect→ 记录空闲 RSS → 在RSSMonitor监控下依次执行各工作负载（每个工作负载先BENCH_WARMUPS（默认 2）次预热，再正式采样）→disconnect→close()并记录shutdown_exited_within_3s；
并发会话测试：对BENCH_CONCURRENCY（默认1,8,32）每个并发级别，启动一个进程，打开对应数量会话（open_session），预热后以ThreadPoolExecutor并行执行BENCH_CONCURRENCY_OPS_PER_WORKER（默认 8）次execute_query，最后关闭会话与进程（benchmark_concurrency()）。

AgentProcess类承担 JSON-RPC 传输层：向 Agent 进程的 stdin 写入单行 JSON（jsonrpc/id/method/params），从 stdout 逐行读取响应并按id分发到对应等待队列；首条{"ready":true}行作为进程就绪信号，超过BENCH_READY_TIMEOUT（默认 30 秒）未就绪即报超时；单次 RPC 超时由BENCH_RPC_TIMEOUT（默认 180 秒）控制。close()优先发送shutdown方法，等待 3 秒，失败则terminate()，再失败则kill()。

RSSMonitor以BENCH_RSS_INTERVAL（默认 0.02 秒）周期采样 RSS，追踪峰值；空闲 RSS 在连接建立后、负载开始前采样。RSS 读取优先从/proc/<pid>/status的VmRSS:行解析（Linux），否则回退到ps -o rss=。

内置工作负载

configured_workloads()定义了基准内置的 7 个工作负载，均可通过环境变量覆盖（见下节）：

工作负载	默认 SQL / 操作	默认 maxRows	默认采样次数
`select_one`	`SELECT 1 AS value`	1	40
`rows_100`	`SELECT id, payload FROM ... LIMIT 100`	100	20
`rows_1000`	`SELECT id, payload FROM ... LIMIT 1000`	1000	10
`rows_10000`	`SELECT id, payload FROM ... LIMIT 10000`	10000	3
`list_databases`	`list_databases`RPC	—	20
`list_tables`	`list_tables`RPC（schema=当前库）	—	20
`page_10000_by_500`	分页读取`LIMIT 10000`，每页 500 行	10000	3

分页负载由execute_workload()中的paged分支处理：循环execute_query_page/fetch_query_page直到has_more为假，结束时调用close_query_session释放查询会话，并断言总行数等于max_rows，否则抛出运行时错误——这保证了"完整分页读取"这一指标确实读取了全部目标行。

输出指标

每个候选的输出results条目包含：

command：实际启动命令；
artifact_bytes：产物字节数；
startup/connect：samples_ms原始样本、mean_ms、p50_ms、p95_ms、p99_ms、min_ms、max_ms（由summarize_latencies()计算，百分位取最接近的分位样本）；
process：idle_rss_kib与peak_rss_kib的 min/median/max，以及shutdown_exited_within_3s（是否全部样本都在 3 秒内退出）；
workloads：每个工作负载按summarize_rounds()汇总的延迟分布、count、elapsed_ms与ops_per_sec吞吐量；
concurrency：每个并发级别的同类汇总，并附peak_rss_kib。

顶层输出还记录host（os.uname().nodename）、server、database、table以及各采样参数（startup_iterations、connect_iterations、rounds、warmups、concurrency_levels），确保结果可追溯复现。

完整配置项（环境变量）

README 给出的全部配置项，结合源码补充默认值与取值范围如下：

环境变量	作用	默认值（源码确认）
`BENCH_CANDIDATES`	参与基准的候选，逗号分隔	性能基准`go,jdbc`；功能探针`go`
`GO_AGENT_COMMAND`/`JDBC_AGENT_COMMAND`	可选完整启动命令（shell 分词后执行）	为空时分别用`GO_AGENT`直接执行、`JAVA_BIN -jar JDBC_AGENT_JAR`
`BENCH_STARTUPS`	全新进程启动采样次数	`8`
`BENCH_CONNECTS`	全新连接采样次数	`8`
`BENCH_ROUNDS`	稳态轮次	`3`
`BENCH_WARMUPS`	每个工作负载前预热次数	`2`
`BENCH_CONCURRENCY`	并发会话数列表，逗号分隔	`1,8,32`
`BENCH_CONCURRENCY_OPS_PER_WORKER`	每个并发会话的操作数	`8`
`HIVE_HOST`/`HIVE_PORT`	HiveServer2 地址与端口	`127.0.0.1`/`10000`
`HIVE_DATABASE`/`HIVE_BENCH_TABLE`	数据库与夹具表名	`dbx_agent_bench`/`agent_bench`
`HIVE_USERNAME`/`HIVE_PASSWORD`	连接凭据	空字符串
`HIVE_URL_PARAMS`	连接 URL 参数	`auth=noSasl`
`HIVE_CONNECTION_STRING`	完整 JDBC 风格连接串	空（优先级高于分解参数）
`HIVE_SSL`	是否启用 TLS	`false`（接受`1/true/yes/on`与`0/false/no/off`）
`HIVE_CA_CERT_PATH`/`HIVE_CLIENT_CERT_PATH`/`HIVE_CLIENT_KEY_PATH`	单向/双向 TLS 证书路径	空
`HIVE_CONNECT_TIMEOUT`	连接超时（秒）	`30`
`GO_RSS_COMMAND`/`JDBC_RSS_COMMAND`	自定义 RSS 读取命令	空（默认走`/proc`或`ps`）
`BENCH_READY_TIMEOUT`	进程就绪等待上限（秒）	`30.0`
`BENCH_RPC_TIMEOUT`	单次 JSON-RPC 超时（秒）	`180.0`
`BENCH_RSS_INTERVAL`	RSS 峰值采样间隔（秒）	`0.02`
`BENCH_FETCH_SIZE`	查询默认 fetchSize	`1000`（不超过 maxRows）
`BENCH_PAGE_SIZE`/`BENCH_PAGE_COUNT`	分页负载页大小与次数	`500`/`3`
`BENCH_LIST_DATABASES_COUNT`/`BENCH_LIST_TABLES_COUNT`	元数据负载次数	`20`/`20`
`BENCH__SQL`/`BENCH__COUNT`	覆盖单个工作负载（如`BENCH_SELECT_ONE_SQL`、`BENCH_ROWS_100_COUNT`）	见上节默认表

对应函数探针也有独立的PROBE_*覆盖项：PROBE_SELECT_SQL（默认SELECT 1 AS value）、PROBE_SELECT_MAX_ROWS（10）、PROBE_FETCH_SIZE（10）、PROBE_PAGE_SQL（默认SELECT id, payload FROM dbx_agent_bench.agent_bench LIMIT 3）、PROBE_PAGE_SIZE（2）、PROBE_PAGE_MAX_ROWS（3）、PROBE_INVALID_SQL（默认查询不存在的dbx_missing_table_for_failure_semantics）、PROBE_AFTER_FAILURE_SQL（默认SELECT 2 AS value）、PROBE_SCHEMA（默认取连接库名）。

数值型环境变量（如BENCH_STARTUPS）必须为正整数，否则脚本直接抛ValueError（见env_int()/env_int_list()的校验逻辑）。

测试前置：Kerberos 夹具

如需验证 Kerberos 认证路径，README 提供了测试专用的 KDC 夹具。它启动一个仅测试用的进程内 KDC，并生成临时krb5.conf与 keytab，包含alice与hive/localhost两个主体。运行方式：

go run ./bench/kdc_fixture -dir /tmp/dbx-hive-kerberos

结合 kdc_fixture/main.go 的源码，该工具还注册了第三个主体zookeeper/localhost（用于 ZooKeeper 服务发现场景），并执行以下步骤：

以0o700权限创建目标目录；
通过krb5test.NewKDC创建 KDC 并启动（UDPPreferenceLimit = 1强制走 TCP）；
生成krb5.conf：默认 realm、关闭 DNS 查询与rdns、加密类型限定为aes256-cts-hmac-sha1-96，并写入 KDC 的 TCP 监听地址；
将 KDC keytab 序列化为fixture.keytab（权限0o600）；
向 stdout 输出 JSON 格式的fixtureInfo：realm、address、config_path、keytab_path、client_principal（alice@REALM）、service_principal（hive/localhost@REALM）、zookeeper_principal；
保持进程运行，直到收到 SIGINT/SIGTERM 才退出并关闭 KDC。

README 的告诫必须遵守：该夹具中的凭据仅供隔离的兼容性环境使用，严禁用于任何生产或共享环境，验证完成后应删除生成的目录。这组凭据可以配合 Go Agent 的 Kerberos 连接配置（keytab 登录、QOP 等参数解析逻辑见 config.go）做端到端认证验证。

源码侧印证：Agent 侧如何支撑这些测度

基准脚本所调用的 JSON-RPC 方法，正是 Go Agent 在 main.go 中实现并暴露的接口。与基准测度直接相关的事实：

就绪协议：Agent 启动即向 stdout 输出{"ready":true}，对应基准脚本的saw_ready等待逻辑；shutdown方法会等待所有在途请求完成后优雅退出并closeAllSessions()，对应close()的干净关闭测度；
分页：execute_query_page/fetch_query_page/close_query_session由server.dispatch()路由到executeQueryPage()/fetchQueryPage()/closeQuerySession()，返回结构含session_id与has_more字段（见queryPageResult定义），与脚本的分页循环严格对应；
多会话：Agent 支持按agentSessionId打开独立会话（runtimeServer.openSession），默认上限 256 个会话（maxAgentSessions），并发测度中的 1/8/32 会话规模在该上限之内；
默认分页/取数：Agent 侧默认maxRows=10000、pageSize=1000、fetchSize=50，基准脚本显式传参可覆盖这些值；
连接参数：connectParams结构（host/port/database/username/password/url_params/connection_string/ssl/证书路径/connect_timeout_secs 等）与基准脚本connection_params()的字段一一对应，其中auth=noSasl这类url_params会进入parseHiveConnectionString/applyHiveParameters的参数解析链（见 config.go）。

从依赖角度看，Go Agent 复用仓库内的 gohive（基于 beltran/gohive/v2 的本地改造）、gosasl 与 go-gssapi（见 go.mod 中的 replace 指令），GSSAPI/Kerberos 链路由此打通，这也是 bench 目录提供 KDC 夹具的原因。

复现建议与注意事项

先探针、后基准：严格按 README 顺序，先跑functional_probe.py并确认parity.ok = true，再跑agent_compare.py；探针失败时不要浪费性能基准的算力与时间；
固定运行环境：两个候选必须同机运行、连同一 HS2 实例；夹具表在基准期间只读；JDBC 候选的JAVA_BIN版本中途不要更换；
善用轮换：默认的轮换与全新进程采样已尽量消除顺序与缓存偏差，不要自行调整轮次顺序逻辑；
结果可追溯：输出 JSON 自带 host、server、采样参数与产物 SHA-256，建议连同夹具 SQL、Hive 版本、Java 版本一起归档，便于跨版本对比；
Kerberos 隔离：KDC 夹具凭据仅限隔离测试环境使用，用后即删。

通过这套流程，你可以对 dbx 的 Hive Agent 迁移获得可量化、可复现的结论：既能确认 Go 实现与 JDBC 历史实现在功能语义上完全对等，也能在启动延迟、内存占用、结果解码与并发吞吐等维度上做出有据可依的工程决策。