OpenSearch PR 性能基准测试指南基于 GitHub Actions 与 benchmark-config 的自动化 Benchmark 工作流【免费下载链接】OpenSearch Open source distributed and RESTful search engine.项目地址: https://gitcode.com/gh_mirrors/op/OpenSearch本指南面向 OpenSearch 仓库的贡献者与维护者系统讲解如何通过benchmark-pull-requestGitHub Actions 工作流在 Pull Request 上自动运行性能基准测试涵盖触发方式、审批流程、构建与发布链路、基准配置结构以及结果对比方法。读完本文你将掌握在 PR 评论中一键触发基准测试、为特定改动新增基准测试配置、以及将测试结果与官方基线进行对比的完整实战方案。为什么需要在 PR 上运行性能基准测试性能是 OpenSearch 这类分布式搜索引擎的核心质量属性。代码改动尤其是搜索、索引、聚合等路径上的改动可能在正确性测试全部通过的情况下引入明显的性能回退。为此OpenSearch 仓库通过benchmark-pull-request工作流定义见 .github/workflows/benchmark-pull-request.yml实现了在 PR 评论中发出指定指令即可自动对当前 PR 的代码改动构建发行版并运行标准化基准测试的能力从而以一致、可复现的方式持续维护仓库的性能标准。除了这套端到端的 PR 基准测试工作流仓库还维护了一套基于 JMH 的微基准测试套件见 benchmarks/README.md用于在性能关键组件上定位回归两者互为补充微基准测试关注热点方法级性能PR 基准测试则面向真实负载workload级别的整体性能。工作流触发机制该工作流基于issue_comment事件触发即当有人在 PR本质上是一个 issue上新建评论时触发on: issue_comment: types: [created]同时工作流通过if条件做了三重过滤对应 benchmark-pull-request.yml仓库必须是opensearch-project/OpenSearch防止 fork 仓库误触发事件对象必须是 PRgithub.event.issue.pull_request存在而非普通 issue评论正文必须包含关键字run-benchmark-test。也就是说只有在 PR 上发表的、包含特定 JSON 关键字的评论才会真正启动基准测试流水线。这也是保证基准资源不被随意消耗的第一道防线。工作流关键步骤拆解结合 .github/workflows/benchmark-pull-request.yml 的源码实现整个工作流共 8 个 job 步骤可归纳为以下核心环节1. 校验评论格式与配置工作流首先读取当前 OpenSearch 版本并设置环境变量。版本取自 buildSrc/version.properties例如OPENSEARCH_VERSION$(awk -F /^opensearch[[:space:]]*/ {gsub(/[[:space:]]/, , $2); print $2} buildSrc/version.properties) major_version$(echo $OPENSEARCH_VERSION | cut -d. -f1) echo OPENSEARCH_MAJOR_VERSION$major_version $GITHUB_ENV随后使用actions/github-script完成三件事尝试将评论正文JSON.parse为 JSON 对象解析失败则判定为无效检查 JSON 是否包含run-benchmark-test属性并取出配置 ID读取 .github/benchmark-configs.json校验该配置 ID 是否存在且其supported_major_versions中是否包含当前 OpenSearch 主版本号例如 3。校验通过后配置中的cluster-benchmark-configs会以环境变量的形式注入后续步骤如果配置还带有baseline_cluster_config字段也会一并导出。2. 无效评论提示与失败若评论格式非法、配置 ID 不存在或主版本不支持工作流会调用 GitHub API 在 PR 上回帖提示Invalid comment format or config id并引导参考本指南PERFORMANCE_BENCHMARKS.md随后显式exit 1使工作流失败。这一设计让用户能立刻知道问题所在而不是无响应地等待。3. 手动审批如需要审批环节的目的是防止非维护者滥用基准资源工作流先调用 GitHub API 获取仓库中具有maintain权限的协作者列表作为审批人集合若评论者不在该集合中则通过trstringer/manual-approvalaction 创建一条审批 issue标题形如 Request to approve/deny benchmark run for PR #xxx工作流暂停直到审批人在该 issue 上以评论方式批准或拒绝审批完成后该 issue 自动关闭。对于维护者maintainer本人发起的请求则会跳过审批直接执行。仓库中可以通过 .github/CODEOWNERS 了解各模块的代码所有者构成。4. 从 PR 代码构建并组装 OpenSearch审批通过后工作流先检出PR 的 head 仓库与 head commit而不是默认分支然后配置 Java 21Temurin 发行版再执行构建任务tasks(:distribution:archives:linux-tar:assemble) if [[ $INSTALL_STREAMING_PLUGINS true ]]; then tasks(:plugins:arrow-base:bundlePlugin :plugins:arrow-flight-rpc:bundlePlugin) fi ./gradlew ${tasks[]} -Dbuild.snapshotfalse默认构建产物是x64 Linux tar 版 min 发行版。当配置要求安装流式插件INSTALL_STREAMING_PLUGINS: true时还会把arrow-base与arrow-flight-rpc插件对应 plugins/arrow-base、plugins/arrow-flight-rpcbundle 进发行版并通过opensearch-plugin install --batch打入 tar 包。5. 上传到 S3构建完成后工作流通过aws-actions/configure-aws-credentials以 OIDC 方式代入UPLOAD_ARCHIVE_ARTIFACT_ROLE角色将 tar 包上传到ARCHIVE_ARTIFACT_BUCKET_NAME指定的 S3 桶aws s3 cp distribution/archives/linux-tar/build/distributions/opensearch-min-$OPENSEARCH_VERSION-linux-x64.tar.gz \ s3://${{ secrets.ARCHIVE_ARTIFACT_BUCKET_NAME }}/PR-$PR_NUMBER/该 S3 桶前端由 CloudFront 承载仅允许下载用于后续 Jenkins 基准作业拉取构建产物桶上的生命周期策略会在30 天后自动删除上传的归档。6. 触发 Jenkins 基准作业接下来工作流检出opensearch-build仓库用于编排 OpenSearch 构建与测试的基础设施仓库并调用其 benchmark 脚本通过 webhook token 触发 Jenkins 上的基准测试作业bash opensearch-build/scripts/benchmark/benchmark-pull-request.sh \ -t ${{ secrets.JENKINS_PR_BENCHMARK_GENERIC_WEBHOOK_TOKEN }} \ -u ${{ secrets.JENKINS_GITHUB_USER}} \ -p ${{ secrets.JENKINS_GITHUB_USER_TOKEN}}基准测试本身基于 OpenSearch Benchmark 工具执行Jenkins 作业会依据前面注入的cluster-benchmark-configs环境变量拉起指定规格的 EC2 集群、安装从 S3 下载的 PR 发行版、加载对应 workload 并运行测试过程test procedure。7. 在 PR 上回帖作业地址最后一步通过actions/github-script在 PR 上发布评论告知 Jenkins 作业 URLbody: The Jenkins job url is ${workflowUrl} . Final results will be published once the job is completed.最终基准结果会在 Jenkins 作业完成后由基准作业回填到该 PR 上。8. 配套入口性能标签自动提示仓库还提供了一个辅助工作流 .github/workflows/add-performance-comment.yml当 PR 被标记上Performance、Search:Performance或Indexing:Performance标签时会自动在 PR 上添加一条评论引导贡献者阅读本指南并按需触发基准测试。这为性能相关改动提供了一条低门槛的入口提示。如何使用该工作流在 PR 上触发基准测试只需四步确保.github/benchmark-configs.json是最新的其中应包含有效的基准配置配置需声明支持的主版本号与集群/基准参数见下文 schema将工作流文件放入仓库即把benchmark-pull-request.yml可命名为benchmark.yml保存到目标仓库的.github/workflows目录下在 PR 上发表触发评论评论必须是一个包含关键字run-benchmark-test与配置 ID 的 JSON 对象监控进度工作流会依次校验评论、执行审批如需、构建发行版并触发 Jenkins 作业随后在 PR 上回帖 Jenkins 作业 URL可在其中跟踪进度与最终结果。示例评论格式运行配置 ID 为id_1的基准测试只需在 PR issue 下发表以下评论{run-benchmark-test: id_1}请注意评论必须是合法的 JSON且属性名严格为run-benchmark-test配置 ID 必须存在于 .github/benchmark-configs.json 中且其supported_major_versions必须包含当前 PR 对应版本的主版本号若评论格式非法或配置不被支持工作流会在 PR 上回帖提示并失败。如何新增一个基准测试配置benchmark-configs.json中的每个配置项遵循以下 schema{ id_number: { description: Short description of the configuration, supported_major_versions: [2, 3], cluster-benchmark-configs: { SINGLE_NODE_CLUSTER: Use single node cluster for benchmarking, accepted values are \true\ or \false\, MIN_DISTRIBUTION: Use OpenSearch min distribution, should always be \true\, MANAGER_NODE_COUNT: For multi-node cluster tests, number of cluster manager nodes, empty value defaults to 3., DATA_NODE_COUNT: For multi-node cluster tests, number of data nodes, empty value defaults to 2., DATA_INSTANCE_TYPE: EC2 instance type for data node, empty defaults to r5.xlarge., DATA_NODE_STORAGE: Data node ebs block storage size, empty value defaults to 100Gb, JVM_SYS_PROPS: A comma-separated list of keyvalue pairs that will be added to jvm.options as JVM system properties, INSTALL_STREAMING_PLUGINS: Bundle arrow-base and arrow-flight-rpc into the pull request distribution, accepted values are \true\ or \false\, ADDITIONAL_CONFIG: Additional space delimited opensearch.yml config parameters. e.g., search.concurrent_segment_search.enabled:true, TEST_WORKLOAD: The workload name from OpenSearch Benchmark Workloads. Default is nyc_taxis, WORKLOAD_PARAMS: With this parameter you can inject variables into workloads, e.g.{\number_of_replicas\:\0\,\number_of_shards\:\3\}, EXCLUDE_TASKS: Defines a comma-separated list of test procedure tasks not to run. e.g. type:search, INCLUDE_TASKS: Defines a comma-separated list of test procedure tasks to run. By default, all tasks listed in a test procedure array are run., TEST_PROCEDURE: Defines a test procedure to use. e.g., append-no-conflicts,significant-text. Uses default if none provided., CAPTURE_NODE_STAT: Enable opensearch-benchmark node-stats telemetry to capture system level metrics like cpu, jvm etc. }, cluster_configuration: { size: Single-Node/Multi-Node, data_instance_config: data-instance-config, e.g., 4vCPU, 32G Mem, 16G Heap } } }字段要点说明字段含义默认值 / 取值范围id_number配置唯一标识即触发评论中run-benchmark-test的值形如id_1description配置的简短描述必填supported_major_versions该配置支持的主版本号数组如[3]SINGLE_NODE_CLUSTER是否使用单节点集群true/falseMIN_DISTRIBUTION是否使用 OpenSearch min 发行版应始终为trueMANAGER_NODE_COUNT多节点测试中的集群管理节点数空值默认 3DATA_NODE_COUNT多节点测试中的数据节点数空值默认 2DATA_INSTANCE_TYPE数据节点的 EC2 实例类型空值默认r5.xlargeDATA_NODE_STORAGE数据节点 EBS 块存储大小空值默认 100GBJVM_SYS_PROPS追加到jvm.options的 JVM 系统属性逗号分隔的 keyvalue 列表可选INSTALL_STREAMING_PLUGINS是否把 arrow-base、arrow-flight-rpc 打入 PR 发行版true/falseADDITIONAL_CONFIG追加到opensearch.yml的配置参数空格分隔如search.concurrent_segment_search.enabled:trueTEST_WORKLOAD使用的 OpenSearch Benchmark workload 名称默认nyc_taxisWORKLOAD_PARAMS向 workload 注入的变量JSON 对象字符串如{number_of_replicas:0,number_of_shards:1}EXCLUDE_TASKS不执行的测试任务列表逗号分隔如type:searchINCLUDE_TASKS仅执行的测试任务列表逗号分隔默认执行全部任务TEST_PROCEDURE使用的测试过程test procedure如append-no-conflicts、restore-from-snapshot、intra-segmentCAPTURE_NODE_STAT是否开启 node-stats 遥测采集 CPU/JVM 等系统级指标true/falsecluster_configuration.size集群规模说明单节点/多节点描述性字段cluster_configuration.data_instance_config数据实例规格说明如4vCPU, 32G Mem, 16G HeapWORKLOAD_PARAMS是使用频率最高的调优入口之一对于依赖预置快照数据的 workload需要注入快照仓库与快照名称等参数对于普通 workload则常用number_of_shards、number_of_replicas控制分片与副本数。TEST_PROCEDURE则决定了测试流程默认追加型过程面向索引压测restore-from-snapshot用于直接从快照恢复数据后只跑搜索类任务intra-segment用于段内intra-segment搜索过程。如果需要为你的改动新增合适的集群与基准配置请新建 PR 提交对benchmark-configs.json的修改并同时更新cluster_configuration描述方便评审与后续维护。仓库内现有配置示例当前 .github/benchmark-configs.json 已内置id_1id_17共 17 个配置可作参考模板例如id_1nyc_taxisworkload 纯索引测试单节点、1 分片 0 副本、排除 search 任务、开启 node-statsid_3big5workload 搜索测试使用restore-from-snapshot过程从快照恢复数据数据节点实例类型c5.2xlargeid_6/id_7/id_8在big5上分别开启并发段搜索的不同形态——search.concurrent_segment_search.enabled:true、mode:all、mode:autoid_9开启近似 range 查询实验特性opensearch.experimental.feature.approximate_point_range_query.enabled:true的搜索测试id_13/id_14使用intra-segment测试过程的段内搜索基准id_16ClickBench workload 的 DSL 查询测试快照恢复 3 分片warmup 10 次、正式 20 次迭代id_17ClickBench 流式聚合基准安装流式插件、注入 Netty 相关 JVM 系统属性并开启stream.search.enabled等实验特性。这些配置既可用于验证某个具体特性的性能影响也为新增配置提供了贴近实战的样板。如何将结果与基线对比单纯跑出基准数据还不够更重要的是判断改动相对现状是好是坏。OpenSearch 官方维护了一套基线数据每晚针对 3.0 与 2.x 的最新构建发行版使用与 PR 测试完全相同的集群与基准配置运行基准测试生成基线数据并公开在看板目前标注为 WIP即仍在建设中上。PR 测试结果可与该看板中的基线进行对照分析。此外官方计划在未来引入 OpenSearch Benchmark 的compare命令能力直接在 PR 上自动执行改动版本 vs 基线版本的对比并把对比结果发布到 PR 评论中届时无需手动对照看板即可获得结论。需要特别注意的是基线对比有效的前提是配置完全一致。因此在编写benchmark-configs.json时应尽量沿用官方baseline_cluster_config对应的实例规格、分片数、副本数与 workload 参数避免因配置漂移导致对比失真。注意事项与前置条件要启用这套基准测试能力仓库需要预先配置以下 secrets见工作流源码中的引用GITHUB_TOKENGitHub 内置令牌用于评论与 API 调用UPLOAD_ARCHIVE_ARTIFACT_ROLE用于以 OIDC 方式代入的 AWS 角色授予上传 S3 的权限ARCHIVE_ARTIFACT_BUCKET_NAME存放 PR 发行版归档的 S3 桶名ARTIFACT_BUCKET_CLOUDFRONT_URL该 S3 桶的 CloudFront 分发地址仅下载JENKINS_PR_BENCHMARK_GENERIC_WEBHOOK_TOKEN触发 Jenkins 基准作业的 webhook tokenJENKINS_GITHUB_USER/JENKINS_GITHUB_USER_TOKENJenkins 侧访问 GitHub 使用的账号凭据。同时.github/CODEOWNERS中应列出基准流程审批人即具有 maintain 权限的仓库协作者非维护者触发的基准请求会进入人工审批环节。审批 issue 在审批人评论完成后会自动关闭。延伸仓库内的微基准测试套件除了 PR 级别的端到端基准测试OpenSearch 仓库还维护了一个基于 JMH 的微基准测试套件见 benchmarks/README.md覆盖搜索聚合、排序、路由分配、translog、日期格式化、哈希函数等性能关键路径源码位于 benchmarks/src/main/java。其用途是在性能关键组件上定位性能回归并支持临时性的 ad-hoc 微基准合入 PR 前需移除。启动方式# 运行全部微基准 gradlew -p benchmarks run # 运行单个基准类注意引号内的前导空格 gradlew -p benchmarks run --args MemoryStatsBenchmark # 附加 GC 分析或 perf 分析 gradlew -p benchmarks run --args MemoryStatsBenchmark -prof gc建议在提交 PR 前先用微基准套件验证热点路径、再用本文所述 PR 基准工作流做整体负载级验证从而形成方法级 负载级的完整性能保障闭环。总结通过run-benchmark-test评论触发、配置驱动、审批受控、构建上传、Jenkins 执行的完整链路OpenSearch 将 PR 级性能基准测试做成了可自助、可复现、可追溯的标准化流程。贡献者在提交涉及性能的改动时只需按 PERFORMANCE_BENCHMARKS.md 与本文的方法选择或新增配置即可在真实负载下验证改动质量并与官方基线对照得出客观结论。【免费下载链接】OpenSearch Open source distributed and RESTful search engine.项目地址: https://gitcode.com/gh_mirrors/op/OpenSearch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenSearch PR 性能基准测试指南：基于 GitHub Actions 与 benchmark-config 的自动化 Benchmark 工作流
OpenSearch PR 性能基准测试指南基于 GitHub Actions 与 benchmark-config 的自动化 Benchmark 工作流【免费下载链接】OpenSearch Open source distributed and RESTful search engine.项目地址: https://gitcode.com/gh_mirrors/op/OpenSearch本指南面向 OpenSearch 仓库的贡献者与维护者系统讲解如何通过benchmark-pull-requestGitHub Actions 工作流在 Pull Request 上自动运行性能基准测试涵盖触发方式、审批流程、构建与发布链路、基准配置结构以及结果对比方法。读完本文你将掌握在 PR 评论中一键触发基准测试、为特定改动新增基准测试配置、以及将测试结果与官方基线进行对比的完整实战方案。为什么需要在 PR 上运行性能基准测试性能是 OpenSearch 这类分布式搜索引擎的核心质量属性。代码改动尤其是搜索、索引、聚合等路径上的改动可能在正确性测试全部通过的情况下引入明显的性能回退。为此OpenSearch 仓库通过benchmark-pull-request工作流定义见 .github/workflows/benchmark-pull-request.yml实现了在 PR 评论中发出指定指令即可自动对当前 PR 的代码改动构建发行版并运行标准化基准测试的能力从而以一致、可复现的方式持续维护仓库的性能标准。除了这套端到端的 PR 基准测试工作流仓库还维护了一套基于 JMH 的微基准测试套件见 benchmarks/README.md用于在性能关键组件上定位回归两者互为补充微基准测试关注热点方法级性能PR 基准测试则面向真实负载workload级别的整体性能。工作流触发机制该工作流基于issue_comment事件触发即当有人在 PR本质上是一个 issue上新建评论时触发on: issue_comment: types: [created]同时工作流通过if条件做了三重过滤对应 benchmark-pull-request.yml仓库必须是opensearch-project/OpenSearch防止 fork 仓库误触发事件对象必须是 PRgithub.event.issue.pull_request存在而非普通 issue评论正文必须包含关键字run-benchmark-test。也就是说只有在 PR 上发表的、包含特定 JSON 关键字的评论才会真正启动基准测试流水线。这也是保证基准资源不被随意消耗的第一道防线。工作流关键步骤拆解结合 .github/workflows/benchmark-pull-request.yml 的源码实现整个工作流共 8 个 job 步骤可归纳为以下核心环节1. 校验评论格式与配置工作流首先读取当前 OpenSearch 版本并设置环境变量。版本取自 buildSrc/version.properties例如OPENSEARCH_VERSION$(awk -F /^opensearch[[:space:]]*/ {gsub(/[[:space:]]/, , $2); print $2} buildSrc/version.properties) major_version$(echo $OPENSEARCH_VERSION | cut -d. -f1) echo OPENSEARCH_MAJOR_VERSION$major_version $GITHUB_ENV随后使用actions/github-script完成三件事尝试将评论正文JSON.parse为 JSON 对象解析失败则判定为无效检查 JSON 是否包含run-benchmark-test属性并取出配置 ID读取 .github/benchmark-configs.json校验该配置 ID 是否存在且其supported_major_versions中是否包含当前 OpenSearch 主版本号例如 3。校验通过后配置中的cluster-benchmark-configs会以环境变量的形式注入后续步骤如果配置还带有baseline_cluster_config字段也会一并导出。2. 无效评论提示与失败若评论格式非法、配置 ID 不存在或主版本不支持工作流会调用 GitHub API 在 PR 上回帖提示Invalid comment format or config id并引导参考本指南PERFORMANCE_BENCHMARKS.md随后显式exit 1使工作流失败。这一设计让用户能立刻知道问题所在而不是无响应地等待。3. 手动审批如需要审批环节的目的是防止非维护者滥用基准资源工作流先调用 GitHub API 获取仓库中具有maintain权限的协作者列表作为审批人集合若评论者不在该集合中则通过trstringer/manual-approvalaction 创建一条审批 issue标题形如 Request to approve/deny benchmark run for PR #xxx工作流暂停直到审批人在该 issue 上以评论方式批准或拒绝审批完成后该 issue 自动关闭。对于维护者maintainer本人发起的请求则会跳过审批直接执行。仓库中可以通过 .github/CODEOWNERS 了解各模块的代码所有者构成。4. 从 PR 代码构建并组装 OpenSearch审批通过后工作流先检出PR 的 head 仓库与 head commit而不是默认分支然后配置 Java 21Temurin 发行版再执行构建任务tasks(:distribution:archives:linux-tar:assemble) if [[ $INSTALL_STREAMING_PLUGINS true ]]; then tasks(:plugins:arrow-base:bundlePlugin :plugins:arrow-flight-rpc:bundlePlugin) fi ./gradlew ${tasks[]} -Dbuild.snapshotfalse默认构建产物是x64 Linux tar 版 min 发行版。当配置要求安装流式插件INSTALL_STREAMING_PLUGINS: true时还会把arrow-base与arrow-flight-rpc插件对应 plugins/arrow-base、plugins/arrow-flight-rpcbundle 进发行版并通过opensearch-plugin install --batch打入 tar 包。5. 上传到 S3构建完成后工作流通过aws-actions/configure-aws-credentials以 OIDC 方式代入UPLOAD_ARCHIVE_ARTIFACT_ROLE角色将 tar 包上传到ARCHIVE_ARTIFACT_BUCKET_NAME指定的 S3 桶aws s3 cp distribution/archives/linux-tar/build/distributions/opensearch-min-$OPENSEARCH_VERSION-linux-x64.tar.gz \ s3://${{ secrets.ARCHIVE_ARTIFACT_BUCKET_NAME }}/PR-$PR_NUMBER/该 S3 桶前端由 CloudFront 承载仅允许下载用于后续 Jenkins 基准作业拉取构建产物桶上的生命周期策略会在30 天后自动删除上传的归档。6. 触发 Jenkins 基准作业接下来工作流检出opensearch-build仓库用于编排 OpenSearch 构建与测试的基础设施仓库并调用其 benchmark 脚本通过 webhook token 触发 Jenkins 上的基准测试作业bash opensearch-build/scripts/benchmark/benchmark-pull-request.sh \ -t ${{ secrets.JENKINS_PR_BENCHMARK_GENERIC_WEBHOOK_TOKEN }} \ -u ${{ secrets.JENKINS_GITHUB_USER}} \ -p ${{ secrets.JENKINS_GITHUB_USER_TOKEN}}基准测试本身基于 OpenSearch Benchmark 工具执行Jenkins 作业会依据前面注入的cluster-benchmark-configs环境变量拉起指定规格的 EC2 集群、安装从 S3 下载的 PR 发行版、加载对应 workload 并运行测试过程test procedure。7. 在 PR 上回帖作业地址最后一步通过actions/github-script在 PR 上发布评论告知 Jenkins 作业 URLbody: The Jenkins job url is ${workflowUrl} . Final results will be published once the job is completed.最终基准结果会在 Jenkins 作业完成后由基准作业回填到该 PR 上。8. 配套入口性能标签自动提示仓库还提供了一个辅助工作流 .github/workflows/add-performance-comment.yml当 PR 被标记上Performance、Search:Performance或Indexing:Performance标签时会自动在 PR 上添加一条评论引导贡献者阅读本指南并按需触发基准测试。这为性能相关改动提供了一条低门槛的入口提示。如何使用该工作流在 PR 上触发基准测试只需四步确保.github/benchmark-configs.json是最新的其中应包含有效的基准配置配置需声明支持的主版本号与集群/基准参数见下文 schema将工作流文件放入仓库即把benchmark-pull-request.yml可命名为benchmark.yml保存到目标仓库的.github/workflows目录下在 PR 上发表触发评论评论必须是一个包含关键字run-benchmark-test与配置 ID 的 JSON 对象监控进度工作流会依次校验评论、执行审批如需、构建发行版并触发 Jenkins 作业随后在 PR 上回帖 Jenkins 作业 URL可在其中跟踪进度与最终结果。示例评论格式运行配置 ID 为id_1的基准测试只需在 PR issue 下发表以下评论{run-benchmark-test: id_1}请注意评论必须是合法的 JSON且属性名严格为run-benchmark-test配置 ID 必须存在于 .github/benchmark-configs.json 中且其supported_major_versions必须包含当前 PR 对应版本的主版本号若评论格式非法或配置不被支持工作流会在 PR 上回帖提示并失败。如何新增一个基准测试配置benchmark-configs.json中的每个配置项遵循以下 schema{ id_number: { description: Short description of the configuration, supported_major_versions: [2, 3], cluster-benchmark-configs: { SINGLE_NODE_CLUSTER: Use single node cluster for benchmarking, accepted values are \true\ or \false\, MIN_DISTRIBUTION: Use OpenSearch min distribution, should always be \true\, MANAGER_NODE_COUNT: For multi-node cluster tests, number of cluster manager nodes, empty value defaults to 3., DATA_NODE_COUNT: For multi-node cluster tests, number of data nodes, empty value defaults to 2., DATA_INSTANCE_TYPE: EC2 instance type for data node, empty defaults to r5.xlarge., DATA_NODE_STORAGE: Data node ebs block storage size, empty value defaults to 100Gb, JVM_SYS_PROPS: A comma-separated list of keyvalue pairs that will be added to jvm.options as JVM system properties, INSTALL_STREAMING_PLUGINS: Bundle arrow-base and arrow-flight-rpc into the pull request distribution, accepted values are \true\ or \false\, ADDITIONAL_CONFIG: Additional space delimited opensearch.yml config parameters. e.g., search.concurrent_segment_search.enabled:true, TEST_WORKLOAD: The workload name from OpenSearch Benchmark Workloads. Default is nyc_taxis, WORKLOAD_PARAMS: With this parameter you can inject variables into workloads, e.g.{\number_of_replicas\:\0\,\number_of_shards\:\3\}, EXCLUDE_TASKS: Defines a comma-separated list of test procedure tasks not to run. e.g. type:search, INCLUDE_TASKS: Defines a comma-separated list of test procedure tasks to run. By default, all tasks listed in a test procedure array are run., TEST_PROCEDURE: Defines a test procedure to use. e.g., append-no-conflicts,significant-text. Uses default if none provided., CAPTURE_NODE_STAT: Enable opensearch-benchmark node-stats telemetry to capture system level metrics like cpu, jvm etc. }, cluster_configuration: { size: Single-Node/Multi-Node, data_instance_config: data-instance-config, e.g., 4vCPU, 32G Mem, 16G Heap } } }字段要点说明字段含义默认值 / 取值范围id_number配置唯一标识即触发评论中run-benchmark-test的值形如id_1description配置的简短描述必填supported_major_versions该配置支持的主版本号数组如[3]SINGLE_NODE_CLUSTER是否使用单节点集群true/falseMIN_DISTRIBUTION是否使用 OpenSearch min 发行版应始终为trueMANAGER_NODE_COUNT多节点测试中的集群管理节点数空值默认 3DATA_NODE_COUNT多节点测试中的数据节点数空值默认 2DATA_INSTANCE_TYPE数据节点的 EC2 实例类型空值默认r5.xlargeDATA_NODE_STORAGE数据节点 EBS 块存储大小空值默认 100GBJVM_SYS_PROPS追加到jvm.options的 JVM 系统属性逗号分隔的 keyvalue 列表可选INSTALL_STREAMING_PLUGINS是否把 arrow-base、arrow-flight-rpc 打入 PR 发行版true/falseADDITIONAL_CONFIG追加到opensearch.yml的配置参数空格分隔如search.concurrent_segment_search.enabled:trueTEST_WORKLOAD使用的 OpenSearch Benchmark workload 名称默认nyc_taxisWORKLOAD_PARAMS向 workload 注入的变量JSON 对象字符串如{number_of_replicas:0,number_of_shards:1}EXCLUDE_TASKS不执行的测试任务列表逗号分隔如type:searchINCLUDE_TASKS仅执行的测试任务列表逗号分隔默认执行全部任务TEST_PROCEDURE使用的测试过程test procedure如append-no-conflicts、restore-from-snapshot、intra-segmentCAPTURE_NODE_STAT是否开启 node-stats 遥测采集 CPU/JVM 等系统级指标true/falsecluster_configuration.size集群规模说明单节点/多节点描述性字段cluster_configuration.data_instance_config数据实例规格说明如4vCPU, 32G Mem, 16G HeapWORKLOAD_PARAMS是使用频率最高的调优入口之一对于依赖预置快照数据的 workload需要注入快照仓库与快照名称等参数对于普通 workload则常用number_of_shards、number_of_replicas控制分片与副本数。TEST_PROCEDURE则决定了测试流程默认追加型过程面向索引压测restore-from-snapshot用于直接从快照恢复数据后只跑搜索类任务intra-segment用于段内intra-segment搜索过程。如果需要为你的改动新增合适的集群与基准配置请新建 PR 提交对benchmark-configs.json的修改并同时更新cluster_configuration描述方便评审与后续维护。仓库内现有配置示例当前 .github/benchmark-configs.json 已内置id_1id_17共 17 个配置可作参考模板例如id_1nyc_taxisworkload 纯索引测试单节点、1 分片 0 副本、排除 search 任务、开启 node-statsid_3big5workload 搜索测试使用restore-from-snapshot过程从快照恢复数据数据节点实例类型c5.2xlargeid_6/id_7/id_8在big5上分别开启并发段搜索的不同形态——search.concurrent_segment_search.enabled:true、mode:all、mode:autoid_9开启近似 range 查询实验特性opensearch.experimental.feature.approximate_point_range_query.enabled:true的搜索测试id_13/id_14使用intra-segment测试过程的段内搜索基准id_16ClickBench workload 的 DSL 查询测试快照恢复 3 分片warmup 10 次、正式 20 次迭代id_17ClickBench 流式聚合基准安装流式插件、注入 Netty 相关 JVM 系统属性并开启stream.search.enabled等实验特性。这些配置既可用于验证某个具体特性的性能影响也为新增配置提供了贴近实战的样板。如何将结果与基线对比单纯跑出基准数据还不够更重要的是判断改动相对现状是好是坏。OpenSearch 官方维护了一套基线数据每晚针对 3.0 与 2.x 的最新构建发行版使用与 PR 测试完全相同的集群与基准配置运行基准测试生成基线数据并公开在看板目前标注为 WIP即仍在建设中上。PR 测试结果可与该看板中的基线进行对照分析。此外官方计划在未来引入 OpenSearch Benchmark 的compare命令能力直接在 PR 上自动执行改动版本 vs 基线版本的对比并把对比结果发布到 PR 评论中届时无需手动对照看板即可获得结论。需要特别注意的是基线对比有效的前提是配置完全一致。因此在编写benchmark-configs.json时应尽量沿用官方baseline_cluster_config对应的实例规格、分片数、副本数与 workload 参数避免因配置漂移导致对比失真。注意事项与前置条件要启用这套基准测试能力仓库需要预先配置以下 secrets见工作流源码中的引用GITHUB_TOKENGitHub 内置令牌用于评论与 API 调用UPLOAD_ARCHIVE_ARTIFACT_ROLE用于以 OIDC 方式代入的 AWS 角色授予上传 S3 的权限ARCHIVE_ARTIFACT_BUCKET_NAME存放 PR 发行版归档的 S3 桶名ARTIFACT_BUCKET_CLOUDFRONT_URL该 S3 桶的 CloudFront 分发地址仅下载JENKINS_PR_BENCHMARK_GENERIC_WEBHOOK_TOKEN触发 Jenkins 基准作业的 webhook tokenJENKINS_GITHUB_USER/JENKINS_GITHUB_USER_TOKENJenkins 侧访问 GitHub 使用的账号凭据。同时.github/CODEOWNERS中应列出基准流程审批人即具有 maintain 权限的仓库协作者非维护者触发的基准请求会进入人工审批环节。审批 issue 在审批人评论完成后会自动关闭。延伸仓库内的微基准测试套件除了 PR 级别的端到端基准测试OpenSearch 仓库还维护了一个基于 JMH 的微基准测试套件见 benchmarks/README.md覆盖搜索聚合、排序、路由分配、translog、日期格式化、哈希函数等性能关键路径源码位于 benchmarks/src/main/java。其用途是在性能关键组件上定位性能回归并支持临时性的 ad-hoc 微基准合入 PR 前需移除。启动方式# 运行全部微基准 gradlew -p benchmarks run # 运行单个基准类注意引号内的前导空格 gradlew -p benchmarks run --args MemoryStatsBenchmark # 附加 GC 分析或 perf 分析 gradlew -p benchmarks run --args MemoryStatsBenchmark -prof gc建议在提交 PR 前先用微基准套件验证热点路径、再用本文所述 PR 基准工作流做整体负载级验证从而形成方法级 负载级的完整性能保障闭环。总结通过run-benchmark-test评论触发、配置驱动、审批受控、构建上传、Jenkins 执行的完整链路OpenSearch 将 PR 级性能基准测试做成了可自助、可复现、可追溯的标准化流程。贡献者在提交涉及性能的改动时只需按 PERFORMANCE_BENCHMARKS.md 与本文的方法选择或新增配置即可在真实负载下验证改动质量并与官方基线对照得出客观结论。【免费下载链接】OpenSearch Open source distributed and RESTful search engine.项目地址: https://gitcode.com/gh_mirrors/op/OpenSearch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考