コンテンツにスキップ

テストを追加する

ngx_mrubyのテストは、mrubyのテストを使います。ngx_mrubyのテストは、まだごく初期の実験的なバージョンです。

プルリクエストを歓迎します。

test/conf/nginx.confにlocationの設定を追加する
Section titled “test/conf/nginx.confにlocationの設定を追加する”
# Nginx.hello test
location /mruby {
mruby_content_handler build/nginx/html/unified_hello.rb cache;
}
locationの設定にスクリプトが要るなら、test/html/にフックのスクリプトを追加する
Section titled “locationの設定にスクリプトが要るなら、test/html/にフックのスクリプトを追加する”
# test/htdocs/unified_hello.rb
if server_name == "NGINX"
Server = Nginx
elsif server_name == "Apache"
Server = Apache
end
Server::rputs "Hello #{Server::module_name}/#{Server::module_version} world!"
test/t/ngx_mruby.rbにテストのコードを追加する
Section titled “test/t/ngx_mruby.rbにテストのコードを追加する”
assert('ngx_mruby', 'location /mruby') do
res = HttpRequest.new.get base + '/mruby'
assert_equal 'Hello ngx_mruby/0.0.1 world!', res["body"]
end

テストのクライアントは、build_config.rbのtestのビルドです。このクライアントはNO_SSLでビルドするので、HttpRequestとSimpleHttpはhttpsのリクエストを送れません。HTTPSのリクエストを送るには、既存のテストと同じように、base_ssl(port)が返すURLでcurl -kを実行するか、openssl s_client -connect localhost:<port>を実行してください。例は、test/t/ngx_mruby.rbのテストにある`curl -s -k #{base_ssl(18082) + '/'}`です。

フラグメントとケースのファイルでテストを追加する

Section titled “フラグメントとケースのファイルでテストを追加する”

test/conf/nginx.confとtest/t/ngx_mruby.rbを編集する代わりに、テストを専用のファイルに置くこともできます。

  • test/conf/conf.d/<name>.conf:http {}ブロックの最後でインクルードするフラグメントです。フラグメントは、専用のポートのserver {}を持ちます。ポートは18080から18199です。ただし18116は、test/t/cases/_second_instance.rbが起動する2つ目のnginxが使います。stream {}のフラグメントはtest/conf/conf.d/stream/に置きます。そのポートは12345から12399で、12357は2つ目のnginxが使います。各ポートは、これらの範囲の5桁の数で書いてください。そう書くと、TEST_SH_PORT_OFFSETで、そのポートがずれます。説明は下の「ポート」にあります。masterのケースはマージでnextに入るので、新しいケースには、両方のブランチで空いているポートを選んでください。origin/masterとorigin/nextで、その番号をgit grepして確かめます。18110より小さいポートも使えます。
  • test/t/cases/<name>.rb:test/t/ngx_mruby.rbの後に実行するテストのファイルです。test.shは、このファイルの先頭にtest/t/cases/_prelude.rbを付けて実行します。_prelude.rbは、base、base_ssl、http_host、html_path、nginx_t、tcp_client、second_instance、suite_pathを定義します。nginx_tは、生成した設定でnginx -tを実行します。suite_pathは、test.shが実行するスイートのコピーの中で、スイートのファイルのパスを返します。CRubyのヘルパーは、`ruby #{suite_path('test/t/cases/_x.rb')}`のように実行してください。説明は下の「ポート」にあります。ケースのファイルはSimpleTest.newで始まり、t.reportで終わります。名前が_で始まるファイルはヘルパーで、ケースとしては実行しません。_tcp_client.rb、_filter_connection_client.rb、_request_body_client.rb、_second_instance.rbは、_prelude.rbのヘルパーとケースがrubyで実行するCRubyのスクリプトです。_wait_for_listen.rbは、test.shがnginxを待つために実行するCRubyのスクリプトです。説明は下の「nginxがlistenするまで待つ」にあります。_agent_proxy_client.rbは、agent_proxy.rbが自分で実行するCRubyのスクリプトで、CRuby 3.0以降が要ります。このスクリプトはtest/soak/mock_llm.rbとtest/soak/http_client.rbを読み込み、リクエストを送る間、LLMのモックのupstreamを12372と12373で動かします。説明は下の「LLMのモックのupstream」にあります。このスクリプトは、key=valueの行を出力します。
  • フックのスクリプトは、これまでどおりtest/html/に置きます。フラグメントは、そのスクリプトをbuild/nginx/html/<name>.rbとして参照します。

test.shは、スイートのコピーにあるフラグメントにnginx.confと同じ置き換えをして、ビルドしたnginxのconf/conf.d/にコピーします。スイートのコピーの説明は、下の「ポート」にあります。そして、ケースのファイルを1つずつ順に実行します。ケースが失敗すると、test/t/ngx_mruby.rbのアサーションが失敗したときと同じく、test.shは0以外のステータスで終了します。

async_sleep_many.rbは、1つのコンテンツハンドラが1msのsleepを1,000回行うことを検査します。ポート18188の専用サーバーを使い、サーバー単位のハンドラは設定しません。応答のステータスと本文が、HTTP 200とslept:1000に一致するかを検査します。

処理後には、Nginx::Debug.statsのtimersとgc_root_fibersが処理前の値に戻ることも確かめます。各HTTP交換はtcp_clientの60秒上限を使い、EOFまで読みます。カウンタが無い場合や取得に失敗した場合も、ケースは失敗します。検査するのは待機中のタイマーと保持されたファイバーで、リクエストのプールの大きさではありません。

test.shは、全スイートのビルドでこの検査を流すため、nginxとngx_mrubyにNGX_MRUBY_DEBUG_STATSを定義します。既存のビルドを更新したら、ONLY_BUILD_NGX_MRUBY=1を使う前に、build/nginx-X.Y.Z/objs/Makefileを削除してから、一度sh test.shを流してフラグを反映してください。動的モジュールではbuild_dynamic/の同じファイルを削除し、BUILD_DYNAMIC_MODULE=1 sh test.shを実行してください。

nginxを自分で起動するケースは、CIのsanitizerのセルでも動きます。そうしたケースはnginx_tかsecond_instanceを使います。sanitizerのセルでは、リークしたプロセスがあると、LeakSanitizerがそのプロセスの出力にレポートを書き足し、終了ステータスを変えます。そのため、そうしたケースは、プルリクエストを開く前に、sanitizerのビルドで1回実行してください。手順は下の「2つのsanitizerの下でテストを実行する」にあります。nginx_tは、nginx -tの実行ではリークの検出を切ります。nginx -tは読んだ設定を解放せずに戻るので、検出を切らないと、nginx自身のメモリの確保がすべて報告されるからです。test/t/ngx_mruby.rbの最後にあるstreamだけのテストも、自分が起動したnginxを止めるnginx -s quitで、同じように検出を切ります。そのプロセスは、main()が最初に作るプールを解放せずに、nginxのmain()から戻ります。検出を切らないと、そのレポートはテストのランナーのstderr.logに入ります。second_instanceは、2つ目のnginxのerror.logかstderr.logにある、sanitizerの最初の行を、sanitizerとして返します。その行があると、ケースは2つ目のnginxのerror.logを出します。

test/t/cases/stream_async_sleep_udp_session.rbは、連続するsleep、バイナリ本文の完全一致、期限内のshutdownを確かめます。

CRubyのヘルパー_udp_wait_session.rbは、nginxとエコーの上流にポート12393-12396を使います。

ケースは順に実行します。ヘルパーがnginxを停止した後、ポート12393を使うworkersのケースが始まります。ヘルパーをsuite_pathから起動するので、TEST_SH_PORT_OFFSETで動かしたポートも使えます。

.github/workflows/test.ymlは、master、next、v*.xへのプルリクエスト、これらのブランチとv*タグへのpush、「Run workflow」で起動します。ルールセットが必須とするステータスチェックはci-okです。ci-okは、needsにある各ジョブが成功したか、changesの判定でスキップされた場合だけ成功します。対象はchanges、buildマトリクスの全ジョブ、filesで、nextではsoakとperfも含みます。masterのci-okは、まだperfを必要としません。masterには、この後のプルリクエストで加えます。マトリクスを実行する場合はvalgrindのセルも対象なので、そのエラーはci-okを失敗させます。CIのvalgrindを参照してください。nextでは、perfの結果にFAILかERRORの行があるときも、ci-okは失敗します。「callgrindで性能を比べる」の「CIで実行する」を参照してください。

プルリクエストの実行は、作成、再オープン、headへのpush、readyへの変更で始まります。イベントはpull_requestのopened、synchronize、reopened、ready_for_reviewです。Draftではchangesとci-ok以外は動かず、ジョブ名もci-ok (draft)になります。この実行ではテストしません。GitHubはDraftをマージしません。このジョブは別の名前なので、成功してもheadにci-okは付きません。そのため、readyにして始まる実行が成功するまで、headは必須チェックを満たしません。他のPR用ワークフローもDraftではスキップします。

readyのheadへpushすると、前のheadの実行をキャンセルして新しく実行します。baseが動くだけでは実行されません。gh api -X PUT repos/<owner>/<repo>/pulls/<number>/update-branchでブランチを更新すると、headへマージコミットがpushされて実行が始まります。その実行の結果は、そのときのheadのコミットと、merge refのbaseのコミットに対するものです。PRにはこの2つを記録します。AGENTS.mdの「Review and merge」の条件2は、この記録と、baseの更新によって再実行が必要になる条件を定めています。

キャンセルしたDraftの実行は、結果を報告しません。readyにすると、数える対象の実行が始まり、まだ動いているDraftの実行はcancel-in-progressでキャンセルされます。キャンセルされた実行のci-okは動かず、未完了の他のジョブと同様にcancelledになります。cancelledは成功ではありません。#692の実行41193944190がその例です。以前はalways()でci-okが動いて失敗し、#678では有効な実行の成功したci-okの横に、Draftの失敗したci-ok (draft)が残りました。実行41191594780を参照してください。開始前にキャンセルされたジョブの名前にはnameの式がそのまま残り、gh pr checksはcancelledをfailと表示します。どちらも有効な実行のci-okではありません。

それ以外の実行ではci-okにalways()を使います。必要なジョブが終わる前に、新しいpushか「Cancel workflow」で実行がキャンセルされると、ci-okは動いて失敗します。その実行はコミットを最後までテストしていないからです。新しいpushによる失敗は、置き換えられた古いheadに残ります。GitHubの説明ではcancelled()はワークフローがキャンセルされたことを示しますが、必要なジョブのtimeout-minutes超過でも真になるかは明記されていません。真になるなら!cancelled()のci-okはスキップされ、そのスキップが必須チェックを満たしてしまいます。site.ymlはnextへのpushとdispatchでだけ動き、ルールセットはそのジョブを要求しません。site.ymlのdeployは、buildが成功したときだけ動きます。サイトのCIを参照してください。

CIは、クリーンな環境での最後の確認です。変更を初めて試す場所ではありません。AGENTS.mdの「Branches and pull requests」にこの決まりがあります。CIが流す検査は、先に手元で流します。対象は、追加したファイルの検査(リポジトリに置かないファイル)、静的なモジュールと動的なモジュールでのテストスイート、2つのsanitizerとvalgrindの下でのテストスイート、callgrindの比較、ソークテスト、examples/startの手順、nginx-tests、サイトの検査、zizmorです。build_config.rb、test/gem_heads.sh、.github/workflows/gem-heads.ymlのどれかを変えるときは、GitHubから取るgemの先頭のコミットのレポートも対象です(GitHubから取るgemの先頭のコミット)。sanitizer、valgrind、callgrindの比較、ソークテストにはLinuxが要ります。macOSでは、このページの各節にあるように、Linuxのコンテナで流します。

CIが受け持つのは、1台のマシンでは用意しきれないものと、理由を書いてCIに残すと決めた検査だけです。1台のマシンでは用意しきれないものは、buildマトリクスのほかのセル(ソースからビルドしたOpenSSL 3.5.9を含みます)、x86-64のrunner、クリーンな環境です。CIは、手元で流した検査をこれらへ広げます。CIに残す検査は、いまはCodeQLの1つだけです(CodeQL)。

先に手元で流すと、失敗はCIへpushする前に手元で見つかります。runnerの都合で実行が落ちたときも、同じ検査の手元の結果があれば、コードに問題があるかどうかを切り分けられます。#796では、runnerがパッケージのミラーの名前解決に失敗し、3回の試行がinstallのステップで止まりました。

readyにする前に、作者は変更に関係する検査を手元で実行し、PRの「How was this tested」にコマンドと結果を書きます。どのPRでも、sh test/check_added_files.shを流します。test/ci/changes.shがbuildをstandardかfullと判定したら、CIの標準の4セルと同じく、静的なモジュールと動的なモジュールでのテストスイートと、sanitizerとvalgrindの下でのテストスイートを流します。テストだけを変えるときも同じです。レビュアーは記録を確認します。手元で流せる検査をCIに任せません。

readyのPRは必要なジョブだけを実行し、全体を約15分で終えます。2026年10月31日の#678では、buildのセルに6〜14分、マトリクス全体に15分かかりました。実行41191594773がその記録です。CIに検査を加える提案では、その検査をローカルで実行できるか、なぜCIでも要るか、実行が何分延びるかを書きます。

test/ci/changes.sh BASE HEADが変更ファイルを分類します。変更の種類で実行を決めるワークフローはすべてこのファイルを読み、方針を一か所に集約します。sh test/ci/changes_test.shで検査できます。出力はキーごとに1行で、分類はcode、tests、docs、site、examples、workflows、続いてsoakとperfがそれぞれtrueかfalseになります。最後のbuildは、buildマトリクスのどのセルを実行するかを表します。codeかtestsが真ならstandard、それ以外はnoneです。renameはgit diff --no-renamesで旧パスと新パスの両方を分類するため、ソースをdocs/へ移してもビルドします。test.ymlのchangesジョブは、実行の種類もスクリプトに渡します。渡すのは、Draftかどうか、readyのPRのラベル、push、タグ、「Run workflow」とそのvalgrind入力です。下の2つ目のテーブルの実行では、スクリプトはbuildを、全セルを表すfullか、noneに決めます。

次の2つのテーブルのジョブのうち、codeql以外は、作者が手元で流した検査を、runnerでもう一度流します。必須のステータスチェックを参照してください。codeqlはCIでだけ動きます(CodeQL)。gem-heads(.github/workflows/gem-heads.yml)は、test/ci/changes.shではなく、自分のパスフィルタで動くかを決めます。build_config.rb、test/gem_heads.sh、このワークフローのどれかを変えるreadyのPRで動きます。そのような変更では、作者が手元でbash test/gem_heads.sh build_config.rb "" .claude/tmp/gem-heads.tsvを流します(GitHubから取るgemの先頭のコミット)。

分類 パス readyのPRが実行するワークフロー
code src/、mrbgems/、mruby/、dependence/、build_config.rb、build_config.rb.lock、configure、configure.in、config.in、Makefile.in、build.sh、nginx_version、他の分類にない全パス test.ymlのbuildマトリクスのうち下の表の標準の4セル、soak、perf。nginx-tests、examples、codeqlは、それぞれのパスフィルタに従って動く
tests test/、test.sh、.github/workflows/test.yml test.ymlの標準の4セル。soakが真ならソーク、perfが真なら比較
docs docs/、トップレベルにあるMarkdownのファイル、AUTHORS、LEGAL、LICENSE、MITL ジョブなし。手元で検査:サイトのCI(next)、2.xページの検査(master)
site .github/workflows/site.ymlとsite/ ジョブなし。docsと同じ
examples examples/ examples。サイトはdocsと同じ扱い
workflows .github/のうちtest.ymlとsite.ymlを除いたもの zizmorは全ワークフローを検査。.github/workflows/と.github/codeql/はCodeQLも対象

標準の4セルは、静的モジュールと動的モジュール、nginxのmainline 1.31とstable 1.30を、それぞれ少なくとも1回ビルドします。メモリの検査も、2種類とも実行します。

セル nginx モジュール OpenSSL nginxの動かし方
nginx 1.31.8、静的モジュール 1.31.8 静的 --with-openssl-src 直接動かす
nginx 1.30.6、動的モジュール 1.30.6 動的 ビルドしてインストールしたOpenSSL 直接動かす
sanitizerのセル 1.31.8 静的 ビルドしてインストールしたOpenSSL AddressSanitizerとUndefinedBehaviorSanitizerを付けてビルドする。2つのsanitizerの下でテストを実行するを参照
valgrindのセル 1.31.8 静的 ビルドしてインストールしたOpenSSL valgrindの下で実行する。CIのvalgrindを参照

PRでは、この4セルを実行します。どのセルも、nginxをビルドする前にOpenSSL 3.5.9をビルドしてインストールします。1つ目のセルは、--with-openssl-srcでOpenSSLをnginxにも組み込み、configure.inとMakefile.inのこの経路を通ります。

valgrindのセルは、同じnginxとモジュールを、インストール済みのOpenSSLでビルドします。ソースから組み込む経路は通りません。

全セルは、nginx 1.31.8と1.30.6、静的モジュールか動的モジュールか、--with-openssl-srcを付けるかどうかを組み合わせた8セルに、sanitizerのセルを加えたものです。valgrindのセルは8セルの1つです。全セルは引き続き、夜間のvalgrindの実行、タグのpush、base入力のない「Run workflow」で実行します。タグの前にも、ベースブランチの先頭で実行します。タグの前のチェックのPRがあるときはそのPRの実行で、このPRにはラベルfull-matrixを付けます。チェックにPRが要らないときは、ベースブランチで「Run workflow」を実行します。docs/releases/README.mdの「タグの前に」を参照してください。ほかのセルでしか確かめられない変更、たとえばnginx 1.31.8の動的モジュール向けの変更は、そのバージョンでローカルで確かめます。バージョンはnginx_versionかセルのNGINX_VERSIONで選び、モジュールはBUILD_DYNAMIC_MODULEで選びます。そのPRにラベルfull-matrixを付けて、全セルを実行することもできます。

masterでは、test/ci/changes.shがbuildをstandardかfullにするPRは、buildマトリクスでいちばん古いnginx(masterでは1.26.3)と静的モジュールのスイートも手元で流します。masterの標準の4セルにそのバージョンが入っていないためで、nginxはバージョンによって受け付ける設定が違います(1.27.1より前のnginxは、コンテンツハンドラの無いstreamのserverを受け付けません)。nextでは、.github/workflows/test.ymlのfull_matrixのNGINX_VERSIONでいちばん古いバージョンは1.30.6で、これは動的モジュールの標準のセルのnginxです。そのため、そのようなPRの実行がこのバージョンをビルドするので、手元の実行は加えません。マトリクスのほかのバージョンで手元でスイートを流すとき(ほかのセルでしか確かめられない変更や、docs/releases/README.mdの「セキュリティの修正」の実行)は、CIのセルがNGINX_VERSIONから書くのと同じようにnginx_versionを書きます。nginx_versionの変更をコミットしないように、専用のチェックアウト(headのgit archive)で書き、そこでONLY_BUILD_NGX_MRUBYを付けずにtest.shを流します。理由はテストを実行するにあります。

$ V=1.30.6
$ printf 'NGINX_SRC_MAJOR=%s\nNGINX_SRC_MINOR=%s\nNGINX_SRC_PATCH=%s\nNGINX_SRC_VER=nginx-%s\n' $(echo $V | tr . ' ') $V > nginx_version
$ sh test.sh

soakはcodeが真か、test/soak/またはtest/build_release.shの変更時に真になります。perfはcodeが真か、性能測定に使うtest/perf/、test/build_release.sh、test/soak/のシナリオファイルの変更時に真になります。未分類のファイルはcodeとして全検査を実行し、理由を記載したPRで分類を追加するまでそのままです。複数の分類のファイルを変えるPRは、それぞれの分類に必要なジョブを、すべて実行します。

実行の種類 3つのジョブbuild、soak、perf
DraftのPR filesとともにスキップ。ジョブ名はci-ok (draft)
readyのPR merge refの第1親であるbaseとの差を上の表で分類。perfはbuildがstandardかfullなら起動し、perfが真かラベルperfで比較
ラベルfull-matrixを付けた、readyのPR ファイルにかかわらず、全セルとsoakを実行。perfはラベルのないPRと同じ
master、next、v*.xブランチへのpush スキップ
v*タグのpush 全セルとsoak。perfはPRのみ
base入力が無いかvalgrind入力がある手動実行。夜間の実行はこれにあたる 全セルとsoak。perfはPRのみ
baseだけの実行 ラベルのないPRとしてbaseとの差を分類する。perfはPRでだけ実行する

changesジョブは、実行のイベントからラベルを読みます。readyのPRに付けたラベルは、次の実行から効きます。次の実行は、headへのpushか、PRをDraftに戻してreadyにし直す操作で始まります。戻す操作はgh pr ready --undo、readyにする操作はgh pr readyです。ジョブを再実行してもイベントは変わらないので、読むラベルも前の実行と同じです。ラベルfull-matrixはPRを開くときにgh pr create --draft --label full-matrixで付け、readyにしたときに全セルの実行が始まるようにします。リポジトリにこのラベルがなければ、gh label create full-matrixで作ります。

test.ymlだけの変更はtestsなので、標準の4セルは実行しますが、全セル、soak、性能比較は実行しません。それらのジョブを変えるPRは、ラベルfull-matrixを付けるか、ブランチでgh workflow run test.yml --ref <branch>を実行して、それらのジョブを動かします。性能比較はラベルperfで動かします。手動実行のジョブ名はci-ok (manual)で、PRに補足の検証結果として記録します。「Review and merge」の条件2が求めるPR自身の実行とは別です。

「Run workflow」でbase入力にブランチかコミットIDを渡すと、スクリプトは、ブランチがbaseとのmerge baseから変えたファイルを分類します。こうすると、ブランチのPRで何が動くかを確かめられます。

$ gh workflow run test.yml --ref claude/topic -f base=next

この実行のジョブ名はci-ok (dry run)で、ci-okではありません。baseは実行する人が選ぶので、その結果は、ルールセットがコミットに求めるチェックにならないからです。同じように、valgrind入力のある実行のジョブ名はci-ok (valgrind)です。この実行は始まった時点のブランチの先頭をビルドするので、キャンセルされると、そのコミットに失敗したci-okが残るからです。そのほかの「Run workflow」のジョブ名はci-ok (manual)です。この実行はPRのマージコミットでなくブランチのheadを検査します。そのため、headにci-okとして付くと、PR自身の実行が成功する前に、PRの必須チェックを満たしてしまいます。valgrind-nightly.ymlは、ジョブの名前でなく、実行の結果を読みます。

masterとnextへのpushでは、changes、files、ci-okだけが動きます。どちらのブランチも、PRを通してだけ変更を受け付けます。AGENTS.mdの「Review and merge」の条件2により、セッションがPRをマージできるのは、PRの実行がまだそのマージに当てはまる間だけです。baseがその後に進んだときは、PRとbaseの新しいコミットの両方がcodeかtestsを変えたときだけ、CIを流し直します。ルールセットはci-okを求めますが、ブランチがbaseに追いついていることは求めません。ブランチの先頭を単独でビルドしてテストするには、gh workflow run test.yml --ref nextのように「Run workflow」を使います。夜間のvalgrindの実行もこの形の実行で、masterのvalgrind-nightly.ymlのスケジュールが、masterとnextで起動します。説明はCIのvalgrindにあります。ほかのワークフローは、それぞれの条件で動きます。siteはnextへのすべてのpushでデプロイします。codeqlは、src/、mrbgems/、ワークフロー、CodeQLの設定を変えるmasterとnextへのpushを検査します。説明はCodeQLにあります。nginx-tests、examples、zizmorは、PRのときにだけ動きます。

build、soak、perf、filesがスキップされたとき、ci-okがそれを成功と数えるのは、changesが成功し、その実行にそのジョブは要らないと判定した場合だけです。perfはプルリクエストでだけ動くので、buildがnoneの実行と、プルリクエストではない実行が、これに当たります。perfが始まっても、比べるファイルが無いとき、つまりperfがfalseでラベルperfも無いときは、測らずに成功します。changesの失敗のような別の理由でスキップされたジョブがあると、ci-okは失敗します。必要なジョブが成功しなかったときも失敗します。変更したファイルに対して不要なジョブをスキップしたPRは、その実行によって「Review and merge」の条件2を満たします。

リポジトリに置かないファイル

Section titled “リポジトリに置かないファイル”

filesジョブは、test/check_added_files.sh BASE HEAD TIPを実行します。このスクリプトは、ファイルの2つの一覧を調べます。

  • 変更が加えるファイル:HEADにあってBASEに無いパスです。スクリプトはgit diff --no-renames --diff-filter=Aでこの一覧を作るので、名前を変えたファイルや移動したファイルは、新しいパスに加わったものとして数えます。
  • 変更のコミットが加えるファイル:TIPからfirst parentをたどってBASEまで戻る各コミットを、そのコミットのfirst parentと比べます。コミットの範囲はgit log --first-parent BASE..TIPです。あるコミットが加え、後のコミットが消したファイルは、マージの後も履歴に残るので、これも調べる必要があります。

どちらの一覧のファイルも、test/forbidden_paths.txtのパターンに一致すると、終了ステータス1で失敗します。パターンに一致するのは、次のファイルです。

  • .claude/の下にある、AIのコーディングエージェントが作るセッションのディレクトリと、そのエージェントのローカルの設定。.claude/の下で通るのは、.claude/settings.json、.claude/commands/、.claude/skills/だけです。この3つも、別の.claude/の下にあると失敗します。
  • 最上位に作るビルドのディレクトリのbuild/、build_dynamic/、build_soak/、build_perf/と、mruby/build/
  • サイトのビルドのsite/dist/、site/build-screenshots/、site/generated/、site/.astro/
  • ./configureかMakefileが最上位に書くファイル。Makefile、config、config.status、autom4te.cache/、mrbgems_config、.mruby_versionと、.openssl_*_doneのファイルです。
  • .vagrant/
  • GNU Globalかctagsが作るタグのファイル
  • .logのファイル
  • .envと.env.*
  • 秘密鍵の素材
  • エディタやOSが残したファイル
  • node_modules/、__pycache__/、.pycのファイル
  • コアダンプ

1つ目の一覧のファイルは、空のとき、つまり0バイトのときにも失敗します。ただし、名前が.gitkeepか.keepのファイルは除きます。どちらの一覧にも、サブモジュールのエントリー、つまりgitlinkが入ります。gitの設定や.gitmodulesがサブモジュールを無視すると書いていても、同じく入ります。

スクリプトは、失敗した各パスを出力します。パスには、一致したパターンと、パターンのファイルでのその行か、「empty file」が付きます。また、そのファイルを加えたコミットも付きます。すべてのファイルが通ると、スクリプトは調べたファイルの数を出力し、0で終了します。次のときは、2で終了します。

  • パターンのファイルが無いとき
  • パターンが正しくないとき
  • リビジョンがリポジトリに無いとき
  • リポジトリがshallowクローンであるとき
  • gitのコマンドが失敗したとき

スクリプトが読むのは、パターンのファイルとgitのリポジトリだけです。

スクリプトは、コミットをfirst parentだけでたどります。その中のマージコミットは、そのコミットのfirst parentと比べます。そのため、2つ目の親が持ち込むファイルは、リポジトリでのパスで調べ、2つ目の親のコミットは1つずつは調べません。こうすると、./update-mruby-subtreeによるサブツリーのマージの、squashしたコミットを調べずに済みます。そのコミットのパスには、mruby/のプレフィックスがありません。一方で、マージしたサイドブランチのあるコミットが加え、同じサイドブランチの後のコミットが消したファイルは、このチェックからは見えません。

プルリクエストでは、ジョブは、プルリクエストのマージコミットを、fetch-depth: 0で履歴ごとチェックアウトします。そして、マージコミットを、そのfirst parentと比べます。first parentは、プルリクエストをマージした先のベースブランチです。また、プルリクエストのheadのコミットから、そのベースまでのコミットを調べます。headのコミットは、マージコミットの2つ目の親です。そのため、ブランチがベースより遅れているプルリクエストでも、その間にベースが消したファイルでは失敗しません。ブランチへのpushでは、ジョブは、ブランチの前の先頭のgithub.event.beforeを、pushしたコミットと比べます。そして、その間のコミットを調べます。タグのpush、ブランチを作るpush、手動の実行には比べるものが無いので、ジョブは成功します。スクリプトかパターンのファイルを変えるプルリクエストは、そのプルリクエストにあるバージョンのスクリプトとパターンで調べます。そのため、その変更はプルリクエストのレビューの対象になります。

test/forbidden_paths.txtは、1行に1つずつ、POSIXの拡張正規表現を持ちます。形式はgrep -Eが読むものと同じです。スクリプトは、各パターンが、リポジトリの最上位からのパスに一致するかを見ます。!で始まる行は例外です。.gitignoreと同じく、パスが一致した最後の行が結果を決めます。たとえば.claude/skills/a/SKILL.mdは、(^|/)\.claude/に一致し、その後で例外の!(^|/)\.claude/skills/に一致するので、通ります。一方、.claude/skills/a/.DS_Storeは、さらに下の(^|/)\.DS_Store$にも一致するので、失敗します。空の行と、#で始まる行はコメントです。パターンは一般的なものにしてください。ほかのプロジェクト、人、ホストの名前は、入れないでください。

プルリクエストを開く前にこのチェックを実行するには、変更をコミットし、ベースブランチと比べてください。nextへの変更なら、ベースはorigin/nextです。引数が2つでも、スクリプトはHEADからベースまでのコミットも調べます。スクリプトには履歴のすべてが要るので、shallowでないクローンで実行してください。

$ git fetch origin master
$ sh test/check_added_files.sh origin/master HEAD
check_added_files.sh: 2 added file(s) checked between origin/master and HEAD and in the 2 commit(s) of origin/master..HEAD, none forbidden or empty

ファイルが失敗したら、そのファイルを変更から外してください。git rm --cached <path>で外すと、ファイルはディスクに残ります。そのファイルがリポジトリに要るものなら、同じプルリクエストでtest/forbidden_paths.txtを変え、プルリクエストの説明に理由を書いてください。空のファイルなら、変えるのはスクリプトです。あるコミットが加え、後のコミットが消したファイルは、履歴に残ります。そのファイルは、加えたコミットから取り除くか、コミットをsquashしてください。取り除くには、たとえばgit rebase -iのコマンドを使ってください。

ngx.mruby.orgはnextのsite/でビルドします。/v2/の2.xページはmasterのdocs/から作ります。masterへのPRでは、2.xページの検査をCIで流しません。

ドキュメントやリンク先を変えるPRでは、readyにする前に手元で検査します。PRの「How was this tested」にコマンドと結果を書いてください。

  1. gitが追跡するMarkdownの相対リンクとアンカーを確かめます。masterに無いcheck_links.pyをnextから取り出して使います。Tは、リポジトリ外に用意した作業用ディレクトリです。

    $ git fetch origin next
    $ git show origin/next:site/scripts/check_links.py > "$T/check_links.py"
    $ git ls-files -z -- '*.md' ':!:mruby/' ':!:dependence/' | xargs -0 python3 "$T/check_links.py" .
  2. nextのチェックアウトで、site/に移動してnpm ci --ignore-scriptsとnpx playwright install chromium webkitを実行します。続けてNGX_MRUBY_V2_TREE=DIR npm run check:ciを流します。

    DIRは、検査するPRをチェックアウトしたディレクトリです。

このコマンドは、nextの3.xページとPRの2.xページをビルドし、ブラウザの検査も含めて確かめます。表示されたnextのコミットと、PRのheadを結果に添えてください。Rubyのブロックは、MRBCで指定したコンパイラか、同梱mrubyのmruby/build/host/bin/mrbcでコンパイルします。どちらも無ければ、その検査を省略したことを最後に表示します。

検査は、解決できないリンクやアンカー、gitが追跡しないファイルへのリンク、2.xバナーの欠落を検出します。検索結果に別のバージョンのページが混じった場合も失敗します。

docs/releases/のリリースノート(vX.Y.Z.mdとvX.Y.Z.ja.md)は、masterをnextへマージすると、3.xのページ(/releases/...と/ja/releases/...)にもなります。この検査は3.xのページをnextのチェックアウトのdocs/からビルドするので、PRが加えるか変えるリリースノートを、3.xのページとしては検査しません。nextの日本語のページの検査(和文と英数字の間のスペース、コードブロック、行の折り返し)も、そのファイルを読みません。そのため、リリースノートを加えるか変えるPRは、流す前にそのファイルをnextのチェックアウトのdocs/releases/にコピーし、pushしないローカルのコミットにします。

$ git add docs/releases/vX.Y.Z.md docs/releases/vX.Y.Z.ja.md
$ git commit -m 'Release notes to check (local only, not pushed)'

ジェネレーターはgitが追跡するファイルだけを読みます。また、site/scripts/export-docs.mjsは、ソースがコミットHEADに無いページで、source must exist at HEAD before exportと出して止まります。そのため、ステージするだけでは、新しいファイルでビルドが止まります。HEADにすでにあるファイルの変更なら通りますが、コミットにすれば、どちらの場合も通ります。こうすると、1回の実行で、そのファイルを2.xのページとしても3.xのページとしても検査します。check:ciはローカルのコミットを表示するので、その親であるnextのコミットと一緒に結果に書きます。終わったら、そのチェックアウトを消すか、origin/nextに戻します。こうすると、masterをマージした後のnextへのpushで、これらの検査のためにサイトのデプロイが止まることがありません。

公開に関わるワークフローは、次の2つです。

  • .github/workflows/site-dispatch.ymlはmasterへのpushごとに、nextのsite.ymlを起動します。新しいmasterから2.xページをビルドして検査し、成功したときだけ公開します。

    dispatchが拒否された場合や、起動した実行を特定できない場合は失敗します。

  • .github/workflows/site-v2.ymlは「Run workflow」でだけ動きます。gh workflow run site-v2.yml --ref <branch>で対象ブランチを選び、nextのサイトと対象ブランチの2.xページを組み合わせて検査します。成果物はsite-v2です。

公開時のsite.ymlが検査するMarkdownはnextのファイルです。サイトに載らないmasterのファイルは、作者が上のリンク検査で確かめます。どちらのワークフローもci-okのneedsには含まれません。

OpenSSF Best Practices

上はプロジェクトのOpenSSF Best Practicesのpassingバッジです。以下のScorecardとは別の評価です。

4つのワークフローがビルドのサプライチェーンとコードを検査します。どれもci-okのneedsにはなく、ルールセットを通じてマージを止めるものではありません。ただし、AGENTS.mdの「Review and merge」は、headのすべてのCIのチェックが成功することを求めます。そのPRで動いたzizmorとcodeqlも、このチェックに含まれます。PRで動くワークフローはDraftではスキップし、readyにすると始まります。

.github/workflows/zizmor.ymlは、zizmorを実行します。動くのは、.github/workflows/、.github/dependabot.yml、.github/zizmor.ymlを変えるreadyのプルリクエストと、「Run workflow」です。pushでは動きません。PRの実行で同じファイルを検査済みだからです。zizmorは、.github/の下のファイルを、デフォルトのpersonaで監査します。この監査には、GitHubに問い合わせる監査も入ります。たとえば、既知の脆弱性があるアクションや、アクションのリポジトリに無いコミットを調べる監査です。指摘が1つでもあると、ジョブは失敗します。同梱したmruby/のツリーには、mruby自身のワークフローがあり、ngx_mrubyはそれらを実行しません。それらのワークフローは監査しません。zizmorのバージョンは、ワークフローのversion:で固定しています。Dependabotは、アクションの固定は更新しますが、この入力は更新しません。

指摘は、ワークフローを直すか、理由を添えて受け入れます。受け入れるには、指摘のある行に# zizmor: ignore[<audit>]のコメントを付け、その上のコメントに理由を書きます。または、.github/zizmor.ymlにignoreのルールを書き、その隣に理由を書きます。プルリクエストを開く前に同じチェックを実行するには、次のようにします。オンラインの監査には、GitHubのトークンが要ります。

$ python3 -m venv .claude/tmp/zizmor && .claude/tmp/zizmor/bin/pip install zizmor==1.31.1
$ GH_TOKEN=$(gh auth token) .claude/tmp/zizmor/bin/zizmor --config .github/zizmor.yml .github

.github/workflows/scorecard.ymlは、OpenSSF Scorecardを実行します。動くのは、masterへのpush、毎週の定期の実行、「Run workflow」です。Scorecardはデフォルトブランチにしか対応しないので、プルリクエストでは動きません。このワークフローは、結果を、Scorecard APIのhttps://api.scorecard.dev/projects/github.com/matsumotory/ngx_mrubyに公開し、code scanningにアップロードします。code scanningの結果は、リポジトリのSecurityのタブにあります。また、このワークフローは、SARIFのファイルを、実行のアーティファクトとして5日間保存します。結果を公開すると、Scorecard APIがワークフロー自身を調べます。そのため、このワークフローにはrunのステップもdefaultsもありません。制限の一覧は、ワークフローのファイルの先頭のコメントにあります。

GitHubは、公開リポジトリで60日間活動が無いと、そのリポジトリで定期に動くワークフローを無効にします。そうなると、このワークフローも次の節のワークフローも定期には動かず、何も失敗しません。「Run workflow」で実行するか、ワークフローを有効に戻すと、再び動きます。有効に戻すコマンドは、gh workflow enable scorecard.ymlとgh workflow enable gem-heads.ymlです。

.github/workflows/codeql.ymlはCodeQLでc-cpp、ruby、actionsの3言語を解析し、結果をリポジトリのSecurityタブのcode scanningへ送ります。src/、mrbgems/、.github/workflows/、.github/codeql/を変更するmasterとnext向けのreadyのPRと両ブランチへのpush、毎週水曜日04:37 UTC、「Run workflow」で実行します。GitHubの定期実行はmasterのファイルから動くため、週次の対象はmasterです。

これは全PRと全pushで動いていたGitHubのdefault setupを置き換えます。default setupはオーナーが管理するリポジトリ設定で無効にしています。ワークフローのファイルはmasterとnextで共通です。

3言語ともbuild-mode: noneです。CとC++はnginxやmrubyをビルドせずソースを解析するため、ビルドは不要です。CodeQLのBuild options for compiled languagesでは、ビルドなしで作ったデータベースはビルドから作るものより精度が低い可能性があると説明しています。このワークフローも、ほかのワークフローと同じく、アクションをコミットIDで固定し、zizmorの検査を受けます。

vendoringしたmruby/とdependence/は解析しません。前者にはmruby自身がvendoringしたコードも含み、後者はngx_devel_kitです。initがconfig-fileとして読む.github/codeql/codeql-config.ymlのpaths-ignoreに指定しています。これらはgit subtreeで取り込むupstreamのコードで、手で編集しません。そのため、警告をこのリポジトリでは直さず、upstreamの変更は次のsubtreeの更新で取り込みます。AGENTS.mdの「Do not」を参照してください。

2026年10月31日にオーナーは、この除外、既存警告をvendored upstream codeとしてdismissすること、upstreamへ報告しないことを決めました。GitHubのWorkflow configuration options for code scanningでは、paths-ignoreがRubyなどのインタープリタ言語と、ビルドなしで解析するCとC++に適用されると説明しています。

CodeQLは、AGENTS.mdの「Branches and pull requests」がCIに残すと決めた、ただ1つの検査です。作者は、PRをreadyにする前にCodeQLを流しません。このジョブは結果をcode scanningへ送り、GitHubは、PRが変えた行に出た新しい警告を、PRの中に注釈として表示します(Triaging code scanning alerts in pull requests)。手元で流すには、CodeQLのbundleが要ります。固定したアクションが既定で使う版(2.27.3)では、Linuxのarm64向けが約550MBです。CodeQLのSystem requirementsでは、Linuxのarm64とApple Siliconへの対応はbetaです。このリポジトリでは、CodeQLを手元で流したことはありません。

GitHubから取るgemの先頭のコミット

Section titled “GitHubから取るgemの先頭のコミット”

.github/workflows/gem-heads.ymlは、test/gem_heads.shを実行します。動くのは、毎週月曜日、「Run workflow」、build_config.rbかスクリプトかワークフローを変えるreadyのプルリクエストです。スクリプトは、build_config.rbのconf.gem github:の各行について、次のことを報告します。

  • ビルドがクローンするブランチの先頭のコミット。ブランチは、その行のbranch:です。行にbranch:が無ければ、mrubyのデフォルトのmasterです。
  • gemのデフォルトブランチが、別のブランチかどうか
  • リポジトリの名前が変わったか、リポジトリがアーカイブされたか
  • 前のレポートから、先頭が動いたかどうか

conf.gem mgem:の行のmruby-secure-randomは調べません。mrubyは、このgemをmgem-listのリポジトリを通して解決します。

前のレポートは、このワークフローをmasterで実行して成功した、定期の実行か手動の実行のうち、いちばん新しい実行が残したアーティファクトgem-headsです。アーティファクトは90日間残ります。masterはbuild_config.rb.lockをコミットしないので、以前のビルドがどの先頭のコミットを取ったかを記録するのは、このレポートだけです。前のレポートが無い実行は、すべてのgemをnewと報告します。先頭が動いたgemは、警告のアノテーションと、ジョブのサマリーにあるテーブルのエントリーになり、2つのコミットを比べるリンクが付きます。それでも、ジョブは成功します。リポジトリかブランチを読めないgemがあると、ジョブは失敗します。以前の実行を一覧にできないときも、ジョブは失敗します。前のレポートを取得できないときは、警告になり、すべてのgemをnewと報告します。

チェックアウトでスクリプトを実行するには、次のようにします。スクリプトには、トークンを持つghのコマンドが要ります。

$ bash test/gem_heads.sh build_config.rb "" .claude/tmp/gem-heads.tsv

実行が先頭の移動を報告したら、セッションは次のようにします。これはセッションの手順で、オーナーの決定ではありません。

  • 比較のリンクの先にあるコミットを読みます。CIを含むmasterのすべてのビルドと、リリースした2.xのタグからのすべてのソースのビルドは、既に新しい先頭を取ります。移動だけではCIは動かないので、masterでtestワークフローを実行し、その結果を読みます。コマンドは、gh workflow run test.yml --ref masterです。
  • 新しい先頭でビルドかテストスイートが壊れるときや、2.xの設定、スクリプト、ビルドから見える挙動が変わるときは、その実行を添えてオーナーに報告します。そして、masterへのプルリクエストを提案します。プルリクエストの中身は、修正か、gemを最後の正常なコミットに固定するchecksum_hash:で、リリースノートのエントリーも入れます。エントリーの書き方はdocs/releases/README.mdにあります。オーナーのgemのmatsumotory/mruby-*には、AGENTS.mdの「Other repositories」が当てはまります。
  • nextではbuild_config.rb.lockが各gemを固定するので、移動がnextに届くのは、固定を動かすプルリクエストを通したときだけです。perfジョブは、ロックのほかの変更と同じく、そのプルリクエストを測ります。
./build/nginxにnginxをビルドし、./build/nginxでテストする
Section titled “./build/nginxにnginxをビルドし、./build/nginxでテストする”
sh test.sh

test.shは、--with-debug、--with-http_stub_status_module、--with-http_ssl_module、--with-http_auth_request_module、--with-streamを付けて、nginxをconfigureします。これらのオプションは、test.shのNGINX_DEFAULT_OPTとNGINX_CONFIG_OPTにあります。そのため、テストの設定は、これらのモジュールのディレクティブを使えます。CIは、新しいチェックアウトで同じtest.shを実行します。手元のビルドのディレクトリは、nginxを最初にconfigureしたときのオプションを保ちます。Makefileがnginxを再びconfigureするのは、build/nginx-X.Y.Z/objs/Makefileが無いときだけだからです。BUILD_DYNAMIC_MODULEのビルドでは、このファイルはbuild_dynamic/...にあります。これらのオプションを変えたら、そのファイルを消し、ONLY_BUILD_NGX_MRUBYを付けずにtest.shを1回実行してください。そうしないと、nginxは、テストの設定で「unknown directive」のエラーを出して止まります。nginx_versionかBUILD_DYNAMIC_MODULEを変えた後も、ONLY_BUILD_NGX_MRUBYを付けずにtest.shを1回実行してください。そのときtest.shは、新しいバージョンのbuild/nginx-X.Y.Zかbuild_dynamic/という、別のビルドのディレクトリを使います。そのディレクトリにそのファイルが無ければ、そこでnginxをconfigureします。

valgrindの下でnginxを動かすには、環境変数NGINX_RUNNERに値を設定します。

$ NGINX_RUNNER=valgrind sh test.sh

valgrindは、test.shの最後にnginxが終了するときに、レポートを書きます。test.shは、valgrindのエラーを自分の終了ステータスに含めません。test.shが出力するのは、nginxの終了ステータスです。下のコマンドのように--error-exitcode=99を付けると、valgrindがエラーを数えたときの終了ステータスは99になります。CIと同じように実行を確かめるには、valgrindにCIのオプションを渡し、ログのERROR SUMMARYの行を読んでください。詳しい説明はCIのvalgrindにあります。

$ rm -rf build/valgrind && mkdir -p build/valgrind
$ NGINX_RUNNER="valgrind --error-exitcode=99 --leak-check=full --show-leak-kinds=definite,indirect,possible --errors-for-leak-kinds=definite,indirect --suppressions=$PWD/test/valgrind.supp --log-file=$PWD/build/valgrind/valgrind.%p.log" sh test.sh
$ grep 'ERROR SUMMARY' build/valgrind/valgrind.*.log

test.shは、テストのnginxを$NGINX_RUNNER build/nginx/sbin/nginx &でバックグラウンドで起動します。そして、nginxがTCPの接続を受け付けるようになってから、最初のリクエストを送ります。そのために、test.shはtest/t/cases/_wait_for_listen.rbをCRubyで2回実行します。

  • nginxを起動する前に、このスクリプトは、下に挙げるポートで接続を受け付けるプロセスが無くなるまで待ちます。別のプロセスがlistenするポートがあると、起動の後の待ちが、nginxがいなくても成功してしまいます。そのため、NGINX_HEATTIME秒の後もまだ接続を受け付けるポートがあると、実行は、そのポートを挙げて失敗します。

    wait_for_listen: before nginx starts, 1 of 33 ports still accept connections after 60.05 seconds (limit 60.00): 18080; another process listens on them
  • nginxを起動した後に、このスクリプトは、すべてのポートが1回ずつ接続を受け付けるまで、0.1秒ごとに各ポートへ接続します。そして、かかった時間を出力します。時間は、nginxを起動した直後のスクリプトの開始から数えます。

    wait_for_listen: nginx (pid 1234) accepted connections on all 33 ports after 0.21 seconds (limit 60.00)

    nginxのプロセスが先に終わったときと、NGINX_HEATTIME秒が過ぎたときは、スクリプトは失敗し、まだ接続を拒んだポートを挙げます。

    wait_for_listen: nginx (pid 1234) ended after 0.47 seconds, before it accepted connections on 33 of 33 ports: 18080, 18081, ...; see its output above and logs/error.log
    wait_for_listen: nginx (pid 1234) did not accept connections within 60.00 seconds (NGINX_HEATTIME) on 33 of 33 ports: 18080, 18081, ...

対象のポートは、http {}のサーバーのポートです。具体的には、下の「ポート」で説明するコピーのtest/conf/nginx.confとtest/conf/conf.d/*.confにある、すべてのlistenディレクティブのポートを、TEST_SH_PORT_OFFSETでずらしたものです。2026年10月30日の時点で、nextには57個あります。nginxは、設定をすべて読んだ後に、listenするソケットをすべて1つのループで開きます。このループはngx_open_listening_sockets()です。そのため、1つのポートが開いていれば、ほとんどの場合、ほかのポートも開いています。それでも、1つのポートにかかるのは1回の接続で、1ミリ秒を大きく下回ります。すべてのポートを調べると、最初のソケットと最後のソケットの間に隙間が残りません。また、インストールした設定に届かなかったconf.dのフラグメントも見つけられます。test/conf/nginx.stream.confとtest/conf/conf.d/stream/にある、stream {}のポートは対象から外します。streamのサーバーに接続すると、そのサーバーのセッションのコードが動くからです。たとえば、12352のサーバーのNginx::Stream::Async.sleep 3000が動きます。そして、ケースは、そのコードがerror.logに書くものを読みます。nginxは、streamのソケットを同じループで、http {}のソケットの直後に開きます。また、streamのポートに接続する最初のテストは、test/t/ngx_mruby.rbの多くのHTTPのテストが通った後に動きます。Nginx::Server#add_listenerとNginx::Stream.add_listenerが加えるポートも、同じループで開きます。これらのポートは調べません。

NGINX_HEATTIMEは、2つの待ちのそれぞれの上限で、単位は秒です。デフォルトは60で、CIはこの変数を設定しません。NGINX_RUNNER=valgrind NGINX_HEATTIME=10 sh test.shのように設定したコマンドは、最大でその秒数まで待ちます。nginxがlistenすると、実行はすぐに先へ進みます。10秒で失敗するのは、そのときまでにnginxがlistenしていない場合だけです。その場合、その時点で最初のリクエストを送っていたら、そのリクエストは拒否され、Errno::ECONNREFUSEDになっていたはずです。

デフォルトの値は、次の測定に基づきます。2026年10月19日に、masterの03aad7031からビルドしたテストのnginxを、test.shと同じ方法で起動しました。nginxは1.31.6で、ngx_mrubyは静的なモジュールです。環境は、Ubuntu 22.04のコンテナです。コンテナを動かしたaarch64のホストにはCPUが11個あり、ほかのビルドのためにロードアベレージが約15でした。そして、上のスクリプトを使って、すべてのポートが接続を受け付けるまでの時間を測りました。

  • NGINX_RUNNER=execで10回起動すると、各回0.10から0.11秒でした。つまり、すべてのポートが、2巡目の試行で接続を受け付けました。スクリプトは0.1秒ごとに接続を試します。
  • NGINX_RUNNER=valgrindで5回起動すると、2.27から2.61秒でした。valgrindは3.18.1です。

CIでは、valgrindの下のセルが、起動から10秒たってもまだ設定を読んでいました。そのセルは、x86_64のランナーでnginx 1.28.3を動かしていました。test.shがSIGTERMを送ったときのvalgrindのレポートでは、nginxはngx_conf_parse()の中にいました。その実行の報告は、#564にあります。この時間は、次のときに長くなります。CIのランナーの負荷が高いとき、valgrindの下で動かすとき、sanitizerのビルドを使うとき、読む設定が多いときです。valgrindの下では、ここではvalgrindなしの20倍を超える時間がかかりました。sanitizerのビルドの時間は、ここでは測っていません。60秒は、そのCIの実行で見た10秒の6倍で、上のvalgrindの下でいちばん遅かった起動の約23倍です。

上限があると、次のような競合が起きることがあります。

  • 起動が上限より遅いと、nginxがいずれ起動するはずでも、実行は失敗します。遅い環境では、NGINX_HEATTIMEを上げてください。待ちはnginxがlistenした時点で終わるので、上限を上げて時間が余計にかかるのは、nginxが終了せずにハングしたときだけです。nginxが終了したときは、スクリプトがすぐに報告します。
  • listenしているソケットは、まだ動いているハンドラではありません。nginxがlistenすると、カーネルはすぐに接続を受け付けます。テストのnginxはmaster_process offの1つのプロセスで、どの接続を読むよりも前に、init_workerのフックを実行します。その間、最初のリクエストは、nginxが読むまでソケットのbacklogで待ちます。テストのクライアントのmruby-simplehttpはタイムアウトなしで読むので、クライアントも同じく待ちます。
  • nginxは後で、スクリプトが待つ間に試した接続を1つずつ読みます。そして、接続がリクエストの無いまま閉じられていると分かると、その接続を閉じます。これらの接続ではハンドラは動きません。nginxは、これらの接続について、error.logにdebugの行だけを書きます。

test.shは、自分が起動したnginxのプロセスだけを、そのpidで止めます。test.shは、killallやpkillのようにプロセスの名前でシグナルを送りません。そのため、ほかのチェックアウト、ソークテスト、nginx-tests、ほかのユーザーのnginxのプロセスは動き続けます。1台のマシンでtest.shを2つ実行するには、別々のポートが要ります。説明は下の「ポート」にあります。同じポートを使うと、上の「nginxがlistenするまで待つ」にあるように、2つ目の実行は起動の前の待ちで失敗します。

  • test.shは終了するときに、テストのnginxにSIGTERMを送って止め、そのプロセスが終わるまで待ちます。終了するのは、最後のケースの後、失敗の後、SIGHUP、SIGINT、SIGTERMを受けたときです。その後、test.shは、止めるのにかかった時間と、nginxの終了ステータスを出力します。nginxの終了ステータスは、test.shの終了ステータスを変えません。

    test.sh: nginx (pid 374) ended within about 0.1 seconds of the first SIGTERM; SIGTERM sent 1 times
    test.sh: nginx (pid 374) exit status 0

    シェルは、シグナルのtrapを、そのとき動いているコマンドが終わった後にだけ実行します。そのコマンドは、nginxを待つ処理、test/t/ngx_mruby.rb、実行中のケースのファイルなどです。そのため、nginxを止める処理は、そのコマンドが終わったときに始まります。また、対話的でないシェルは、&で実行するコマンドを、SIGINTを無視する状態で起動します。そのため、sh test.sh &はSIGINTでは止まりません。代わりにSIGTERMを送ってください。

  • test.shは、シグナルを送る前に毎回、そのpidがまだこのチェックアウトのbuild/nginx/sbin/nginxを動かしているかを確かめます。ps -ww -o args=で読んだそのpidのコマンドラインにその絶対パスが含まれていれば、test.shは、そのpidがnginxを動かしていると判断します。valgrindの下でも同じです。シェルは、終わったバックグラウンドのプロセスを回収します。そのため、nginxがクラッシュした後は、止める時点で、そのpidが別のプロセスのものになっていることがあります。test.shは、そのようなpidを終わったプロセスとして扱い、シグナルを送りません。

    test.sh: nginx (pid 374) had ended before the stop; no signal sent
  • test.shは、nginxを起動する前にbuild/nginx/logs/nginx.pidを読みます。BUILD_DYNAMIC_MODULEでは、このファイルはbuild_dynamic/...にあります。前の実行がnginxを止める前にkillされると、そのnginxは動き続けます。このファイルは、そのnginxのpidを持っています。上の確認で、そのプロセスがこのチェックアウトのbuild/nginx/sbin/nginxを動かしていれば、test.shは同じ方法でそのプロセスを止めます。ほかのプロセスには触れません。

    test.sh: stopping the nginx (pid 7) that an earlier run left running
    test.sh: logs/nginx.pid names pid 7, which does not run /path/to/build/nginx/sbin/nginx; left running

テストのnginxはmaster_process offの1つのプロセスです。このプロセスは、ngx_single_process_cycle()のループで、イベントを処理した後にだけシグナルを調べます。シグナルハンドラがngx_terminateを設定し、ループはngx_process_events_and_timers()が戻った時点で終わります。シグナルを調べた後、次のepoll_wait()の前にSIGTERMが届くと、そのSIGTERMは待ちを中断しません。タイマーも接続も無いと、epoll_wait()は時間の制限なしに待ちます。そのときnginxは、signal 15 (SIGTERM) receivedをログに書き、動き続けます。マスタープロセスには、この隙間がありません。マスタープロセスは、sigsuspend()でシグナルを待ちます。SIGTERMの後もワーカーがまだ動いていると、マスタープロセスは、終了のコマンドをワーカーに送り直します。送り先は各ワーカーのソケットペアで、ワーカーのイベントループがこのソケットペアを監視しています。この書き込みに失敗したときだけ、マスタープロセスはSIGTERMを送ります。送り直す間隔は50ミリ秒から始まって2倍ずつ延び、間隔が1秒を超えると、マスタープロセスはSIGKILLを送ります。SIGKILLを送るのは、最初のシグナルから約1.6秒後です。この処理はngx_master_process_cycle()にあります。test.shは、1つのプロセスのnginxにシグナルを送り直して、マスタープロセスと同じように止めます。プロセスがまだ動いていれば、test.shは、最初のSIGTERMの1、3、7、15、31秒後にSIGTERMを送り直します。epoll_wait()の間にSIGTERMが届くと、待ちは終わります。test.shがSIGKILLまでマスタープロセスより長く待つのは、テストのnginxがvalgrindの下で動くことがあるからです。valgrindは終了時にリークを調べるので、SIGKILLを送ると、そのレポートが失われます。NGINX_STOPTIME秒の後に、test.shはSIGKILLを送ります。NGINX_STOPTIMEのデフォルトは60です。そして、test.shは次の行を出力します。

test.sh: nginx (pid 374) did not end within 60 seconds (NGINX_STOPTIME) after 6 SIGTERM; sent SIGKILL

その後、test.shは終了ステータス1で終了します。test.shは、これらの時間を、sleep 0.1とpsの繰り返しで数えます。そのため、実際の時間は、出力する時間より少し長くなります。test/t/cases/_second_instance.rbの2つ目のnginxも1つのプロセスで、このnginxはSIGQUITで止め、シグナルを同じように送り直します。

実行がこの隙間に当たる頻度を、2026年10月29日に測りました。テストのnginxは、nextのc9c49023eからビルドしました。nginxは1.31.6で、ngx_mrubyは静的なモジュールです。このnginxを、test.shと同じ方法で起動しました。環境は、CPUが11個あるaarch64のホストで動かした、Ubuntu 22.04のコンテナの中でした。

  • テストのnginxを800回起動し、それぞれに1回SIGTERMを送りました。400回は、1つのリクエストにレスポンスが返った直後に送りました。残りの400回は、3つのリクエストを送ってから0から20ミリ秒後に送りました。nginxは毎回、1回のSIGTERMで終わりました。隙間は、ngx_terminateの確認からepoll_wait()の呼び出しまでです。その間にあるのは、デバッグのログを1行書く処理と、タイマーのツリーを検索する処理だけです。そのため、この規模のループでは、隙間に当たりません。
  • gdbをテストのnginxにアタッチし、nginxがリクエストの接続を閉じるまで待ちました。そして、次のngx_epoll_process_events()の呼び出しでnginxを止め、そこでSIGTERMを届けました。そのとき、イベントもタイマーも残っていませんでした。その呼び出しはtimer=-1でした。nginxはsignal 15 (SIGTERM) received from ..., exitingをログに書き、続けてepoll timer: -1を書きました。そして、10秒後もまだ動いていました。2回目のSIGTERMで、nginxは0.1秒以内に終わりました。これは、#600の7926f72でtest.shを実行したときと同じ状態です。その実行では、nginxはSIGTERMをログに書き、20分間epoll_wait()の中に留まりました。

スイートのポートは、12345から12399までと、18080から18199までの数です。次のポートがこれにあたります。

  • test/conf/にあるlistenディレクティブのポート
  • add_listenerに渡すアドレスのポート
  • test/t/cases/_second_instance.rbが起動する2つ目のnginxが使う、18116と12357
  • test/t/cases/config_hooks.rbが起動するnginxが使う18158
  • test/t/cases/stream_duplicate_hooks.rbのnginx -tが使う12398
  • test/t/cases/_agent_proxy_client.rbが動かすLLMのモックのupstreamが使う、12372と12373
  • test/t/ngx_mruby.rbにあるstreamだけのテストが使う12399
  • テストと、test/html/にあるフックのスクリプトと期待する出力が挙げるポート

TEST_SH_PORT_OFFSETは整数で、デフォルトは0です。この変数を設定すると、これらのポートがすべて同じ数だけずれます。そのため、2つのチェックアウトが、それぞれ別のオフセットで、1台のマシンで同時にtest.shを実行できます。

$ TEST_SH_PORT_OFFSET=1000 sh test.sh # 13345 to 13399 and 19080 to 19199

test.shは、設定をインストールする前にtest/t/cases/_stage.rbを実行します。このスクリプトは、test/t、test/conf、test/html、test/soak/mock_llm.rb、test/soak/http_client.rbをbuild/nginx/harness/test/にコピーします。BUILD_DYNAMIC_MODULEでは、コピー先はbuild_dynamic/...です。コピーにあるすべてのテキストファイルで、2つの範囲の数は、その数にオフセットを足した数になります。対象は5桁で書いた数で、その隣に数字、英字、_が無いものです。

stage: copied 164 files to /path/to/build/nginx/harness/test; 593 port numbers moved by 1000

その後、test.shは、コピーから設定とフックのスクリプトをインストールし、コピーのポートを待ちます。そして、コピーのtest/t/ngx_mruby.rbとケースのファイルを実行します。テストは、suite_pathを使って、コピーのCRubyのヘルパーを実行します。suite_pathはtest/t/cases/_prelude.rbにあり、test/t/ngx_mruby.rbにも自分で使うsuite_pathがあります。suite_pathは、スイートのパスをTEST_SH_STAGE_DIRにつなげます。TEST_SH_STAGE_DIRは、test.shが設定するディレクトリです。ケースをtest.shの外で実行するときのように、この変数が無いと、suite_pathはチェックアウトのパスを返します。テストは今も、チェックアウトの最上位から実行します。設定が、フックのスクリプトを、最上位からの相対パスのbuild/nginx/html/<name>.rbで指すからです。オフセットが0なら、コピーは元のファイルと同じです。

ポートをずらす規則はテキストの置き換えなので、新しいテストでは、次のことを必ず守ってください。

  • ポートは、2つの範囲のどちらかの5桁の数で書いてください。また、これらの範囲の数は、ポートか、テストが同じファイルの集まりにある数と比べる値にだけ使ってください。このような数を18_132のように_を入れて書くと、置き換えの規則では見つからないので、_stage.rbはファイルと行を挙げて失敗します。計算で作るポートは、その5桁の部分が範囲にあるときだけずれます。オフセットが1000なら、18110 + 1は19110 + 1になります。一方、18000 + 110と、文字列から作るポートはそのままです。ポートの数をそのまま書いてください。
  • 範囲の中の数で、ポートでないものが1つあります。test/conf/conf.d/20-filter-connection.confはf.output 12345を出力し、test/t/cases/filter_connection.rbは、ボディを'12345'と、その長さを'5'と比べます。両方のファイルが同じようにずれるので、このケースは今も、Filter#outputがIntegerをto_sで5バイトに変換することを確かめます。
  • オフセットは、すべてのポートを10000から65535の間に保ち、すべての数を5桁のままにする値にしてください。そのようなオフセットは-2345から47336までで、それ以外のオフセットでは_stage.rbが失敗します。また、オフセットは、ポートをほかの実行のポートから離しておく値にしてください。ソークテストのポートは12360から12362で、SOAK_PORT_BASEで決まります。性能の比較のポートは12370から12372で、PERF_PORT_BASEで決まります。nginx-testsのポートは8000から8999です。オフセットが0だと、test.shと性能の比較は、どちらも12372を使います。

2つの実行には、2つのオフセットのほかに、2つのチェックアウトが要ります。1つのビルドのディレクトリには、1つのテストのnginxと、そのログと、そのスイートのコピーが入るからです。2つのオフセットは、2つの実行の範囲を離しておく必要があります。18080から18199の範囲には120個の数があるので、オフセットの差は120以上にします。オフセットの差が5681から5854のとき、一方の実行の12345から12399の範囲は、もう一方の実行の18080から18199の範囲に重なります。差の符号は問いません。5681は18080 - 12399で、5854は18199 - 12345です。そのため、差はこの区間に入らないようにします。オフセットが14568を超えると、18080から18199のポートは、Linuxがデフォルトでエフェメラルポートに使う範囲に入ります。14568は32767 - 18199で、その範囲は32768から60999です。その範囲では、nginxがbindする前に、クライアントのソケットがそのポートを取ることがあります。例のオフセットの0と1000は、3つの条件をすべて満たします。

.github/workflows/test.ymlのbuildのマトリクスは、各セルでtest.shを実行します。どのセルがvalgrindの下でnginxを動かすかは、実行の種類によって違います。

  • buildマトリクスを実行する場合、全セルを動かす場合も標準の4セルだけの場合も、1つのセルがvalgrindの下でnginxを動かします。実行するジョブの選択を参照してください。そのセルは、ngx_mrubyを静的なモジュールとして組み込んだnginx 1.31.8を、--with-openssl-srcなしでビルドします。全マトリクスでは、このセルのジョブの名前はbuild (1.31.8)です。マトリクスは、このセルにVALGRIND_ON_EVERY_RUNを与えます。sanitizerを使わないほかのセルは、NGINX_RUNNER=execでnginxを直接動かします。sanitizerのセルは、AddressSanitizerとUndefinedBehaviorSanitizerを付けてビルドしたnginxを動かします。説明は次の節にあります。

  • test.ymlを入力valgrindを付けて手動で実行すると、sanitizerのセルを除くすべてのセルが、valgrindでnginxを動かします。

    $ gh workflow run test.yml --ref next -f valgrind=true
  • 夜間の実行:.github/workflows/valgrind-nightly.ymlが毎日18:23 UTC、日本時間03:23に、上の項目のvalgrind入力を付けたtest.ymlの実行を起動し、終了を待って、その実行が失敗したら失敗します。GitHubの定期実行はデフォルトブランチのファイルから動くため、#674で入ったmasterのファイルがmasterとnextの実行を起動します。PRでは起動しません。test.ymlかtest/valgrind.suppを変えるPRは、PR自身の実行で、valgrindのセルを1つ動かします。すべてのセルをvalgrindの下で動かすには、次の夜間の実行を待つか、そのブランチでvalgrind-nightly.ymlか、valgrind入力を付けたtest.ymlを「Run workflow」で実行します。この実行は必須チェックのci-okを出さず、ジョブの名前はci-ok (valgrind)です。実行するジョブの選択を参照してください。

valgrindを使っても、セルの時間はあまり増えません。入力valgrindを付けた実行40824932917では、valgrindの下の16のセルで、test.shのうちnginxの起動からtest.sh ... successfulまでの部分に、67から94秒かかりました。同じコミットのプルリクエストの実行40824899601では、nginxを直接動かした15のセルで57から75秒でした。どちらも2026年10月29日の実行です。1つのセルは全体で4から13分かかり、その大部分はOpenSSL、mruby、nginxのビルドの時間です。

valgrindの下のセルは、次のオプションでnginxを動かします。

valgrind --error-exitcode=99 --leak-check=full --show-leak-kinds=definite,indirect,possible --errors-for-leak-kinds=definite,indirect --suppressions=test/valgrind.supp --log-file=$RUNNER_TEMP/valgrind/valgrind.%p.log

test/ci/changes.shがbuildをstandardかfullと判定したら(標準の4セルと同じく、コードかテストを変えるとき)、作者がPRをreadyにする前に、このオプションでvalgrindの下のテストスイートを手元で流します。valgrindのセルは、同じ検査をx86-64のrunnerでもう一度流します。手元では、専用のチェックアウトで流してください。たとえばgit archive HEAD | tar -x -C DIRで作ります。同じチェックアウトでsanitizerのビルドをすると、別のフラグでビルドしたmrubyが残るからです。valgrindにはLinuxが要ります。macOSでは、そのチェックアウトの最上位のディレクトリで、Linuxのコンテナを使って流します。

$ docker run --rm --init -v "$PWD":/work -w /work ubuntu:22.04 sh -c 'apt-get -qq update && DEBIAN_FRONTEND=noninteractive apt-get -qq install -y build-essential rake ruby bison git gperf wget ca-certificates curl zlib1g-dev libpcre3-dev libssl-dev valgrind >/dev/null && mkdir -p build/valgrind && NGINX_RUNNER="valgrind --error-exitcode=99 --leak-check=full --show-leak-kinds=definite,indirect,possible --errors-for-leak-kinds=definite,indirect --suppressions=$PWD/test/valgrind.supp --log-file=$PWD/build/valgrind/valgrind.%p.log" sh test.sh && grep -h "ERROR SUMMARY" build/valgrind/valgrind.*.log | sed "s/^==[0-9]*== //" | sort | uniq -c'

Linuxでは、パッケージを入れた後の、引用符の中のコマンドを流します。最後のコマンドは、ERROR SUMMARYの行を種類ごとに、その行を持つログの数とともに出力します。下のステップ「Check the valgrind reports」と同じく、どの行もエラーの数が0で、少なくとも1つのログにその行がなければなりません。--initを付けると、テストが残したプロセスを、コンテナのinitのプロセスが回収します。

このコマンドと、sanitizerの節のコマンドは、Ubuntu 22.04のOpenSSL(libssl-devのOpenSSL 3.0.2)でビルドします。一方、CIのどのセルも、libssl-devを外し、ソースからビルドしたOpenSSL 3.5.9でビルドします(実行するジョブの選択)。この違いは、CIのセルが受け持ちます。

valgrindは、起きたメモリのエラー1つごとに、エラーを1つ数えます。メモリのエラーは、不正な読み込みか書き込み、初期化していない値による条件分岐かシステムコール、不正な解放か対応しない解放です。また、valgrindは、種類がdefiniteかindirectのloss recordのうち、test/valgrind.suppがsuppressしないもの1つごとに、エラーを1つ数えます。nginxが終了するとき、valgrindは、エラーの数と、異なるスタックの数を、ERROR SUMMARYの行に出力します。valgrindは、異なるスタックをcontextsと呼びます。たとえば、20のリクエストが動かしたハンドラで不正な読み込みがあると、この行は20 errors from 1 contextsになります。--error-exitcode=99を付けると、エラーの数が0でないとき、valgrindは99で終了します。test.shは、nginxを止めたときに、nginxの終了ステータスを出力します。valgrindがエラーを数えた後は、test.sh: nginx (pid 374) exit status 99です。説明はnginxを止めるにあります。しかし、test.shは、この終了ステータスを自分の終了ステータスに含めません。そのため、ステップ「Check the valgrind reports」は、代わりにログを読みます。このステップは各ログを出力します。そして、少なくとも1つのログにERROR SUMMARYがあり、すべてのERROR SUMMARYでエラーの数が0のときだけ通ります。それ以外では失敗します。ERROR SUMMARYが1つも無いセルも失敗します。そのセルでは、valgrindがレポートを書き終えていません。

possibly lostのブロックは、スタックとともに出力されますが、エラーにはなりません。master_process offのテストのnginxが終了する時点で、nginxはcycleのプールを破棄しています。残るのは、ngx_event_process_init()が確保した接続とイベントの配列、ngx_crc32_table_init()のテーブル、まだ開いている接続のプールです。valgrindは、これらのブロックの途中を指すポインタしか見つけないので、これらをpossibly lostとして報告します。その数は、nginxが終了するときに開いている接続によって変わります。2026年10月29日のCIの実行40819115837、40820233191、40821209339では、valgrindの下の16のセルが、それぞれ5ブロックの85,440バイトから8ブロックの86,208バイトまでを報告しました。ngx_mrubyを静的なモジュールとして組み込んだnginx 1.31.6のセルは、この3つの実行で、5、7、7ブロックを報告しました。ngx_mruby、mruby、gemのどれかがブロックを指す最後のポインタを失うと、そのリークはdefinitely lostになります。そのため、そのセルは失敗します。ngx_mrubyがfinalizeしないリクエストや接続は、nginxが終了するまで、そのプールを持ち続けます。valgrindはそのプールをpossibly lostとして報告するので、そのセルは失敗しません。実行40824899601では、終了時にまだ開いていたupstreamの接続のプールが、possibly lostでした。そのプールを確保したときのスタックには、ngx_mrb_post_fiberがあります。このようなリークを調べるのはsoakジョブです。このジョブは、ワーカーの接続、タイマー、ファイルディスクリプタを、サンプルの間で比べます。説明はメモリのソークテストにあります。

test/valgrind.suppがsuppressするのは、nginx自身の確保だけです。各エントリーには、スタックと、コメントに書いた理由があります。今あるエントリーは、ngx_set_environment()の環境変数の配列だけです。この配列は8バイトで、どのセルでもdefinitely lostになります。nginxは、終了時にこの配列をわざと確保したまま残します。この処理はnginx.cのngx_cleanup_environment()にあります。エントリーを加えるのは、レポートのスタックと、そのブロックがngx_mrubyのものでない理由があるときだけです。ngx_mruby、mruby、gemのフレームを持つリークは、suppressしません。

2つのsanitizerの下でテストを実行する

Section titled “2つのsanitizerの下でテストを実行する”

test/ci/changes.shがbuildをstandardかfullと判定したら(標準の4セルと同じく、コードかテストを変えるとき)、作者がPRをreadyにする前に、AddressSanitizerとUndefinedBehaviorSanitizerを有効にする-fsanitize=address,undefinedでビルドしたテストスイートを、手元で流します。CIのマトリクスのsanitizerのセルは、同じフラグでビルドし、x86-64のrunnerでもう一度流します。セルが使うのはOpenSSL 3.5.9です(CIのvalgrindのdockerのコマンドの後の説明を参照してください)。手元では、専用のチェックアウトで流してください。たとえばgit archive HEAD | tar -x -C DIRで作ります。フラグだけを変えても、既存のmrubyのビルドは作り直されないからです。Linuxでは、gccかclangを使い、次のようにします。

$ sudo sysctl -w vm.mmap_rnd_bits=28 # ASan and the kernel's high-entropy ASLR do not mix
$ export NGINX_EXTRA_CC_OPT="-fsanitize=address,undefined -fno-omit-frame-pointer"
$ export NGINX_EXTRA_LD_OPT="-fsanitize=address,undefined"
$ export NGX_MRUBY_CFLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer"
$ export NGX_MRUBY_LDFLAGS="-fsanitize=address,undefined"
$ export ASAN_OPTIONS="detect_leaks=1"
$ export LSAN_OPTIONS="suppressions=$PWD/test/lsan.supp"
$ export UBSAN_OPTIONS="print_stacktrace=1:suppressions=$PWD/test/ubsan.supp"
$ NGINX_RUNNER=exec sh test.sh
$ grep -HnE 'ERROR: (AddressSanitizer|LeakSanitizer)|runtime error:|SUMMARY: (AddressSanitizer|UndefinedBehaviorSanitizer)' $(find build/nginx/logs $(ls -d build/nginx/second_instance 2>/dev/null) -type f -name '*.log')

macOSでは、そのチェックアウトの最上位のディレクトリで、Linuxのコンテナを使って流します。sysctlの行が設定するのは、コンテナが共有するカーネルの値で、コンテナからは変えられません。先に値を読みます。

$ docker run --rm ubuntu:22.04 cat /proc/sys/vm/mmap_rnd_bits

28以下なら、何もしなくて構いません。28より大きければ、そのカーネルが動くところ(コンテナのランタイムのLinuxのVM)で28に設定します。CIのsanitizerのセルも、ビルドの前にsudo sysctl -w vm.mmap_rnd_bits=28を実行します。これより大きいと、ASanのシャドウメモリの配置が失敗するからです。

$ docker run --rm --init -v "$PWD":/work -w /work ubuntu:22.04 sh -c 'apt-get -qq update && DEBIAN_FRONTEND=noninteractive apt-get -qq install -y build-essential rake ruby bison git gperf wget ca-certificates curl zlib1g-dev libpcre3-dev libssl-dev >/dev/null && export NGINX_EXTRA_CC_OPT="-fsanitize=address,undefined -fno-omit-frame-pointer" NGINX_EXTRA_LD_OPT="-fsanitize=address,undefined" NGX_MRUBY_CFLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer" NGX_MRUBY_LDFLAGS="-fsanitize=address,undefined" ASAN_OPTIONS=detect_leaks=1 LSAN_OPTIONS=suppressions=$PWD/test/lsan.supp UBSAN_OPTIONS=print_stacktrace=1:suppressions=$PWD/test/ubsan.supp && NGINX_RUNNER=exec sh test.sh && ! grep -HnE "ERROR: (AddressSanitizer|LeakSanitizer)|runtime error:|SUMMARY: (AddressSanitizer|UndefinedBehaviorSanitizer)" $(find build/nginx/logs $(ls -d build/nginx/second_instance 2>/dev/null) -type f -name "*.log")'

このコマンドは、test.shが通り、grepがレポートを1行も見つけなかったときに0で終わります。コンテナのコンパイラは、sanitizerのセルと同じく、Ubuntu 22.04のgcc 11です。

Linuxのコマンドの最後の行は、CIのそのセルにあるステップ「Check for sanitizer reports」が読むファイルを、同じパターンで読みます。このステップは、パターンに一致する行があると失敗します。レポートは、それを書いたプロセスのstderrに出ます。そのstderrは、次のファイルのうちのどれかです。

ファイル 誰のstderrか
build/nginx/logs/error.log テストのnginxが、ログを開いた後に出すstderr。終了時のリークのレポートも含む
build/nginx/logs/stderr.log テストのクライアントのstderr。クライアントはtest/t/ngx_mruby.rbとケースのファイルで、test.shがそのstderrをこのファイルへリダイレクトする。そのため、テストがstderrをリダイレクトせずに起動するプロセスのstderrも、ここに入る。そのプロセスは、nginx -t、streamだけのテストのnginx -s quit、ログを開く前のnginxである
ほかのbuild/nginx/logs/*.log テストが専用のログを持たせて起動するnginxのプロセスが、そのログを開いた後に出すstderr。streamだけのテストのstream_only.error.logがこれにあたる。このテストは、nginxをdaemon onで実行します。
build/nginx/second_instance/<mode>/*.log test/t/cases/_second_instance.rbが起動する2つ目のnginx。ファイルはerror.log、stderr.log、stdout.log

test.shがケースのファイルより前で止まったときは、build/nginx/second_instance/がありません。そのときステップは、ほかのファイルを読み、このディレクトリが無いことを出力します。このステップは、*.log.bakのファイルを読みません。test.shは、前の実行のログを、同じディレクトリのこれらのファイルに残します。テストのnginxがerror.logを開く前に出したレポートは、次の段落にあるように、端末に出ます。CIでは、scriptのステップの出力に出ます。

NGINX_EXTRA_CC_OPTとNGINX_EXTRA_LD_OPTは、nginxの--with-cc-optと--with-ld-optの後ろに足されます。NGX_MRUBY_CFLAGSとNGX_MRUBY_LDFLAGSは、mrubyのビルドに渡ります。sanitizerとvalgrindを一緒に使わないでください。nginxは、設定を読み込んだ後に、stderrをerror.logへ送ります。そのため、nginxが設定をパースする間に動くコードのレポートは、error.logでなく端末に出ます。そのようなコードは、ディレクティブのハンドラ、スクリプトのコンパイル、mruby_init_codeです。両方を読んでください。test/ubsan.suppには、nginx自身から出るレポートが、それぞれの理由とともに挙げてあります。test/lsan.suppには、LeakSanitizerについて同じものが挙げてあります。nginxは、cycle->connectionsと、ngx_event_process_initで確保する2つのイベントの配列を解放しません。終了時にLeakSanitizerがこれらをレポートするかどうかは、これらの外にまだこれらを指すものがあるかどうかで決まります。そのため、抑制が無いと、nginx自身が確保したメモリのために実行が失敗することがあります。CIが使うgcc 11のランタイムでは、抑制したブロックはほかのものを隠しません。LLVMのランタイムとgcc 12以降は、抑制したブロックをルートとしても扱います。そのため、これらのランタイムでは、これらの配列からしかたどれないブロックまで、レポートされなくなります。

nginx自身のテストスイートnginx-tests

Section titled “nginx自身のテストスイートnginx-tests”

sh test/nginx-tests/run.shは、nginx自身のテストスイートであるnginx-testsをproveで実行し、結果を比べます。実行の対象は、nginx_versionが指定するバージョンのnginxを、次の2とおりの方法でビルドしたものです。

  • ngx_mrubyを入れたnginx:test.shがTEST_SH_SKIP_TESTS=1でビルドします。静的なモジュールで、test.shのconfigureのオプションと-DMRB_GC_STRESSを使い、build/nginxにインストールします。test.shのオプションはテストを実行するにあります。TEST_SH_SKIP_TESTS=1を付けると、test.shはインストールの後で止まります。テストの設定を書かず、nginxをkillせず、nginxを起動もしません。run.shはBUILD_DYNAMIC_MODULEをunsetします。この変数があると、test.shは代わりにbuild_dynamic/へビルドするからです。
  • ngx_mrubyを入れないnginx:同じnginxのソースをbuild_nginxtests/plain/srcにコピーし、test.shがnginxに渡したオプションでconfigureします。そのオプションは、生成したMakefileのNGX_CONFIG_OPTです。ただし、Makefileが足す2つの--add-moduleのオプションは除きます。2つは、ngx_mrubyのオプションとngx_devel_kitのオプションです。サマリーにあるnginx -Vのconfigure argumentsの行が、両方のビルドのオプションを示します。

テストファイルは、それぞれ自分のnginxの設定を書きます。mrubyのディレクティブを持つ設定はありません。ngx_mrubyを入れたビルドでは、nginxを起動するたびとリロードするたびに、ngx_mrubyのmrb_stateができます。nginxは、設定を読む間に、http {}ブロックとstream {}ブロックのそれぞれにこのmrb_stateを作ります。mrb_stateを作るのはmrb_openで、MRB_GC_STRESSの下で動きます。mrb_openは、mrubyのコアと同梱のgemに含まれるRubyのコードを実行します。ngx_mrubyは、post-read、server rewrite、rewrite、access、logのフェーズにハンドラを加えます。各HTTPリクエストは、そのうちリクエストが到達したフェーズのハンドラを通ります。returnやrewriteは、後のフェーズより前にリクエストを終えることがあります。リクエストは、contentのフェーズのngx_mrubyのハンドラも通ります。ただし、locationが自分のcontentハンドラを持つときは通りません。proxy_passなどがそのようなハンドラで、nginxは、そのフェーズのハンドラの代わりにそれを実行します。コードを設定していないとき、これらのハンドラはdeclineします。各streamのセッションは、ngx_mrubyのaccessのフェーズのハンドラを通ります。ngx_mrubyのヘッダフィルタとボディフィルタは、ディレクティブが求めたときにだけ加わります。また、設定に書くハンドラ、フィルタ、initのコードは、1つも動きません。そのため、ngx_mrubyを入れると失敗し、入れないと通るテストファイルは、何も設定していなくてもこのモジュールがnginxの挙動を変えることを示しています。

nginx-testsには、リリースもタグもありません。run.shは、NGINX_TESTS_COMMITのコミットec44bc80c4bfをfetchします。これは2026年10月19日のmasterの先頭のコミットで、コミットした日は2026年10月16日です。こうすると、nginx-testsにテストが加わっても、結果が変わるのは、このリポジトリを変えたときだけになります。固定したコミットは、そのためだけのプルリクエストで動かします。そのプルリクエストは、動かす前と後のサマリーを引用します。nginx_versionを変えたときは、固定したコミットを動かす理由になります。nginx-testsの新しいテストファイルは、新しいバージョンのnginxの機能をテストし、古いバージョンでは自分をスキップするからです。

run.shには、Linuxと、root以外のユーザーと、test.shが必要とするものが要ります。root以外のユーザーが要る理由は2つあります。テストファイルは、そのユーザーだけが読めるディレクトリに設定を書きます。また、rootが起動したnginxは、ワーカーをnobodyで動かします。テストファイルが必要とするperlのモジュールやプログラムが無いとき、そのテストファイルは失敗でなくスキップになります。Ubuntu 22.04では、ジョブは次のものをインストールします。

$ sudo apt-get install rake bison git gperf zlib1g-dev libpcre3-dev libssl-dev ruby \
libio-socket-ssl-perl libnet-ssleay-perl libfcgi-perl libscgi-perl \
libcache-memcached-perl libcache-memcached-fast-perl libprotocol-websocket-perl memcached
$ sh test/nginx-tests/self-test.sh
$ sh test/nginx-tests/run.sh

macOSでは、ツリーのコピーを同じパスにマウントしたLinuxのコンテナで実行します。

D=$HOME/ngx_mruby-nginx-tests # any directory outside the checkout
rm -rf "$D" && mkdir -p "$D" && git archive HEAD | tar -x -C "$D"
docker run --rm -v "$D:$D" -w "$D" ubuntu:22.04 sh -c 'apt-get -qq update && DEBIAN_FRONTEND=noninteractive apt-get -qq install -y build-essential perl rake ruby bison git gperf wget ca-certificates openssl zlib1g-dev libpcre3-dev libssl-dev libio-socket-ssl-perl libnet-ssleay-perl libfcgi-perl libscgi-perl libcache-memcached-perl libcache-memcached-fast-perl libprotocol-websocket-perl memcached >/dev/null && useradd -m nt && chown -R nt "$PWD" && su nt -c "NGX_MRUBY_COMMIT='"$(git rev-parse HEAD)"' sh test/nginx-tests/run.sh"'

テストファイルは、8000から8999のポートのうち自分がロックしたポートで、nginxを起動します。そのため、テストファイルは並列に動きます。並列の数はNGINX_TESTS_JOBSで決まり、デフォルトはCPUの数です。テストファイルはtest.shのポートを使いません。また、test.shが止めるのは、自分が起動したnginxだけです。詳しい説明は上の「nginxを止める」にあります。

環境変数は次のとおりです。NGINX_TESTS_OUTは出力のディレクトリで、デフォルトはbuild_nginxtestsです。NGINX_TESTS_SRCは、固定したコミットのnginx-testsのチェックアウトです。指定すると、run.shはfetchの代わりにそれを使います。たとえば、github.comに接続できないときに使います。NGINX_TESTS_JOBSは並列の数です。NGINX_TESTS_FILESは、すべてのテストファイルの代わりに実行するテストファイルで、たとえばNGINX_TESTS_FILES='access.t proxy.t'と指定します。NGX_MRUBY_COMMITは、サマリーに書くngx_mrubyのコミットです。デフォルトは、GitHub ActionsではGITHUB_SHAで、それ以外ではチェックアウトのHEADです。run.shに足した引数はtest.shに渡り、そこから./configureに渡ります。nginx-tests自身の変数も使えます。失敗したファイルのエラーログを読むには、そのファイルだけを、TEST_NGINX_LEAVE=1かTEST_NGINX_CATLOG=1を付けて実行し直してください。TEST_NGINX_LEAVE=1は一時ディレクトリを残し、TEST_NGINX_CATLOG=1はログの内容を出力します。

run.shは、次のファイルをbuild_nginxtests/に出力します。

ファイル 内容
summary.md 両方のビルドの件数、ビルドごとの失敗したファイル、スキップの理由、両方のビルドのconfigureの引数
only-mruby.txt, both.txt, only-plain.txt 失敗したテストファイルの一覧。順に、ngx_mrubyを入れたビルドでだけ失敗したもの、両方のビルドで失敗したもの、ngx_mrubyを入れないビルドでだけ失敗したもの
mruby/, plain/ ビルドごとのprove.log、results.tsv、nginx-V.txt。prove.logはproveの出力。results.tsvはテストファイルごとに1つのレコードを持ち、レコードはファイル、passedかfailedかskipped、スキップの理由か失敗したサブテストの3つから成る

test/nginx-tests/results.plはprove.logを読みます。proveの「Test Summary Report」にあるファイルのエントリーに、失敗したサブテスト、0以外のwait status、パースのエラーのどれかがあると、そのファイルは失敗です。パースのエラーは、planが無いか、planが間違っている場合です。エントリーにあるのが、通ったTODOのサブテストだけなら、そのファイルは通ったことになります。ログがproveの完全な実行でないとき、results.plは止まります。test/nginx-tests/compare.plは、一覧とサマリーを書きます。sh test/nginx-tests/self-test.shは、この2つのスクリプトを、test/nginx-tests/self-test/にある小さなテストファイルのproveの出力で確かめます。これらのテストファイルは、わざと通るか、失敗するか、スキップするか、planを壊します。その動きは2つのビルドで違い、組み合わせは、self-test.shの先頭のテーブルに書いてあります。

両方のビルドをテストし、その結果を読めたとき、run.shは0で終わります。テストファイルが失敗したときも同じです。ビルド、fetch、prove自身のどれかが失敗したときと、ログが完全な実行でないときは、run.shは0以外のステータスで終わります。

.github/workflows/nginx-tests.ymlは、ubuntu-22.04でセルフテストとrun.shを実行します。このワークフローが動くのは、nextへのPRがnginxのバイナリの入力、test.sh、test/nginx-tests/、ワークフローのどれかを変えるときと、「Run workflow」のときです。バイナリの入力は、性能の比較のCIで実行するに挙げてあります。Draftでは動かず、readyにすると始まります。nextへのpushでは動きません。マージの記録には、PRのマージコミットでの実行を使うからです。ジョブのサマリーはsummary.mdで、ngx_mrubyを入れたビルドでだけ失敗するファイルには、warningのアノテーションが付きます。アーティファクトnginx-testsには、上の出力のうち、nginxのソースのコピーを除いたものが入ります。

このジョブは結果を記録します。ゲートにはなりません。ジョブが失敗するのは、セルフテスト、ビルド、fetch、prove自身のどれかが失敗したときと、summary.mdが無いときだけです。テストファイルの結果では、ジョブは失敗しません。また、ci-okはこのジョブを必要としません。詳しくは必須のステータスチェックにあります。docs/proposals/v3-plan.mdのPillar Eに従い、結果が安定したらこのジョブを必須にします。

2026年10月19日に、2つのマシンで測りました。どちらのマシンでも、nginx-testsはec44bc80c4bfで、nginx 1.31.6、gcc 11.4.0、OpenSSL 3.0.2、perl 5.34を使いました。

  • CI:ubuntu-22.04で動いたrun 39241352263のnginx-testsジョブです。x86_64で、テストファイルを4つずつ並列に実行しました。対象は、#602の093e47dを7b5a0c4のnextへマージしたマージコミット401cf56です。
  • macOSの上のubuntu:22.04のDockerのコンテナ:aarch64で、テストファイルを11ずつ並列に実行しました。コマンドはnginx-testsを実行するのもので、対象は093e47dです。
マシン ビルド テストファイル 通った 失敗した スキップした 実行したサブテスト
CI、x86_64 ngx_mrubyを入れたnginx 511 302 0 209 3994
CI、x86_64 ngx_mrubyを入れないnginx 511 302 0 209 3994
コンテナ、aarch64 ngx_mrubyを入れたnginx 511 301 0 210 3991
コンテナ、aarch64 ngx_mrubyを入れないnginx 511 301 0 210 3991
  • ngx_mrubyを入れると失敗し、入れないと通るテストファイルは、ngx_mrubyがnginxに入っているために失敗するファイルです。どちらのマシンでも、そのようなファイルはありませんでした。
  • ngx_mrubyを入れないnginxでも失敗するテストファイルも、どちらのマシンでもありませんでした。

2つのマシンの結果は、ssl_ktls.tの1ファイルだけが違います。このファイルは、ランナーでは通り、コンテナではスキップになります。コンテナのカーネルにはkTLSが無く、スキップの理由は「no Linux KTLS」です。どちらのマシンでも、両方のビルドで同じファイルが、同じ理由でスキップになりました。ランナーでスキップになった209ファイルのうち189ファイルは、test.shがビルドしないモジュールがnginxに無いために、スキップになりました。内訳は、http_v2が59ファイル、stream_sslが25、http_v3が23、mailが16、realipが11、subが9で、ほかの18のモジュールがそれぞれ1から6ファイルです。残りの20ファイルは、マシンかnginx-testsの条件で、スキップになりました。スキップになった条件は次のとおりです。

  • インストールしていないプログラムかperlのモジュール。uwsgiが4ファイルで、ほかにGD、Win32API::File、新しいバージョンのIO::Socket::SSLを要するファイルがあります
  • OpenSSL 3.5
  • root。3ファイルです
  • ワイルドカードのアドレス。2ファイルです
  • Windows。1ファイルです
  • nginx-testsがTEST_NGINX_UNSAFEのときだけ実行するか、まったく実行しない6ファイル。孤立したプロセスグループ、長いテスト、OpenSSLのエンジンかプロバイダの鍵を使うものです

各実行のサマリーは、すべての理由をその件数とともに挙げます。ランナーでは、ジョブは約8分かかりました。2つのビルドに2分37秒、各ビルドのproveに2分37秒です。

この結果が確かめるのは、ngx_mrubyが入っていて、ngx_mrubyに何も設定していないnginxです。次の2種類の実行を加えると、もっと広い範囲を確かめられます。どちらもまだ用意していません。1つは、スキップしたファイルが必要とするモジュールを入れたビルドです。モジュールは、--with-http_v2_module、--with-http_v3_module、--with-stream_ssl_module、--with-mailと、上に挙げたほかのモジュールです。もう1つは、ngx_mrubyのハンドラかフィルタが、スイートのリクエストに対してRubyのコードを動かすテストの実行です。docs/proposals/v3-plan.mdのPillar Eには、その手段としてTEST_NGINX_GLOBALS_HTTPが書いてあります。docs/HANDOFF.mdのキューには、両方が載っています。

テストで使うLLMのモックのupstream

Section titled “テストで使うLLMのモックのupstream”

test/soak/mock_llm.rbは、HTTP/1.1のサーバです。POST /v1/messagesにはAnthropic Messages APIと同じように答え、POST /v1/responsesにはOpenAI Responses APIと同じように答えます。動かすにはCRuby 3.0以降が要ります。エージェントプロキシは、LLMのAPIの前に置いた、ngx_mrubyを入れたnginxです。このモックは、次の3つの場所で、エージェントプロキシのupstreamの代わりを務めます。

  • メモリのソークテストのagent_*のシナリオと、性能の比較のproxy_*、responses_stream_plain_*、auth、route_json_*のシナリオ:ソークテストと性能の比較は、シナリオごとに、モックを別のプロセスとして、ポートのベース+2で起動します。ポートは12362と12372です。オプションはシナリオのもので、test/soak/scenarios.rbのmockにあります。
  • ケースのtest/t/cases/agent_proxy.rb:そのヘルパーのtest/t/cases/_agent_proxy_client.rbは、リクエストを送る間、モックを自分のプロセスの中で12372と12373で動かします。ケースは、現在のビルドで動くエージェントプロキシのレシピを、test/conf/conf.d/60-agent-proxy.confのサーバで確かめます。このサーバのポートは18132です。レシピは5つあります。1つ目はserver rewriteハンドラで、既知でないクライアントのキーを401で拒否し、serverのレベルのerror_pageがJSONのボディを付けます。そのリクエストはupstreamに届きません。2つ目はaccessハンドラで、JSONのボディのmodelで2つのupstreamブロックの1つを選び、クライアントの認証情報を差し替えます。3つ目は、クライアントのキーごとのlimit_connです。拒否は、limit_conn_status 460とerror_pageを通して、retry-afterの付いたJSONの429になります。クライアントがストリームを閉じた後は、スロットがまた空きます。4つ目は、upstreamの529を変えずにクライアントへ渡すことです。5つ目は、$upstream_statusを読むlogハンドラです。同じレシピは、location = /v1/responsesでも、Responses APIのリクエストで動きます。そこでは、プロキシ自身が返す401と429のボディはResponses APIのエラーの形式を使い、upstreamのエラーは503と429です。ケースは、50個のデルタのストリームが1バイトも違わずに届くことも確かめます。確かめるストリームは、Messages APIのストリーム1つと、ストリームを終えるイベントの種類ごとのResponses APIのストリーム1つずつです。
$ ruby test/soak/mock_llm.rb --port 12362 --events 50 --hold-after 10
オプション デフォルト 意味
--port PORT 必須 127.0.0.1:PORTで待ち受ける。ポートを増やすには、このオプションを繰り返す。どのポートも同じように答える
--events N 50 ストリームが持つ、テキストのデルタのイベントの数。Messages APIではcontent_block_delta、Responses APIではresponse.output_text.delta
--delta-text TEXT hello テキストのデルタの各イベントが運ぶテキストの内容
--hold-after K 無効 ストリームの最初のK個のイベントを書き、その後は相手が接続を閉じるまで何も書かずに待つ
--reset-after K 無効 ストリームの最初のK個のイベントを書き、その後に接続をRSTでリセットする
--status CODE 無効 すべてのリクエストに、イベントより前に、このステータスで答える。ボディには、そのAPIの形式のエラーを入れる。/v1/messagesではAnthropicのエラーで、529にはoverloaded_error、503にはapi_error。/v1/responsesではOpenAIのエラーで、429にはrate_limit_error、503にはservice_unavailable_error、ほかの4xxにはinvalid_request_error、ほかの5xxにはserver_error
--delay-ms MS 0 2つのイベントの間にMSミリ秒ずつ待つ
--one-write 無効 ステータス行とヘッダと、ストリームの全体を、1回のwriteで書く
--terminal NAME completed Responses APIのストリームを終えるイベント。completed、incomplete、failedのどれか

リクエストは、ヘッダで、そのリクエストだけのオプションを上書きできます。ヘッダは、x-mock-events、x-mock-hold-after、x-mock-reset-after、x-mock-status、x-mock-delay-msと、x-mock-terminalです。前の5つの値は0以上の数で、x-mock-terminalの値はcompleted、incomplete、failedのどれかです。x-mock-hold-after、x-mock-reset-after、x-mock-statusはoffも受け付けます。offは、それぞれ--hold-after、--reset-after、--statusの動作を無効にします。x-mock-eventsとx-mock-delay-msはoffを受け付けません。それ以外の値には、そのヘッダの名前を書いた400で答えます。エラーはinvalid_request_errorです。nginxは、設定がヘッダを落とすとき以外は、これらのヘッダを転送します。ruby test/soak/mock_llm_test.rbは、これらの決まりと下に書く答えを、自分のプロセスの中のモックで確かめます。nginxは使わず、約1秒で終わります。test/soak/run.shは、ソークテストの前に、これを実行します。

POST /v1/messagesへの答え方は次のとおりです。

  • "stream": trueを持つJSONのボディ:200で、text/event-streamとchunkedで答えます。イベントは、usageを持つmessage_start、content_block_start、テキストを持つN個のcontent_block_delta、content_block_stop、usageを持つmessage_delta、message_stopで、合わせてN + 5個です。
  • それ以外のJSONのオブジェクト:メッセージをJSONにして、Content-Lengthを付けた200のレスポンスで答えます。

POST /v1/responsesには、openai/openai-openapiのopenapi.yamlにあるイベントの型とフィールドで答えます。読んだのはコミット33248a6のファイルで、日付は2026年10月19日です。

  • "stream": trueを持つJSONのボディ:200で、text/event-streamとchunkedで答えます。各イベントには、型を書いたevent:の行と、data:の行があります。data:の行のJSONは、同じtypeと、0から数えるsequence_numberを持ちます。イベントは、まずresponse.createdとresponse.in_progressです。この2つは、ステータスがin_progressでusageがnullのResponseオブジェクトを持ちます。続いて、response.output_item.added、response.content_part.added、テキストを持つN個のresponse.output_text.deltaが来ます。ストリームを終えるイベントがcompletedかincompleteなら、その後にresponse.output_text.done、response.content_part.done、response.output_item.doneと、response.completedかresponse.incompleteが続きます。この最後のイベントは、出力のテキストとusageを含むResponseオブジェクトの全体を持ちます。usageのフィールドは、input_tokens、input_tokens_details、output_tokens、output_tokens_details、total_tokensです。イベントは合わせてN + 8個です。failedなら、デルタの後にresponse.failedが続きます。このイベントは、ステータスがfailedで、errorを持ち、usageがnullです。イベントは合わせてN + 5個です。
  • それ以外のJSONのオブジェクト:ResponseオブジェクトをJSONにして200で答えます。ステータスはcompletedで、Content-Lengthを付けます。

どちらのパスでも、--one-writeが無ければ、各イベントは1回のwriteで書く1つのチャンクです。ステータス行とヘッダは最初のイベントと一緒に書き、最後のチャンクは最後のイベントと一緒に書きます。JSONのオブジェクトでないボディには400で答え、レスポンスのボディには、そのAPIのエラーの形式でinvalid_request_errorを入れます。ほかのパスには、Anthropicの形式の404で答えます。GET /_mock/statsには、カウンタをJSONにして答えます。カウンタは下にあります。

答えは、リクエストとオプションだけで決まります。モデルは、リクエストのmodelです。input_tokensは、リクエストのボディのバイト数を4で割り、切り上げた数です。output_tokensはNで、ストリームを使わない答えでは6です。Responseのidと時刻は固定です。--delay-msのほかにsleepはありません。ドライバとケースは、同じコードで期待するレスポンスを計算し、1バイトずつ比べます。そのコードはMockLLM.stream_bodyとMockLLM.answer_bodyです。レスポンスには、答えたポートを示すx-mock-portも付きます。リクエストに認証情報のヘッダがあったときは、届いた値をx-mock-authorizationとx-mock-x-api-keyに入れて返します。そのため、テストは、プロキシがモックへどの認証情報を送ったのかを、確かめられます。

モックは、アイドルのkeep-aliveの接続を自分から閉じません。モックが接続を閉じるのは、リクエストにConnection: closeがあるとき、相手が接続を閉じたとき、--hold-afterと--reset-afterのときだけです。Connection: closeを持つリクエストには、答えにもConnection: closeを付けます。GET /_mock/statsのカウンタは次のとおりです。

カウンタ 意味
connections_open いま開いている接続の数。尋ねている接続は数えない
connections 受け付けた接続の数
requests 読んだPOST /v1/messagesとPOST /v1/responsesのリクエストの数
completed 最後まで書いた答えの数。エラーのステータスで答えたものも含む
held いま--hold-afterで待たせているストリームの本数
held_closed --hold-afterで待っている間に、相手が閉じたストリームの数
reset --reset-afterでリセットした接続数
write_failed 相手が接続を閉じていたために、途中で切れた答えの数

nginxのワーカーは、何日もリクエストを処理し続けます。終わったリクエストがワーカーに何かを残すと、それはワーカーが動いている間ずっと積み上がります。残るものには、GCのルート、生きているmrubyのオブジェクト、タイマー、ファイルディスクリプタ、接続、ヒープのメモリがあります。ソークテストは、シナリオごとに1つのlocationへ多数のリクエストを送り、これらのどれも増えないことを確かめます。test/ci/changes.shがsoakをtrueにするときは、作者がPRをreadyにする前に、このテストを手元で流します。流し方は実行するにあります。CIのsoakジョブは、同じテストをx86-64のrunnerでもう一度流します。

test/soak/soak.rbは、シナリオごとにnginxを起動します。設定はmaster_process onで、ワーカーは1つです。soak.rbは、まず1つのレスポンスを確かめ、SOAK_WARMUP個のリクエストを送ります。続いて、SOAK_N個のリクエストを、SOAK_N / 3個ずつ3つのウィンドウに分けて送ります。サンプルは、ウォームアップの後と各ウィンドウの後に1回ずつ、合わせて4回取ります。各サンプルの前に、soak.rbは自分の接続をすべて閉じます。そして、stub_statusが示す開いた接続が、サンプルを求める接続だけになるまで待ちます。待つのは最大5秒です。サンプルは次のカラムからなります。

カラム 取得元 合格の条件
gc_live Nginx::Debug.gcの後に読んだNginx::Debug.stats。このメソッドの説明は下の「ソークのビルドとNginx::Debug」の節に書いてある どのサンプルでも同じ
gc_root gc_liveと同じ どのサンプルでも同じ
fibers gc_rootと同じHashのgc_root_fibers どのサンプルでも同じ
arena gc_rootと同じHashのgc_arena_idx どのサンプルでも同じ
timers 同じHashのtimers すべてのサンプルで0
fd /proc/<worker>/fdにあるエントリーの数 fdからupを引いた値が、すべてのサンプルで同じ
up モックのLLMのconnections_open。モックを使わないシナリオでは、常に0 SOAK_CONCURRENCY以下。abortとcutのシナリオでは、いつも0になる
active stub_statusのActive connections すべてのサンプルで1
rss_kb /proc/<worker>/statusにあるVmRSS 最後のサンプルからその前のサンプルを引いた値がSOAK_RSS_STEP_KB以下。最後のサンプルから最初のサンプルを引いた差の値がSOAK_RSS_TOTAL_KB以下に収まる

どのサンプルの時点でも、ワーカーは同じ状態にあります。それより前に送ったリクエストはすべて終わっていて、動いているリクエストは/debug/stats自身だけです。そのため、カウンタの値は、それまでに動いたリクエストの数によって変わりません。

  • gc_liveは、生きているmrubyのオブジェクトの数です。Nginx::Debug.gcは最初にフルGCを実行するので、終わったリクエストのオブジェクトは既に解放されています。
  • gc_rootは、ngx_mrubyがGCから守っているオブジェクトの数で、fibersはそのうちのfiberの数です。数えるのは、各mrb_stateのholderと、holderに入れたオブジェクトです。holderはmrb_stateを開くときに1回だけ登録し、その実装はsrc/http/ngx_http_mruby_gc_roots.hにあります。各ディレクティブのコンパイルしたコードは、mrb_stateを閉じるまで、holderのスロットに残ります。cacheを付けないハンドラのファイルは、実行ごとのコードを同じスロットに入れます(src/common/ngx_mruby_code.h)。ハンドラは、始まるときにholderへfiberを入れ、終わるときにそのスロットを空けます。そのため、サンプルに残るのは、holder、コンパイルしたコード、/debug/statsのfiberです。ngx_mrubyは自分の呼び出しを数えるので、このチェックは、mrubyがGCのルートをどう持つかに左右されません。数え方は、下の「ソークのビルドとNginx::Debug」にあります。
  • arenaは、/debug/statsが動いている間のmrubyのGCアリーナの深さです。アリーナを保存するコードパスは、どれもアリーナを元に戻します。
  • timersは、Nginx::Async.sleepのタイマーのうち、発火も削除もされていないものの数です。待っているリクエストが無いので、この数は0です。
  • fdは、/debug/statsの接続が閉じた後に読みます。そのため、fdが数えるのは、listenしているソケット、ログのファイル、nginx自身のディスクリプタです。activeは/statusのリクエストから読みます。その時点で開いている接続は、このリクエストの接続だけです。リクエストがソケットやファイルを開いたままにすると、1つにつき、これらの値が1増えます。
  • upは、モックのLLMで開いている接続の数です。nginxのupstreamは、これらの接続を次のリクエストのために保ちます。その数は、それまでで最も混んだ時点で同時に使われていたupstreamの接続の数です。そのため、後のウィンドウがたまたまそれより混むと、upは1増えることがあります。また、これらの接続は、それぞれfdにも数えられます。そこでソークテストは、サンプルの間でfdからupを引いた値を比べ、upの上限をクライアントの接続の数で押さえます。abortとcutのシナリオでは、正常に終わるレスポンスが無いので、nginxはupstreamの接続を保ちません。ソークテストはupが0になるまで最大5秒待ち、0にならなければそのサンプルを失敗にします。

VmRSSは正確な値ではないので、ソークテストは比べずに上限で押さえます。ソークのビルドは、各サンプルの前のフルGCでmalloc_trim(0)を呼びます。この関数は、Cのヒープの空きページを返します。説明は下の節にあります。この呼び出しが無いと、正しいビルドでも、サンプルの間でVmRSSが増える向きにも減る向きにも最大で約1 MB動きました。どれだけ動くかは、アロケータがたまたまどこに空きメモリを残したかによって決まりました。

test/soak/nginx.confのシナリオは、Nginx::Debug自身も1回確かめます。確かめるのは、最初のレスポンスの後、ウォームアップの前です。シナリオは/debug/checkにリクエストを送ります。そのコードは、まずNginx::Debug.gcを実行し、Nginx::Debug.statsを読みます。次に、1000回のループの各回で、どこからも参照されないStringを2つ作ります。最後に、2回目のNginx::Debug.gcの前と後に、gc_liveをもう一度読みます。シナリオは、次のすべてが成り立たないと失敗します。

  • Nginx::Debug.statsが、下の「ソークのビルドとNginx::Debug」が挙げるキーを持ち、値がすべてIntegerであること。gc_root_mrubyとgc_root_fibers_mrubyは、両方あるか、両方無いかのどちらかであること
  • Nginx::Debug.gcがnilを必ず返すこと
  • Stringを作ると、gc_liveが1000以上増えること
  • 2回目のフルGCでgc_liveが1000以上減り、最初に読んだ値に10を足した値以下になること

コードは、GC.disableとGC.enableの間でStringを作ります。フルGCの後でも、生きているオブジェクトは約1000個あります。そのため、こうしないと、mrubyのインクリメンタルGCがループの途中で始まります。そうすると、2回目に読む前に、Stringの大部分が解放されます。このチェックが無いと、キーが欠けたNginx::Debug.statsや、何も解放しないNginx::Debug.gcでも、すべてのサンプルが同じ値になり、ソークテストは通ってしまいます。

シナリオは、次のどれかが起きたときにも失敗します。

  • レスポンスが期待どおりでないとき
  • SIGQUITを受けてから30秒以内にnginxが終了しないとき
  • nginxのerror.logかstderrに、open socket、[error]、[alert]、[crit]、[emerg]、runtime error:、Sanitizerのどれかが含まれるとき

ngx_mrubyは、ハンドラで発生した例外をerrorのレベルでログに書きます。また、disconnectのクライアントは最初のレスポンスしか読みません。そのため、そのクライアントの後のリクエストで起きた例外は、ログにだけ現れます。シナリオは、nginxが意図してerrorのレベルで書く行を挙げられます。挙げる場所はtest/soak/scenarios.rbのallowed_logで、挙げた行はチェックの前に除かれます。どれかのシナリオが1つでも失敗すると、終了ステータスは1になります。

デフォルトのシナリオは次のとおりです。それぞれがtest/soak/nginx.confの1つのlocationです。

シナリオ ハンドラ クライアント
hello Nginx.rputs keep-alive
headers リクエストヘッダを3つ読み、レスポンスヘッダを2つ設定する keep-alive
var Nginx::Varで変数を2つ読み、1つを設定する keep-alive
filter mruby_output_body_filter_codeが、return 200のボディを書き換える keep-alive
sleep Nginx::Async.sleep 1の後、レスポンスのボディを出力する keep-alive
sub_request Nginx::Async::HTTP.sub_requestで、あるlocationにサブリクエストを送る。そのlocationは、2つ目のserverの静的なlocationへプロキシする。2つ目のserverのポートは、ベースのポートに1を足した番号を使う keep-alive
file スクリプトのファイルを指定し、cacheを付けたmruby_content_handler keep-alive
disconnect Nginx::Async.sleep 50の後、レスポンスのボディを出力する 接続ごとに1つのリクエストを送り、レスポンスを読まずに、その接続をすぐ閉じる

加えて、エージェントプロキシのシナリオが4つあります。どれも、モックのLLMの前に置いたtest/soak/nginx.agent.confの/v1/routeか/v1/responses/routeを使います。説明は下の「エージェントプロキシのシナリオ」にあります。

シナリオ モック クライアント
agent_stream 50個のcontent_block_deltaのイベントを持つストリーム。イベントは全部で55個 keep-alive。すべてのストリームが1バイトも違わないことを比べる
agent_client_abort 10個のイベントを書き、nginxがその接続を閉じるまでストリームの送信を止めておく 接続ごとに1つのリクエスト。レスポンスのヘッダと最初の3つのイベントを読み、それを確かめてから、接続を閉じる
agent_upstream_reset 10個のイベントを書き、その接続をリセットする 接続ごとに1つのリクエスト。EOFまで読み、ボディがちょうど10個のイベントで、chunkedのボディの終わりが無いことを確かめる
agent_responses_stream 50個のresponse.output_text.deltaのイベントとresponse.completedを持つ、Responsesのストリーム。イベントは全部で58個。/v1/responses/routeを通して中継する keep-alive。すべてのストリームが1バイトも違わないことを比べる

keep-aliveのクライアントは、SOAK_CONCURRENCY個の接続です。各接続は、レスポンスを読んでから次のリクエストを送ります。soak.rbは、すべてのレスポンスを確かめます。disconnectのクライアントは、スレッドごとに、100 msごとに16個のリクエストをまとめて送ります。こうすると、同時に開いているリクエストの数が、どのウィンドウでも同じになります。agent_client_abortのクライアントのモードは:abortで、agent_upstream_resetのクライアントのモードは:cutです。どちらのクライアントもSOAK_CONCURRENCY個のスレッドで、各スレッドは接続ごとに1つのリクエストを送り、届いたものを確かめます。

エージェントプロキシのシナリオ

Section titled “エージェントプロキシのシナリオ”

test/soak/nginx.agent.confは、ソークテストと性能の比較のための、独立した設定です。この設定には、mrubyのフィルタのディレクティブがありません。http {}ブロックのどこかにボディフィルタのディレクティブが1つあるとします。すると、そのブロックのすべてのレスポンスに、ngx_mrubyのボディフィルタが入ります。test/soak/nginx.confのfilterのシナリオでは、そうなっています。その場合、ストリームのようなchunkedのレスポンスは、どれもそのフィルタを通り、そのたびにnoticeのログが出ます。この設定のerror_logのレベルはwarnです。プロキシの設定は、エージェントプロキシの設定と同じです。proxy_buffering off、proxy_buffer_size 4k、proxy_http_version 1.1を指定し、クライアントのAuthorizationを、ハンドラが選んだ認証情報に置き換えます。upstreamブロックには、keepalive 32、keepalive_requests 1000000、keepalive_timeout 1hを指定します。こうすると、シナリオの間、nginxもモックへのアイドルの接続を閉じません。ハンドラはtest/soak/handlers/にあります。

  • agent_init.rb:mruby_init_workerのハンドラです。クライアントのキー、認証情報、モデルのテーブルを用意します。
  • agent_auth.rb:server auth.agent.testのserver rewriteハンドラです。Authorizationかx-api-keyからクライアントのキーを探し、3つの変数を設定します。キーを探すのに、Hashを合わせて2回引きます。
  • agent_route.rb:/v1/routeと/v1/responses/routeのaccessハンドラで、そのlocationにはmruby_enable_read_request_body onを指定しています。JSON.parse(r.body)["model"]を実行し、Hashを1回引いて、proxy_pass http://$agent_backendのための$agent_backendの値を設定します。

/v1/plainと/v1/routeは、モックの/v1/messagesへプロキシします。/v1/responses/plainと/v1/responses/routeは、モックの/v1/responsesへプロキシします。リクエストのボディは、ちょうど2 KBか64 KBのMessagesのリクエストです。responses_*とagent_responses_*のシナリオでは、ちょうど2 KBのResponsesのリクエストです。ボディはMockLLM.request_bodyが作り、Responsesのボディにはapi: :responsesを渡します。どのボディでも"model"が最初のキーで、ストリームのボディには"stream": trueがあります。abortとresetのシナリオには、Responsesに対応するシナリオがありません。nginxは、どちらのAPIのバイトも、同じように中継するからです。

各agent_*のシナリオで、ソークテストはnginxより先にモックを起動します。モックのポートは、ベースのポートに2を足した番号です。最後のサンプルの後、ソークテストはモックのカウンタを確かめます。モックが読んだリクエストは、ソークテストが送ったリクエストとちょうど同じ数でなければなりません。その数は1 + SOAK_WARMUP + SOAK_Nです。また、そのすべてのリクエストが、シナリオが決める終わり方で終わっていなければなりません。agent_streamでは、レスポンスを最後まで書き終えることです。agent_client_abortでは、nginxが接続を閉じるまでストリームを止めておくか、モックがまだ書いている間に接続が閉じていたことです。agent_upstream_resetでは、接続をリセットすることです。モックが出力したものはlogs/mock.<scenario>.logに書かれます。

agent_upstream_resetは、errorのレベルの行を2つ許します。どちらも、モックの/v1/messagesへのupstreamの接続についての行です。1つ目はrecv() failed (104: Connection reset by peer)です。nginxは、upstreamの接続のエラーをerrorのレベルで、クライアントの接続のエラーをinfoのレベルでログに書きます。2つ目はupstream prematurely closed connectionです。バッファリングしないモードで、upstreamがレスポンスの途中で接続を閉じると、nginxはこの行を書きます。これまでの実行で現れたのは1つ目だけです。その行の動作の部分は、「while reading upstream」か「while sending to client」でした。agent_client_abortは、warn以上のレベルでは何もログに書きません。

stream_sleepは、ソークと性能比較の既定のシナリオです。接続ごとにNginx::Stream::Async.sleepで1ms待ち、stream sleptとEOFを確認します。

通信全体の期限は、ソークでは30秒、callgrindでは120秒です。短い応答、余分な応答、接続のリセットを検出すると失敗します。

ポートの範囲は変わりません。先頭はHTTP制御、次はTCPの測定、その次はstreamのGC制御です。このシナリオはモデルAPIのモックを起動しません。

ソークのsessions列は、最初の確認とウォームアップを含むTCPの完了数です。requests列はHTTP制御のリクエスト数を表します。ほかのシナリオのsessions列は-です。

測定前に、GC制御のセッションが250ms待つ間のカウンターを確認します。stream_timersとstream_fibersが1になり、応答が終わると0に戻る必要があります。値の欠落、負数、整数以外の値も失敗です。

各メモリサンプルの前に、同じstream VMでGC.startを実行します。stream gc completeとEOFを確認し、両カウンターが0に戻ってから記録します。HTTPのシナリオでも、両方の列を表示します。

HTTPとstreamは別のmruby状態を持ちます。HTTP側のNginx::Debug.gcはstream VMを回収しません。gc_liveもHTTP側の値です。streamのGC制御を終えてからworkerのRSSを読み、既存のしきい値で判定します。

性能比較はGC制御のセッションを呼びません。stream_sleepのIrは、TCPセッションあたりの命令数です。計測窓にはngx_stream_mrb_start_fiberがPERF_N回必要です。HTTP制御の呼び出しは数えません。

レポートとJSONの既存のフィールド名は維持します。この行だけはrequestを含む名前もセッション単位です。ヘッダーにも単位を示し、JSONの各結果にはunitを追加します。値はsessionまたはrequestです。

ruby_callsはHTTPとstreamのファイバー開始を含みます。GCの除外と警告・失敗のしきい値は変わりません。

測定用の両ビルドは--with-streamを付けます。更新後はONLY_RUNを付けずにソークと性能比較を流してください。構成の変更を検出してビルドし直します。通常のビルドと統合テストの構成は変わりません。

共有TCPクライアントの検査は、ビルド前に自動で流れます。応答、EOF、タイムアウト、リセット、カウンターの値を、nginxなしで確かめます。単独ではruby test/soak/tcp_client_test.rbで実行できます。

test/soak/run.shは、test/build_release.shでbuild_soak/にビルドします。説明は下の「リリースのビルド」にあります。nginxとngx_mrubyは-O2 -gでビルドし、MRB_GC_STRESSも--with-debugも付けません。build_config.rbのgemは、build_config.rb.lockのコミットでビルドします。このビルドには、定義が2つ加わります。ngx_mrubyは-DNGX_MRUBY_DEBUG_STATSを付けてコンパイルし、mrubyは-DMRB_USE_MALLOC_TRIMを付けてコンパイルします。後者を付けると、mrb_full_gc()はmalloc_trim(0)も呼びます。mrubyがフルGCを実行するのは、求められたときと、まれな場合だけです。求めるのはGC.startやNginx::Debug.gcです。まれな場合とは、インクリメンタルGCが多すぎるオブジェクトを見つけたときや、メモリの確保に失敗したときです。そのため、サンプルの間のワーカーは、この定義が無いときと同じように動きます。

-DNGX_MRUBY_DEBUG_STATSを付けると、クラスのNginx::Debugが加わります。build.shのデフォルトのビルドには、このクラスがありません。test.shは、このクラスをHTTPの反復sleepなどの統合テストで使います。

  • Nginx::Debug.gcは、フルGCのmrb_full_gcを実行し、nilを返します。
  • Nginx::Debug.statsは、次のSymbolをキーに持つHashを返します。
    • gc_live:mrb->gc.liveの値です。
    • gc_root:nginxのプロセス全体で、ngx_mrubyがGCから守っているオブジェクトの数です。数えるのは2種類のオブジェクトで、呼び出し1回につき1つと数えます。1つは、mrb_gc_register()で登録して、まだ登録を外していないオブジェクトで、各mrb_stateのholderがこれにあたります。holderはsrc/http/ngx_http_mruby_gc_roots.hにあります。もう1つは、ngx_mrb_gc_roots_add()でholderに入れて、まだngx_mrb_gc_roots_remove()で外していないオブジェクトです。各ディレクティブのコンパイルしたコードもこれにあたり、mrb_stateを閉じるまで、スロットに残ります(src/common/ngx_mruby_code.h)。httpモジュールの分とstreamモジュールの分を足して数えます。即値はmrubyが登録しないので、数えません。ngx_mrubyが入れた数より多く外すと、この値は負になります。
    • gc_root_fibers:gc_rootが数えるオブジェクトのうちの、fiberの数です。
    • gc_arena_idx:mrb->gc.arena_idxです。
    • timers:Nginx::Async.sleepのタイマーのうち、発火も削除もされていないタイマーの数です。
    • stream_timers:timersと同じ数え方で、Nginx::Stream::Async.sleepのタイマーの数です。
    • stream_fibers:streamのハンドラのfiberのうち、streamモジュールのmrb_stateのholderに保持されているものの数です。sleepした後で、終わっておらず、セッションも終わっていないfiberが入ります。この数はgc_root_fibersにも入ります。stream_sleepはセッションの待機中に2つのカウンターが増えることを確認し、終了後に0へ戻ることを確かめます。すべてのソークのサンプルで両方の値を検査し、表に表示します。
    • gc_root_mrubyとgc_root_fibers_mruby:httpモジュールのmrb_stateにある、mruby自身の_gc_root_の配列の長さと、配列の中のfiberの数です。mruby 3.xと4.0は、そのmrb_stateで最初にmrb_gc_register()を呼んだときに、この配列を作ります。mruby 4.1は、代わりにGCのルートをmrb->gc.rootに持つので、この2つのキーはありません。gc_rootと違って、この2つの値には、mrubyとgemが登録したオブジェクトが入り、holderの中のオブジェクトは入りません。配列にあるのはhttpモジュールのholderで、holderの中のfiberではないからです。ソークテストはこの2つの値を確かめません。配列のあるバージョンのmrubyで、gc_rootと比べるために出す値です。

gc_rootとgc_root_fibersは、GCのルートをmrubyから読みません。mruby 4.1は、GCのルートを_gc_root_の配列に持たなくなったからです。配列から読むと、数はどのサンプルでも0になり、ソークテストは何も確かめずに通ってしまいます。ngx_mrubyはfiberをmrb_stateのholderに保持し、src/http/ngx_http_mruby_core.cのngx_mrb_gc_roots_add()とngx_mrb_gc_roots_remove()で数えます。-DNGX_MRUBY_DEBUG_STATSを付けると、src/http/ngx_http_mruby_debug.hは、mrb_gc_registerとmrb_gc_unregisterをマクロとして定義します。このマクロは、mrubyの関数を呼んでから、その呼び出しを数えます。そのため、このヘッダをインクルードするソースファイルの呼び出しは、後で加えた呼び出しも含めて、すべて数えられます。したがって、src/http/、src/stream/、src/common/の.cファイルのうち、どちらかを呼ぶものは、ngx_http_mruby_debug.hをインクルードしなければなりません。test/soak/run.shは、ビルドの前にこれを確かめ、インクルードしていないファイルがあれば止まります。定義が無いと、このヘッダはマクロを定義せず、呼び出しはmrubyの関数に直接届きます。

soak.rbは/procを読むので、LinuxとCRuby 3.0以降が要ります。ほかのシステムでは、コンテナの中で実行してください。たとえば、次のようにします。

$ docker run --rm -v "$PWD":/work -w /work ubuntu:22.04 sh -c 'apt-get -qq update && DEBIAN_FRONTEND=noninteractive apt-get -qq install -y build-essential rake ruby bison git gperf wget ca-certificates zlib1g-dev libpcre3-dev libssl-dev >/dev/null && sh test/soak/run.sh'

Linuxでは、次のように実行します。

$ sh test/soak/run.sh # build, then run the default scenarios
$ ONLY_RUN=1 sh test/soak/run.sh # run without building
$ ONLY_RUN=1 SOAK_SCENARIOS=sleep,disconnect SOAK_N=100000 sh test/soak/run.sh

最初の実行には数分かかります。gemをクローンし、mrubyとnginxをビルドするからです。シナリオの実行には約1分かかり、aarch64のコンテナでは、そのうちagent_*のシナリオが約18秒です。結果のテーブルには、シナリオごとに1つのレコードがあります。ある値がサンプルの間で違うときは、4つの値をすべて/で区切って示し、その理由をテーブルの下に挙げます。ログはbuild_soak/nginx/soak/logs/にあり、error.<scenario>.log、stderr.<scenario>.log、mock.<scenario>.log、soak.logの4種類です。mock.<scenario>.logは、agent_*のシナリオでモックのLLMが出力したもので、soak.logはsoak.rbの出力の記録です。

test.shが止めるのは、自分が起動したnginxだけです。説明は上の「nginxを止める」にあります。また、test.shのポートは、ソークテストのポートとは重なりません。

変数 デフォルト 意味
ONLY_RUN 未設定 設定すると、ビルドを飛ばす
NUM_THREADS_ENV CPUの数の半分 ビルドの並列数。build.shに渡す
SOAK_SCENARIOS デフォルトのシナリオ全部 カンマで区切ったシナリオの名前
SOAK_N 20000 ウォームアップの後に、シナリオごとに送るリクエストの数
SOAK_WARMUP 2000 最初のサンプルを取る前に送るリクエストの個数
SOAK_CONCURRENCY 8 接続の数。disconnectではスレッドの数を表す
SOAK_PORT_BASE 12360 シナリオのポート。sub_requestのバックエンドは次の番号を使い、モックのLLMはさらにその次の番号を使う
SOAK_RSS_STEP_KB 512 最後のウィンドウでのVmRSSの上限。単位はkB
SOAK_RSS_TOTAL_KB 1024 最初のサンプルから最後のサンプルまでのVmRSSの上限。単位はkB

しきい値とキャリブレーション

Section titled “しきい値とキャリブレーション”

VmRSSの2つの上限は、2026年10月3日にデフォルトのシナリオを実行した結果から決めました。環境は、nginx 1.31.6、Ubuntu 22.04、gcc 11、glibc 2.35です。実行した場所は、aarch64のコンテナと、x86_64のCIのsoakジョブです。テーブルの値は、そのレコードのすべてのシナリオと実行のうちで、最も大きい値を選んで示します。

実行 最後のウィンドウの増分 最初のサンプルからの増分
aarch64のコンテナ、3回実行、SOAK_N=20000、MRB_USE_MALLOC_TRIMを付けないとき +144 kB +212 kB。減る向きには最大で-1076 kB
aarch64のコンテナ、1回実行、SOAK_N=100000、MRB_USE_MALLOC_TRIMを付けないとき +288 kB +3396 kB (disconnect)
aarch64のコンテナ、10回実行、SOAK_N=20000 +112 kB (sub_request) +204 kB (sleep)
aarch64のコンテナ、1回実行、SOAK_N=100000 +68 kB (file) +160 kB (file)
x86_64のCIのランナー、4回実行、SOAK_N=20000 +144 kB (filter) +236 kB (sleep)
aarch64、3回、SOAK_N=20000、agent_*、2026年10月4日の実行 +28 kB (agent_stream) +32 kB、シナリオはagent_upstream_reset
x86_64のCI、実行37152930938と37156005549、SOAK_N=20000、agent_*、2026年10月4日の2回の実行 +16 kB、シナリオはagent_streamとagent_client_abort +84 kB (agent_streamとagent_client_abort)

malloc_trim(0)が無いと、SOAK_N=300000のdisconnectのシナリオでは、VmRSSがウィンドウごとに+2832 kB、-788 kB、+1088 kB動きました。最後のウィンドウの上限を512 kBにすると、この動きは上限を超えます。それでも、このシナリオのカウンタは同じままで、全体の増分はSOAK_N=100000のときより小さくなりました。malloc_trim(0)があると、最も大きい増分は、最後のウィンドウで144 kB、全体で236 kBです。デフォルトの上限は、最後のウィンドウで512 kB、全体で1024 kBで、それぞれこれらの約3.5倍と約4.3倍です。最後のウィンドウの上限を緩いほうにしたのは、共有のCIのランナーで、1つのウィンドウが144 kB増えたためです。小さなリークを見つけるのは、全体の上限のほうです。リクエストあたり約50バイト未満のリークは、SOAK_Nがデフォルトの20000なら、1024 kBに届きません。それより小さなリークを探すには、SOAK_Nを上げてください。比較のために挙げると、リクエストあたり4 kBリークするビルドは、ウィンドウごとに約26 MB増えます。

  1. test/soak/nginx.confにlocationを加えます。ハンドラを使うなら、ハンドラのファイルをtest/soak/handlers/に加えます。そのディレクトリのパスには__SOAK_HANDLERS__を使い、2つ目のserverには__SOAK_BACKEND_PORT__を使います。モックのLLMを後ろに置くシナリオは、代わりにtest/soak/nginx.agent.confに加え、モックには__SOAK_MOCK_PORT__を使います。
  2. test/soak/scenarios.rbのSCENARIOSにScenarioを加えます。パス、リクエストヘッダ、期待するボディとレスポンスヘッダ、モードを指定します。モードは:keepalive、:disconnect、:abort、:cutのどれかです。エージェントのテンプレートのシナリオでは、conf: 'nginx.agent.conf'、リクエストのメソッドとボディ、mock:も設定します。mock:にはモックのオプションを指定し、デフォルトのままなら[]にします。フィールドの一覧は、そのファイルの先頭のコメントにあります。
  3. test/soak/soak.rbのDEFAULT_SCENARIOSにシナリオの名前を加えます。ソークテストを3回実行し、すべてのカウンタが同じままで、VmRSSが上限に収まることを確かめます。あるカウンタが増え続けるなら、そのシナリオは問題を見つけました。シナリオを通すために、上限を上げたり、比較を外したりしないでください。脆弱性の可能性があるときは、SECURITY.mdに書いてある方法で、非公開で報告してください。
  4. :keepaliveのシナリオは、下の性能の比較でも測れます。test/perf/perf.rbのDEFAULT_SCENARIOSに名前を加え、性能の比較の「しきい値とキャリブレーション」にある、変更の無い比較をそこで流して確かめてください。

sh test/build_release.sh SOURCE_DIR BUILD_DIRは、リリースに近いオプションで、ngx_mrubyを静的モジュールとして組み込んだnginxをビルドします。nginxとngx_mrubyは-O2 -gでビルドし、mrubyは、mrubyのgccのツールチェインが決めるフラグでビルドします。そのフラグは-O3 -gです。test.shが加えるMRB_GC_STRESSと、--with-debugは付けません。build_config.rbのgemは、gemのロックのコミットでビルドします。ロックの説明はこの下にあります。ソークテストと性能の比較は、このスクリプトでビルドします。オプションが混ざらないように、それぞれ専用のディレクトリにビルドします。

ビルド ディレクトリ 加えるオプション
test/soak/run.shのソークテスト build_soak/ ngx_mrubyに-DNGX_MRUBY_DEBUG_STATSをRELEASE_CC_OPTで加え、mrubyに-DMRB_USE_MALLOC_TRIMをNGX_MRUBY_CFLAGSで足す
性能の比較のtest/perf/run.shとtest/perf/compare.sh build_perf/head/、build_perf/base/ 無し。どちらの定義を付けても、測るプロセスに余分なコードが加わるため

SOURCE_DIRはビルドするチェックアウトで、スクリプトは、そのチェックアウト自身が持つビルドのファイルを使います。build.sh、configure、build_config.rbなどです。そのため、プルリクエストのベースは、ベース自身のビルドの仕方でビルドされます。スクリプトはソースをBUILD_DIR/treeにコピーし、そこでbuild.shを実行して、nginxをBUILD_DIR/nginxにインストールします。その結果、スクリプトは、build/ディレクトリ、mruby/build、test.shが生成したMakefile、config、mrbgems_configには触れません。このビルドは、いつも、自分でダウンロードしたnginxのソースとシステムのOpenSSLでビルドする静的モジュールです。そのため、スクリプトはBUILD_DYNAMIC_MODULE、NGINX_SRC_ENV、OPENSSL_SRC_VERSIONを無視します。nginxのソースはBUILD_DIR/tree/build/にダウンロードします。nginx.orgに届かないときは、AGENTS.mdに書いてある方法で、ソースをそのディレクトリに置いてください。

サードパーティのgemは、SOURCE_DIRにコミットしたbuild_config.rb.lockのコミットでビルドします。説明はdocs/install/README.mdの「Gem commits」にあります。RELEASE_GEM_LOCKが設定されていて空でないときは、その値が指すロックのコミットでビルドします。test/soak/run.shとtest/perf/run.shは、環境のRELEASE_GEM_LOCKをそのまま渡します。そのため、RELEASE_GEM_LOCK=/path/to/other.lock sh test/soak/run.shを実行すると、チェックアウトを変えずに別のコミットでビルドできます。ロックの無いチェックアウトでは、最初のビルドが各gemのブランチの先頭を取ります。ロックをコミットする前のチェックアウトが、これにあたります。rakeは、ビルドしたコミットをBUILD_DIR/tree/build_config.rb.lockに書き込みます。

後の実行では、スクリプトはコピーを更新し、変わったファイルだけをビルドし直します。

  • スクリプトは、内容が違うときだけ、ファイルをコピーに書き込みます。書き込んだファイルの時刻は、SOURCE_DIRの時刻でなく、コピーした時刻になります。git archiveで作ったチェックアウトのファイルは、コミットの時刻を持ちます。この時刻は前のビルドのオブジェクトより古いことがあり、そうするとmakeはそのファイルをビルドし直しません。
  • SOURCE_DIRに無くなったファイルは、コピーから消します。
  • makeは、src/とdependence/のヘッダを追いません。そのため、そのどれかが変わったときは、スクリプトがそこにある.cファイルをtouchします。
  • スクリプトは、ファイルを消して作り直さず、その場で上書きします。ソースが大文字と小文字を区別しないファイルシステムにあり、それをコンテナと共有することがあります。macOSのDocker Desktopがその例です。この場合、rakeはmrubyのRakefileをrakefileとして読み込みます。ファイルを消して作り直した後、同じコンテナでの2回目の実行は、LoadError: cannot load such file -- .../rakefileで失敗していました。

ただし、makeとrakeが気づかない変更もあります。消したソースや外したgemのオブジェクトはlibmruby.aに残り、nginxのconfigureも再び実行されません。そこでスクリプトは、次の入力を、BUILD_DIR/build_stampに記録します。

  • mrubyのツリー。SOURCE_DIRがgitのworktreeの最上位なら、gitがそのツリーに付けたidを記録します。そうでなければ、mruby/buildとmruby/binを除いたファイルのチェックサムを記録します。この2つのディレクトリは、test.shがビルドした出力です。
  • mrbgems/の下のファイルの名前
  • build_config.rb、config.in、configure、Makefile.in、build.sh、nginx_versionのチェックサム
  • NGX_MRUBY_CFLAGS。スクリプトは、test.shと同じように、この値をmrubyに渡します。
  • nginxのconfigureのオプション
  • そのビルドのgemのロック

スタンプが前のビルドのスタンプと違うと、スクリプトはmrubyとnginxを最初からビルドし、gemも新しくクローンします。ダウンロードしたnginxのソースは残します。新しいクローンが要るのは、ロックだけが変わったときです。rakeは、既にあるクローンを、fetchせずにロックのコミットでチェックアウトします。古いクローンには、そのコミットが無いことがあります。スタンプが扱わない変更の後は、rm -rf build_soakでビルドを手でリセットしてください。性能の比較ではbuild_perfを消します。スタンプが扱わない変更には、たとえばmruby/の下のコミットしていない変更があります。gitがツリーに付けるidは、コミットしたときのままだからです。

リクエストを処理する経路を変えると、どのテストも失敗しないまま、すべてのリクエストの仕事が増えることがあります。性能の比較では、プルリクエストのベースとヘッドのそれぞれで、nginxがリクエストあたりに実行する命令の数を数えます。そして、シナリオごとの変化をレポートに出します。命令の数はcallgrindのIrで、ベースとヘッドはどちらもリリースのビルドです。命令の数はマシンの速さにも負荷にも左右されないので、この比較は共有のCIのランナーでも使えます。共有のランナーのスループットは30%を超えて変わり、そのことはdocs/proposals/v3-plan.mdの3.7節に書いてあります。命令の数には、キャッシュミス、分岐予測のミス、カーネルで使った時間は出ません。命令の数は、nginx、ngx_mruby、mruby、Cライブラリのユーザー空間のコードが、1つのリクエストのためにする仕事の量を表します。

HTTPでは、ソークのkeep-aliveのシナリオと、下のエージェントプロキシのシナリオを測ります。前者はhello、headers、var、filter、sleep、sub_request、fileです。

TCPではstream_sleepを測ります。disconnectは測りません。

各シナリオで、test/perf/perf.rbはベースとヘッドを次の手順で測ります。

  1. シナリオにLLMのモックがあれば、モックを起動します。nginxは、test/soak/nginx.confかシナリオのテンプレートをmaster_process offに変えた設定で、valgrind --tool=callgrind --instr-atstart=noの下で起動します。こうすると、起動の間は計測しません。

  2. レスポンスを1つ確かめてから、PERF_WARMUP回のリクエストまたはTCPセッションを完了します。

  3. TCPでは本文とEOFを確認します。HTTPでは、ウォームアップの接続が閉じたことをstub_statusで確認します。

    その後、callgrind_control --instr=onで計測を有効にします。

  4. HTTPではkeep-aliveを使い、PERF_N回の応答を確認します。keepalive_requestsの1000回ごとに接続し直します。

    stream_sleepでは、接続ごとに1セッションを完了し、合計PERF_N回の本文とEOFを確認します。

  5. callgrind_control --dumpでプロファイルを書き出し、nginxを止めます。

ステップ5のプロファイルは、ステップ4の処理量を記録します。起動、設定、ウォームアップ、終了は含みません。Irの合計をPERF_Nで割ると、HTTPではリクエストあたり、TCPではセッションあたりの値になります。

別の方法として、Nと2Nのリクエストで2回実行し、その差をNで割ることもできます。この方法では3倍の数のリクエストが要り、2回の実行のばらつきも加わります。この比較では、1回の実行の計測窓を使って処理量を求めます。

callgrind_controlは、valgrindのgdbserverであるvgdbを通してプロセスに届きます。vgdbは、nginxのワーカーのような、valgrindがforkしたプロセスを扱いません。master_process offでは、nginxの1つのプロセスが、ワーカーと同じようにイベントループとハンドラを実行します。epoll_waitで待っているプロセスに割り込むためのptraceをvgdbが使えないときは、コマンドは、そのプロセスが次にコードを実行したときに動きます。そのためperf.rbは、コマンドが動くまで、0.2秒ごとに/statusへリクエストを送ります。/statusはstub_statusです。これらのリクエストの一部はウィンドウに入ります。これまでの実行では、ウィンドウごとに2つでした。

GCを除いたリクエストあたりのIrは、mrubyのガベージコレクタのコストを除いた値です。除くのは、コレクタの外からmrb_incremental_gcとmrb_full_gcを呼んだ呼び出しのinclusiveのコストです。そうした呼び出しは、mrb_obj_alloc、mallocのラッパー、GC.startから来ます。このコストは、再帰のサフィックス'2の無いmrb_incremental_gcとmrb_full_gcについてcallgrind_annotate --inclusive=yesが出すinclusiveのコストです。ただし、mrb_incremental_gcが実行するフルGCは2回数えません。perf.rbは、この値をプロファイルの呼び出しの記録から読みます。詳しくはparse_profileのコメントにあります。GCは、まとまって動きます。生きているオブジェクトの数がしきい値を超えると、mrb_obj_allocがコレクタを呼びます。1つのサイクルは、ルートのスキャンとマーク、その後のスイープで、数回の呼び出しになります。helloでは、20000のリクエストで21回の呼び出しがあり、およそ2000のリクエストに1つのサイクルです。GCは合計の約6%です。リクエストあたりに確保するオブジェクトが数個増えたり減ったりする変更では、サイクルがウィンドウに対してずれます。そして合計は、1つのサイクルの一部の分だけ動きます。GCを除いた値はこのようには飛びません。

GCと定数の参照を除いたリクエストあたりのIrは、レポートではw/o GC/constと書きます。この値は、mrubyの定数キャッシュをミスした定数の参照のコストも除きます。除くのは、mrb_vm_const_get自身のコストと、そこからiv_getを呼んだinclusiveのコストです。iv_getは、各クラスの表から定数を探す関数です。CIの実行のプロファイルでは、mrb_vm_const_getが呼ぶのはこの関数だけです。これはtest/perf/perf.rbのCONST_LOOKUP_CALLEESにあります。ほかの関数への呼び出しは除かず、シナリオの行にnot subtracted: <関数> <ベース>/<ヘッド> Irと出します。aarch64のauthのプロファイルでは、callgrindはmrb_vm_const_getがmrb_vm_exec'2を呼び、その下でリクエストの大部分が動いたように示しますが、コードはそう動きません。VMはfiberと大域脱出で関数を抜け、callgrindの呼び出しのグラフはそれを追えないからです。const_missingのRubyのコードも、このような呼び出しになります。こうしたコストを判定の値に残しても、変更を隠すことはありません。一方、ERRORで止めると、aarch64で実行するタグの前の比較が止まります。

mrubyのVMのOP_GETCONSTは、mruby/src/vm.cにあり、定数キャッシュをミスしたときだけmrb_vm_const_getを呼びます。キャッシュのエントリーは64個で(MRB_CONST_CACHE_SIZE)、irepのアドレスとシンボルのハッシュでエントリーを選びます。参照がミスする理由は2つあります。

  • 1つのリクエストがする2つの参照が同じエントリーを使うと、どちらもリクエストのたびにミスします。そうなるかどうかはirepを確保したアドレスで決まり、同じバイナリでも実行ごとに変わることがあります。#766では、同じベースとヘッドのコミットea3c5996eとe7140ba08で、このジョブの2回の実行ではヘッドのstream_sleepがTCPのセッションごとに2回ミスし、3回目の実行ではミスしませんでした。ミスした実行では、mrb_vm_const_getとiv_getがセッションごとに671 Ir多く、GCを除いた値で+6.05%のFAILになりました。コードの変更とは関係の無いFAILです。ハンドラはNginxを、mrbgems/ngx_mruby_mrblibのNginx::Stream::Async.sleepはFiberを参照します。どの2つの参照がエントリーを共有したかは観測していません。その後のnextの実行では、authが両方のビルドで、実行によってリクエストごとに2回か3回ミスしました。
  • キャッシュ全体が消されると、その後の参照はどれも1回ミスします。mruby/src/variable.cのmrb_const_set、mrb_const_remove、mrb_define_const_idと、mruby/src/class.cのmrb_include_module、mrb_prepend_moduleがキャッシュを消します。そのため、Rubyでの定数の代入(OP_SETCONST、Module#const_set)、include、prepend、extendも消します。mrbgems/rack-based-apiのRack.runは、リクエストのたびにKernel.const_setを呼びます。こうしたミスのコストは、キャッシュを消したコードの側にあり、irepのアドレスでは変わりません。

レポートは、どちらもリクエストあたりの数で出します。const_missesはmrb_vm_const_getの呼び出しの数です。const_clearsは、上の関数とmrb_const_cache_clearを、それらではない関数から呼んだ数です。そのため、gccが消す処理を呼び出し元にインライン化しても数えます。aarch64では、Module#const_setの1回の呼び出しで、callgrindは2回と記録しました。比べるのは、1回の実行のベースとヘッドの数だけです。シナリオは、レポートのjudgedの列にある値で判定します。この値はw/o GC/constですが、ヘッドがベースより多くキャッシュを消すシナリオと、ヘッドがキャッシュを消し、かつベースより多くミスするシナリオでは、定数の参照を含めたw/o GCになります。両方のビルドが消す処理の後に変更が参照を足すと、足した参照もリクエストのたびにミスするからです。こうして、消す処理が起こすミスを、変更のコストとして数えます。ヘッドが消さないシナリオと、ベースと同じ回数だけ消してミスが増えないシナリオはw/o GC/constで判定し、そのミスはアドレスの違いによるものとみなします。レポートには、合計、GCを除いた値、GCと定数の参照を除いた値を出します。別の定数がエントリーを使った後の参照だけがミスするので、参照する定数を増やす変更では、キャッシュにヒットした参照のコストは残ります。このコストはmrb_vm_execの中のOP_GETCONSTの命令です。mrb_vm_const_getがメモリを確保するのはconst_missingを呼ぶときだけで、その確保でGCが動くと、そのGCは2回除かれます。

GCが動くと、残りの部分のコストも変わります。スイープが多くのブロックを解放した後は、リクエストのコードの次のmallocの呼び出しに時間がかかります。そのため、ウィンドウは多くのGCのサイクルにまたがる必要があります。PERF_N=20000では、helloのGCを除いたリクエストあたりのIrは11039でした。PERF_WARMUP=7000にしてウィンドウを5000のリクエストだけずらすと11049で、差は+0.1%でした。PERF_N=1000とPERF_WARMUP=200のウィンドウは1つのサイクルより短く、2回の実行で10726と10732になり、-2.8%でした。これが、PERF_Nを20000に設定した理由です。

性能の比較に入れたエージェントプロキシのシナリオ

Section titled “性能の比較に入れたエージェントプロキシのシナリオ”

これらのシナリオでは、エージェントプロキシにリクエストあたりどれだけのコストがかかるかを測ります。測るのは、test/soak/nginx.agent.confの設定でLLMのモックの前に置いたnginxです。LLMのモックは「LLMのモックのupstream」に、この設定はソークテストの節の「エージェントプロキシのシナリオ」にあります。Rubyを使わないシナリオは、同じ形のシナリオのベースラインです。そのため、2つの差がRubyの加えるコストになります。テーブルの最後には、test/soak/nginx.confの7つのシナリオを、各シナリオのリクエストの関数を示すために載せています。

シナリオ リクエストと応答 リクエストあたりのRuby リクエストの関数。括弧の中はリクエストあたりの呼び出しの数
proxy_plain_2k, proxy_plain_64k ちょうど2 KBか64 KBのMessagesのボディを/v1/plainへPOSTし、proxy_passでモックへ送る。応答はJSONのメッセージ1つ 無し ngx_http_log_request (1)
proxy_stream_plain_50, proxy_stream_plain_1000 "stream": trueを付けた2 KBのボディを/v1/plainへ送る。応答は50か1000のデルタのストリームで、イベントは55か1005 無し ngx_http_log_request (1)
responses_stream_plain_50, responses_stream_plain_1000 "stream": trueを付けた2 KBのResponsesのボディを/v1/responses/plainへ送り、proxy_passでモックの/v1/responsesへ送る。応答は、50か1000のデルタとresponse.completedのResponsesのストリームで、イベントは58か1008 無し ngx_http_log_request (1)
auth proxy_plain_2kのリクエストをサーバのauth.agent.testへ送る。このサーバのserver rewriteハンドラのagent_auth.rbが、クライアントのキーを探し、upstreamの認証情報を差し替える ハンドラ1つ ngx_http_log_request (1)
route_json_2k, route_json_64k proxy_plain_*のリクエストを/v1/routeへ送る。そのaccessハンドラのagent_route.rbが、JSON.parseでボディをパースし、proxy_pass http://$agent_backendのupstreamブロックを選んで設定する ハンドラ1つ ngx_http_log_request (1)
ruby_call_1, ruby_call_10 mruby_set_codeの変数を1つか10個持ち、return 200で応答するlocationへのGET。upstreamは無し 1回か10回のハンドラの呼び出し ngx_http_mruby_set_inline_handler (1か10)
hello, headers, var, filter, sleep, sub_request, file test/soak/nginx.confのlocationへのGET。locationは「メモリのソークテスト」にある。モックは無し ハンドラかフィルタ1つ ngx_mrb_start_fiber (1)

test/soak/nginx.confの7つのシナリオは、ngx_mrb_start_fiberの呼び出しを数えます。ハンドラやフィルタのRubyのコードを実行するngx_mrb_runは、実行のたびにfiberを1つ始めます。ほかにngx_mrb_start_fiberを呼ぶものはありません。これらのシナリオがngx_mrb_runを数えないのは、callgrindがその呼び出しをどのビルドでも同じようには記録しないからです。2026年10月4日にnextの45c9e52をaarch64でビルドしたものでは、callgrindは、リクエストごとにngx_mrb_runの2つ目の呼び出しを記録しました。filterでは、ngx_mrb_runからngx_mrb_run'2への呼び出しとして記録し、この呼び出しは1回と数えます。ほかの6つのシナリオでは、ngx_mrb_http_get_module_ctx.part.0からngx_mrb_run'2への呼び出しとして記録しました。ngx_mrb_http_get_module_ctxはngx_mrb_runを呼ばないにもかかわらず、そう記録しました。そのため、6つのシナリオのウィンドウにはリクエストごとに2回の呼び出しが入り、チェックに失敗しました。ngx_mrb_start_fiberの呼び出しは、7つのすべてで、リクエストごとに1回と記録しました。CIのランナーで動かしたx86_64のビルドと同じです。

upstreamのあるシナリオは、ngx_http_log_requestの呼び出しを数えます。nginxは、Rubyの有無にかかわらず、終えるリクエストごとにこの関数を1回呼びます。サブリクエストについては、log_subrequest onのときだけ呼びます。Rubyを使わないシナリオには、数えるngx_mrb_start_fiberの呼び出しがありません。そこで、upstreamのあるシナリオは、どれも同じこの関数を数えます。callgrind_controlのためにnginxを起こす/statusのリクエストも、計測を有効にした後に来たものはウィンドウの中で終わります。そのため、ウィンドウには、その数だけ多くの呼び出しが入ることがあります。これまでの実行では、ウィンドウごとに2つでした。mruby_set_codeは、そのハンドラの末尾呼び出しを通してngx_mrb_runに至ります。callgrindは、この末尾呼び出しを、いつもngx_mrb_runの呼び出しとして記録するとは限りません。aarch64のビルドでは、ruby_call_10のリクエストあたり10回の呼び出しのうち1回が、ハンドラからngx_mrb_start_fiberへの呼び出しとして出て、ruby_call_1では1回も出ませんでした。そのため、ruby_call_*のシナリオは、nginxがポインタを通して呼ぶハンドラの呼び出しの回数を数えます。

リクエストあたりの数のうち4つは、テーブルの後に出力し、report.jsonに残しますが、チェックはしません。1つ目はruby_callsで、ngx_mrb_start_fiberの呼び出しの数です。ngx_mrb_runはRubyのコードを実行するたびにfiberを1つ始め、ほかにこの関数を呼ぶものはありません。test/soak/nginx.confの7つのシナリオでは、ウィンドウのチェックも同じ呼び出しを数えます。2つ目はnon_buffered_callsで、バッファしないレスポンスを中継するngx_http_upstream_process_non_buffered_requestの呼び出しの数です。nginxは、upstreamの接続が読めるようになったときと、クライアントの接続に書けるようになったときに、この関数を呼びます。1回の呼び出しで、nginxはrecv()がブロックするところまでupstreamから読み、読んだものをクライアントへ書きます。一度に読むのは、最大でproxy_buffer_sizeの4kです。そのため、この数は4kずつ読んだ回数ではありません。1つのレスポンスに何回の呼び出しがかかるかは、各呼び出しのときにレスポンスのどれだけが届いていたかで決まります。この数は、ビルドとマシンでも違います。proxy_plain_*、auth、route_json_*では、aarch64のコンテナでリクエストあたり2.00回、x86_64のCIのランナーで1.00回でした。3つ目と4つ目はconst_missesとconst_clearsで、mrubyの定数キャッシュをミスした数と、キャッシュを消した数です。「何を測るか」を参照してください。どちらかのビルドが定数を参照したときは、行に、両方のビルドの定数の参照のリクエストあたりのIr(const lookups <ベース>/<ヘッド> Ir)と、除かなかったmrb_vm_const_getの呼び出しも、あわせて出します。

呼び出しのたびにIrがかかります。aarch64でPERF_N=2000のproxy_stream_plain_50を、モックの書き方を3通りに変えて測りました。ストリームを1回で書く場合、イベントごとに1回書く場合、イベントごとに1 msずつ空けて1回書く場合です。リクエストあたりの呼び出しは3.00、4.96、109.99回で、リクエストあたりのコストは52270、54255、142740 Irでした。1つ目と2つ目の差からは呼び出しあたり約1010 Ir、1つ目と3つ目の差からは約850 Irになります。2つのビルドを比べるとき、呼び出しの数が違うシナリオのレポートの行には、その差だけで生じるIrを出します。このIrは呼び出しあたり1000 Irとして計算し、ベースのGCを除いた値に対する割合で示します。1000はNON_BUFFERED_CALL_IRの値です。その割合がPERF_WARN_PERCENTの半分以上なら、その行には、シナリオの変化はレスポンスが届いたタイミングから来たのかもしれないと書きます。proxy_stream_plain_50では、呼び出しがリクエストあたり約2回増えるとWARNに、約3回増えるとFAILに届きます。「しきい値とキャリブレーション」では、ビルドの入力を変えない変更を測りました。そこでは、1回の実行のベースとヘッドの間で、このシナリオの呼び出しはリクエストあたり0.01から0.25回違いました。

2つのビルドでconst_missesが違うシナリオの行には、それらの定数の参照のIrを示します。このIrは推定ではなく、各ビルドで測った値です。ベースのGCと定数の参照を除いた値に対する割合も示し、判定に使わないことを「not judged」と書きます。割合がPERF_WARN_PERCENTの半分以上なら、ヘッドで定数キャッシュをミスする参照が増えたか減ったかを書きます。たとえば、#766のFAILの実行のstream_sleepは、const_misses 0.00/2.00 (const_misses +2.00 per request: +671 Ir, +5.86% of base w/o GC/const, not judged; more constant lookups of head miss the constant cache of mruby)になります。ヘッドがキャッシュを消さないなら、この注記は、ヘッドでirepのアドレスが変わり、キャッシュの別のエントリーを使ったことを示します。判定は変えず、2回目の実行も要りません。ヘッドのほうが多くキャッシュを消すときと、ヘッドが消してミスが増えたときは、行の終わりにhead clears the constant cache of mruby more often: judged w/o GCかhead clears the constant cache of mruby and misses more lookups: judged w/o GCと出し、ミスを含めた値で判定します。

最初の測定は2026年10月4日です。このチェックアウトのヘッドのビルドで、test/perf/perf.rbを1回実行しました。ヘッドは、nextのf62880cにハーネスを加えたものです。環境は、aarch64のコンテナの中のUbuntu 22.04で、gcc 11、valgrind 3.18.1、nginx 1.31.6、PERF_N=20000です。Hは同じ実行のhelloの値で、リクエストあたり11856 Ir、GCを除くと11158 Irになります。

シナリオ リクエストあたりのIr。括弧の中はGCを除いた値 H リクエストあたりのnon_buffered_calls
proxy_plain_2k 21952 (21952) 1.85 2.00
proxy_plain_64k 22264 (22264) 1.88 2.00
proxy_stream_plain_50 54294 (54294) 4.58 4.97
proxy_stream_plain_1000 432228 (432228) 36.5 38.43
auth 49132 (46977) 4.14 2.00
route_json_2k 109396 (106246) 9.23 2.00
route_json_64k 1603842 (1600216) 135.3 2.00
ruby_call_1 11404 (10737) 0.96 0
ruby_call_10 41541 (35237) 3.50 0

同じ実行での、同じ形のシナリオの間の差は次のとおりです。

  • authからproxy_plain_2kを引くと、リクエストあたり27180 Irで、GCを除くと25025 Ir、2.3 Hです。これは、2回のHashの検索と3回の変数への代入をするserver rewriteハンドラ1つの分です。
  • route_json_2kからproxy_plain_2kを引くと、87444 Irで、GCを除くと84294 Ir、7.4 Hです。これは、2 KBのボディをパースするaccessハンドラ1つと、変数を使うproxy_passの分です。このproxy_passは、upstreamブロックを名前で探します。
  • route_json_64kからproxy_plain_64kを引くと、1581578 Irで、GCを除くと1577952 Ir、133 Hです。増えた62 KBのボディには、GCを除いて1 KBあたり約24100 Irかかりました。
  • Rubyの呼び出しを1回増やすと、(ruby_call_10 - ruby_call_1) / 9で3349 Ir、GCを除くと2722 Ir、0.28 Hです。
  • Rubyを使わずにストリームのイベントを1つ増やすと、(proxy_stream_plain_1000 - proxy_stream_plain_50) / 950で398 Irです。その実行のnon_buffered_callsは、リクエストあたり4.97と38.43でした。

Responsesのストリームは、2026年10月19日に測りました。nextのa466688をベースにし、シナリオを加えたヘッドと比べて、test/perf/compare.shを1回実行しました。ベースとヘッドはどちらもリリースのビルドで、同じバイナリです。環境は、aarch64のコンテナの中のUbuntu 22.04で、gcc 11、valgrind 3.18.1、nginx 1.31.6、PERF_N=20000です。ベースのビルドでは、helloはリクエストあたり11618 Irで、GCを除くと11260 Irでした。ほかの結果は次のとおりです。

シナリオ リクエストあたりのIr。括弧の中はGCを除いた値 H リクエストあたりのnon_buffered_calls
proxy_stream_plain_50 53674 (53674) 4.62 4.27
responses_stream_plain_50 55710 (55710) 4.80 5.65
proxy_stream_plain_1000 433190 (433190) 37.3 37.20
responses_stream_plain_1000 478098 (478098) 41.2 59.46

中継するResponsesのイベントを1つ増やすと、(responses_stream_plain_1000 - responses_stream_plain_50) / 950で445 Irかかりました。同じ実行で、Messagesのイベントは399 Irでした。Responsesのストリームのデルタのイベントは186から189バイトで、長さが変わるのはsequence_numberが大きくなるためです。Messagesのストリームのデルタのイベントは121バイトです。1000のデルタのストリームのボディは、Responsesでは215046バイト、Messagesでは121619バイトです。中継の関数の呼び出しは、リクエストあたりResponsesでは59.46回、Messagesでは37.20回でした。

その実行では、proxy_stream_plain_1000とroute_json_64kに、ビルドごとに83秒と129秒かかりました。デフォルトのセットのシナリオは、すべて合わせて約140秒です。そのため、この2つはDEFAULT_SCENARIOSに入れていません。responses_stream_plain_1000も入れていません。これらはPERF_SCENARIOSで挙げてください。エージェントプロキシのほかのシナリオはデフォルトのセットに入り、測定の時間はビルドごとに約1分増えます。

しきい値とキャリブレーション

Section titled “しきい値とキャリブレーション”

判定の値がベースより3%以上多いと、シナリオはWARNになり、5%以上多いとFAILになります。3%はPERF_WARN_PERCENTの値で、5%はPERF_FAIL_PERCENTの値です。終了ステータスは、シナリオがFAILのとき、測定が失敗してERRORになったとき、比べたシナリオが1つも無いときに1になります。測定が失敗するのは、次のどれかがあったときです。期待しないレスポンス、error.logのerror以上のレベルの行、タイムアウト、ダンプが無いこと、リクエストを含まないウィンドウです。詳しくは「CIで実行する」にあります。例外は1つだけです。ヘッドが通るのにベースが期待しないレスポンスを返す場合で、ヘッドの機能を必要とするシナリオはこうなります。このとき、レポートはシナリオをn/aと示し、実行は失敗になりません。ただし、これはベースの測定でほかに何も問題が起きなかったときだけです。ベースのerror.logには、リクエストのRubyのコードが例外を起こしたときにngx_mrubyが出す行があってもかまいません。その行はmrb_run failed: return 500 HTTP status code to client: error: ...で、ヘッドのRubyのメソッドやクラスを持たないベースは、NoMethodErrorやNameErrorでこの行を出します。error以上のレベルのほかの行があると、シナリオはERRORになります。たとえば、LLMのモックが失敗してnginxが502を返したときに、nginxがログに出すconnect()やrecv()のエラーです。モックの問題と、1つのログにそのレベルの行が5つより多くあることも、ERRORになります。レポートはログごとに5行を示し、残りは読まないからです。ヘッドにしか無いディレクティブがあると、ベースは起動のときに止まるので、これもERRORになります。

しきい値は、2026年10月3日に、ビルドの入力を変えない変更で確かめました。ビルドの入力が同じ2つのチェックアウトで、compare.shを3回実行しました。チェックアウトは、nextのf713d4eと、test/とドキュメントだけを変えるブランチです。環境は、aarch64のコンテナの中のUbuntu 22.04で、gcc 11、valgrind 3.18.1、nginx 1.31.6です。1回目の実行は両方のツリーをビルドし、残りの2回はONLY_RUN=1で同じビルドをもう一度測りました。次のテーブルは、ベースに対するヘッドの変化を、合計とGCを除いた値の順に示します。

シナリオ ベースのリクエストあたりのIr。括弧の中はGCを除いた場合の値 1回目 2回目 3回目
hello 11736 (11039) +0.002% / +0.003% -0.000% / -0.000% +0.008% / +0.008%
headers 36002 (34025) +0.002% / +0.002% -0.002% / -0.002% +0.000% / +0.000%
var 21199 (19700) -0.000% / -0.000% +0.000% / +0.000% +0.000% / +0.000%
filter 14010 (13089) -0.002% / -0.002% -0.002% / -0.002% +0.002% / +0.002%
sleep 15427 (14654) -0.006% / -0.007% -0.002% / -0.002% +0.000% / +0.000%
sub_request 48710 (47538) -0.003% / -0.004% -0.001% / -0.001% -0.001% / -0.001%
file 14009 (13075) +0.002% / +0.002% +0.000% / +0.000% -0.002% / -0.002%

最大の変化は0.008%で、リクエストあたり約1命令です。これはWARNの3%の300分の1より小さいので、Nを上げる必要はありません。後の2026年10月4日の実行では、同じ2つのチェックアウトを新しくビルドし、sub_requestが+0.076%でした。GCを除いたリクエストあたりのIrは47501と47537です。ほかのシナリオは、どれも0.011%以内でした。2つ目のサーバへプロキシするsub_requestは、いちばん大きくばらつきます。下に書くとおり、CIのランナーでも同じです。callgrind_controlを起こす/statusへのリクエストは、接続を含めて約12500命令かかります。各ウィンドウには、そのうち2つのリクエストの一部が入ります。これは、いちばん小さいウィンドウであるhelloの2億3500万命令の、多くても約0.01%にあたります。

エージェントプロキシのシナリオは、2026年10月4日に、ビルドの入力を変えない変更で確かめました。2つは、同じ種類のaarch64のコンテナで測ったもので、9つのシナリオをすべて測りました。9つには、デフォルトのセットから外した2つも入ります。残りの1つは、これらのシナリオを加えたプルリクエストのperfジョブで、x86_64のCIのランナーで、デフォルトのセットの7つを測りました。このジョブの実行は37152930938で、ベースはnextのf62880c、ヘッドはマージコミットで、ビルドの入力は変わっていません。次のテーブルは、ベースに対するヘッドの変化を、合計とGCを除いた値の順に示します。

シナリオ aarch64で同じビルドを2回。nextの4f29b06 aarch64のcompare.sh。nextのf62880cとプルリクエスト x86_64のCIの実行37152930938
proxy_plain_2k +0.000% / +0.000% +0.005% / +0.005% +0.000% / +0.000%
proxy_plain_64k +0.005% / +0.005% +0.009% / +0.009% -0.110% / -0.110%
proxy_stream_plain_50 +0.042% / +0.042% +0.023% / +0.023% -0.063% / -0.063%
proxy_stream_plain_1000 +0.004% / +0.004% +0.007% / +0.007% 実行していない
auth +0.000% / +0.000% +0.000% / +0.000% +0.000% / +0.000%
route_json_2k +0.000% / +0.000% +0.000% / +0.000% -0.000% / -0.000%
route_json_64k +0.000% / +0.000% +0.000% / +0.000% 実行していない
ruby_call_1 +0.000% / +0.000% +0.000% / +0.000% +0.000% / +0.000%
ruby_call_10 +0.003% / +0.004% +0.000% / +0.000% +0.000% / +0.000%

upstreamのあるシナリオがいちばん大きくばらつき、non_buffered_callsでは、そのばらつきの一部しか説明できません。aarch64では、proxy_stream_plain_50が最大で0.042%動きました。このときの呼び出しは、ベースとヘッドでリクエストあたり5.01と5.02でした。CIのランナーでは、proxy_plain_64kが-0.110%動きました。リクエストあたりのIrは22530と22506で、呼び出しは両方のビルドで1.00でした。proxy_stream_plain_50は-0.063%動き、その間に呼び出しは4.86から4.94に増えました。この増加だけで約0.14%増えるはずです。同じジョブの2回目の実行は37156005549で、そのプルリクエストのレビューを反映したコミットで動きました。このときもビルドの入力は変わっていません。この実行では、proxy_plain_64kが+0.30%でした。リクエストあたりのIrは22564と22630で、呼び出しは両方のビルドで1.00でした。proxy_stream_plain_50は+0.39%で、その間に呼び出しは4.92から5.17に増え、比較はその分を+0.43%と見積もりました。ほかのシナリオは、どれも0.02%以内でした。タイミングで量が変わるほかの仕事は数えていません。たとえば、64 KBのリクエストのボディを何回で読むかです。aarch64で同じビルドを繰り返し実行したときは、GCを除いたリクエストあたりのIrが、authで46797と46977で、差は0.38%でした。route_json_2kでは106066と106246で、差は0.17%でした。しきい値が比べるのは1回の実行のベースとヘッドの間の変化で、これらの実行での最大は0.39%でした。これはWARNの3%の約8分の1です。ランナーでの後の実行でも、upstreamのあるシナリオは0.数%動くことがあります。これらのシナリオの変化がWARNに近いときは、リグレッションとみなす前に、2回目の実行と、non_buffered_callsの注記が要ります。

このcompare.shの実行では、aarch64の両方のビルドで、test/soak/nginx.confの7つのシナリオがウィンドウのチェックに失敗しました。当時、これらのシナリオはngx_mrb_runを数えていて、callgrindはその呼び出しをリクエストごとに2回記録しました。詳しくは「性能の比較に入れたエージェントプロキシのシナリオ」にあります。今はngx_mrb_start_fiberを数えます。2026年10月4日に、同じ種類のコンテナで、ビルドの入力を変えない変更をもう1つ測りました。compare.shのベースはnextの45c9e52で、ヘッドはtest/perf/とドキュメントだけを変えるブランチです。この測定では、両方のビルドで、7つのシナリオの各ウィンドウにngx_mrb_start_fiberの呼び出しがちょうど20000回ありました。デフォルトのセットのシナリオは、どれも0.017%以内で、最大はproxy_stream_plain_50でした。7つのシナリオは0.009%以内でした。

しきい値が働くことを確かめるために、ベースのコピーのngx_mrb_runの先頭に、100回まわる空のループを入れてヘッドにしました。ループのカウンタはvolatileです。当時の7つのシナリオは、どれもリクエストごとにngx_mrb_runを1回実行します。エージェントプロキシのシナリオは後から加わりました。そのうちproxy_*のシナリオはRubyを実行せず、ruby_call_10は10回実行します。ngx_mrb_runのselfのコストは、どのシナリオでもリクエストあたり604命令増えました。レポートでは、helloが+5.47%でFAILになりました。filterとfileが+4.62%、sleepが+4.10%、varが+3.07%で、これらはWARNでした。headersは+1.79%、sub_requestは+1.26%で、これらはokでした。これらの割合は、604命令を各シナリオのGCを除いたリクエストあたりのIrで割った値です。compare.shは1で終了しました。命令の数で言うと、3%は、helloではリクエストあたり約330、sub_requestでは約1430命令です。

CIのランナーでは、perfジョブを加えたプルリクエストのそのジョブが、同じく、ビルドの入力を変えない変更になります。ランナーはx86_64のubuntu-22.04で、バージョンは上と同じです。ベースはnextのf713d4eで、ヘッドはマージコミットでした。このジョブを4回実行し、どの回も両方のツリーをビルドしました。1回目から3回目は、そのプルリクエストの最初のコミットでの、ジョブの実行と2回の再実行です。4回目は、ドキュメントだけを変えた2つ目のコミットで、ジョブを実行しました。

シナリオ ベースのリクエストあたりのIr。括弧の中はGCを除いた場合の値 1回目 2回目 3回目 4回目
hello 11669 (11006) -0.003% / -0.004% -0.003% / -0.003% +0.000% / +0.000% +0.000% / +0.000%
headers 39424 (37267) -0.002% / -0.002% +0.000% / +0.000% +0.000% / +0.000% +0.000% / +0.000%
var 22383 (20706) +0.000% / +0.000% +0.000% / +0.000% +0.000% / +0.000% +0.000% / +0.000%
filter 14569 (13636) +0.000% / +0.001% +0.003% / +0.004% +0.000% / +0.000% +0.003% / +0.002%
sleep 15833 (15068) +0.006% / +0.006% +0.000% / +0.000% +0.001% / +0.001% +0.002% / +0.002%
sub_request 49996 (48854) +0.001% / +0.001% +0.016% / +0.016% -0.001% / -0.001% +0.020% / +0.021%
file 14309 (13360) +0.002% / +0.002% +0.000% / +0.000% -0.002% / -0.003% +0.000% / +0.001%

そのプルリクエストのレビューを反映したコミットで、このジョブをさらに2回実行しました。このときも、ビルドの入力は変わっていません。sub_requestを除くすべてのシナリオは0.007%以内で、sub_requestは+0.005%と-0.047%でした。sub_requestのGCを除いたリクエストあたりのIrは、48706と48683です。2026年10月4日までの6回の実行をまとめると、次のとおりです。

  • 1回の実行のベースとヘッドの間では、最大の変化は約0.05%で、sub_requestの約23命令でした。ほかのシナリオは、どれも0.007%以内でした。
  • 実行の間では、sub_requestのGCを除いたリクエストあたりのIrは48683から48857までで、差は0.36%でした。ほかのシナリオは、どれも0.015%以内でした。

ばらつくのは、2つ目のサーバへプロキシするsub_requestです。その1回の実行の中での最大の変化でも、WARNの3%の約60分の1です。ベースとヘッドは同じジョブで続けて測るので、しきい値が見るのは1回の実行の中の変化です。命令セットが違うので、数はaarch64のものと違います。x86_64では、callgrindはGCの入口の関数に再帰のサフィックスを付けません。GCを除いた値から除くコストは、ここでも、callgrind_annotateが出すmrb_incremental_gcのinclusiveのコストに等しくなります。nextでは、ci-okはこのジョブを必要とします。下の「CIで実行する」を参照してください。

同梱のmrubyの次の差は、受け入れ済みです。そのため、後の比較は、この差を含んだ状態を基準に測ります。#678からは、PRのbaseのnextはmruby 4.1.0-rc2を同梱します。

  • mruby 4.1.0-rc2と4.0.0の差です。どちらにも#682のGCのルートのholderを入れて比べ、比較は#678にあります。authのGCを除いたリクエストあたりのIrは、42599から45621へ7.10%増えました。Rubyを使うシナリオでは、GCの割合も増えました。たとえば、authは3.7%から13.5%に、headersは6.6%から20.9%になりました。ほかのシナリオは、GCを除いた値でWARNより下でした。
    • GCを除いた値が増えたのは、mruby 4.1のVMとコアが、同じバイトコードをより多くの命令で実行するからです。authでは、mruby自身の関数で、リクエストあたり約2260 Ir増えました。原因は3つあります。1つ目は2-wayのメソッドキャッシュで、リクエストごとに探索で見つけるメソッドが、4.0.0の17個から22個に増えました。2つ目は、StringのキーでHashを引くときにobj_eqlを通ることです。3つ目は、Cのメソッドの引数のパースが、さらに分かれたことです。どれもmruby 4.1の作りで、不具合として知られているものはありません。
    • GCの割合が増えたのは、ヒープに空きのスロットが無いときの動作が変わったからです。mruby 4.1は、前回のマークで空きができていれば、ヒープのページを足す代わりにフルGCを実行します。これはmrubyのコミットc009f1633の変更で、小さな固定のアリーナで動くターゲットのヒープを抑えるためのものです。コミットの題は「gc: try to reclaim before growing the object heap」です。ngx_mrubyのワーカーは、1024スロットのページ2つに、生きているオブジェクトを約1100個持ちます。そのため、インクリメンタルGCが始まる前にヒープの空きが尽き、そのたびにフルGCが動きます。
    • GC.interval_ratioを変えても、この動作は変わりません。ヒープを大きくすると、GCの割合は0〜3%になります。大きくするには、MRB_HEAP_PAGE_SIZEを4096にするか、起動時にmrb_gc_add_region()でページを足します。しかし、多くのシナリオでGCを除いた値が増え、増え方は最大で17%でした。測定は#678にあります。ngx_mrubyは、mrubyのデフォルトのままにします。
  • オーナーは、2026年10月31日にこれらの差を受け入れました。記録は#678とdocs/HANDOFF.mdにあります。

baseが同梱するmrubyがheadより古い比較では、このような差がまた測られます。#678より前のnextのコミットをbaseにすると、上のmruby 4.0.0との差が出ます。タグの前に前のタグと比べるときも、baseは古くなります。その比較は、AGENTS.mdの「Design principles」にあります。v3の最初のプレリリースの前は、baseはmruby 3.3.0を同梱するv2.7.2です。mruby 3.3と4.1の差を扱う行はファイルに無いので、その比較のWARNとFAILの行は、規則のとおりオーナーに確かめます。

test/perf/accepted.txtには、受け入れ済みの差を1つずつ1行に書きます。行には、条件、シナリオ、判定の値の変化の許容幅を、パーセントで書きます。条件は2つあります。mruby-versionは、各ビルドのツリーのmruby/include/mruby/version.hにあるMRUBY_RELEASE_MAJORとMRUBY_RELEASE_MINORから作るMAJOR.MINORを比べます。書式は、ファイルの先頭のコメントにあります。mruby-version 4.0 4.1 auth 8は、baseがmruby 4.0.xを、headが4.1.xを同梱するときに当てはまります。

mruby-versionの行が当てはまるのは、両方のビルドが条件に合うときだけです。pull-requestは下で説明します。行が当てはまると、その行が挙げるシナリオのWARNかFAILの行のうち、許容幅に収まるものは、ok (accepted: mruby 4.0.0→4.1.0, +8%)と表示されます。この行は実行を失敗させず、ジョブのアノテーションのnoticeになります。許容幅を超える変化は、WARNかFAILのままです。report.txtのヘッダの1行と、ジョブのサマリーのテーブルの下の1行には、両方のビルドのmrubyのバージョンと、当てはまった差を出力します。たとえばperf: mruby: base 4.0.0, head 4.1.0; accepted differences (accepted.txt): auth up to +8% (mruby 4.0.0→4.1.0)で、当てはまる差が無ければnone applyです。perf.rbは、測る前にこのファイルを読み、書式に合わない行があると、ファイルと行の番号を示して止まります。--self-testもこのファイルを確かめます。GCの割合は出力するだけで判定しないので、ファイルにはGCの割合の許容幅の行がありません。

もう1つの条件のpull-requestは、オーナーがプルリクエストで受け入れたFAILのためのものです。「CIで実行する」を参照してください。この行には、プルリクエストのベースブランチと番号を書きます。たとえばpull-request next 812 stream_sleep 7です。この行が当てはまるのは、そのプルリクエストのperfジョブだけです。ジョブは、ベースブランチと番号をPERF_BASE_REFとPERF_PULL_REQUESTでperf.rbに渡します。これらを設定しないローカルの実行では、この行は当てはまりません。前のタグとの比較も同じです。当てはまった行のシナリオはok (accepted: pull request #812 to next, +7%)と表示され、ヘッダの1行にはpull request #812 to nextが加わります。1つのシナリオにpull-requestの行とmruby-versionの行が両方当てはまるときは、pull-requestの行を使います。この行は、マージした後も記録としてファイルに残します。ほかのプルリクエストの比較には当てはまりません。

PRが測るバイナリの入力か測定を変え、perfがtrueになるときは、作者がPRをreadyにする前に、baseとの比較を手元で流し、レポートをPRの本文に引用します。AGENTS.mdの「Design principles」を参照してください。その後、CIで実行するのperfジョブが、同じ比較をrunnerでもう一度流します。

ドライバには、CRuby 3.0以降と、callgrind_controlとその補助のvgdbを持つvalgrindが要ります。callgrind_controlとvgdbはLinuxで動きます。これらが無いと、perf.rbはすぐに止まります。macOSでは、Linuxのコンテナの中で実行してください。このチェックアウトをorigin/nextとコンテナの中で比べるには、次の1つのコマンドを実行します。

$ rm -rf build_perf/base-src && git archive --prefix=build_perf/base-src/ origin/next | tar -x && docker run --rm -v "$PWD":/work -w /work ubuntu:22.04 sh -c 'apt-get -qq update && DEBIAN_FRONTEND=noninteractive apt-get -qq install -y build-essential rake ruby bison git gperf wget ca-certificates zlib1g-dev libpcre3-dev libssl-dev valgrind >/dev/null && sh test/perf/compare.sh build_perf/base-src'

Linuxでは、次のように実行します。

$ sh test/perf/compare.sh build_perf/base-src # build both, then compare
$ ONLY_RUN=1 sh test/perf/compare.sh build_perf/base-src
$ ONLY_RUN=1 PERF_SCENARIOS=hello,var sh test/perf/compare.sh build_perf/base-src
$ sh test/perf/run.sh # measure this checkout only

compare.sh BASE_DIR [HEAD_DIR]は、BASE_DIRをbuild_perf/baseに、HEAD_DIRをbuild_perf/headにビルドします。HEAD_DIRのデフォルトはこのチェックアウトです。どちらのビルドでも、サードパーティのgemは、そのツリーにコミットしたbuild_config.rb.lockのコミットです。そのため、gemが違うのはヘッドがロックを変えたところだけです。gemを別のコミットへ動かすプルリクエストは、マージしたときと同じく、そのコミットで測ります。ロックの無いチェックアウトは、反対側のロックを使います。ロックをコミットする前のチェックアウトがこれに当たります。ベースはヘッドのロックを、ヘッドはベースのビルドが書いたロックを使います。レポートは、コミットの違うgemの数を示し、その一覧を出します。測定に使うtest/perf/とtest/soak/のシナリオは、両方のビルドとも、このチェックアウトのものです。最初の実行は2つのツリーをビルドし、それぞれ数分かかります。デフォルトのHTTPシナリオの測定は、ビルドごとに約140秒かかります。CIのランナーでは139秒で、そのうち28秒がsleepです。PERF_SCENARIOSでproxy_stream_plain_1000とroute_json_64kを挙げると、それぞれ約80秒と130秒が加わります。

レポートはbuild_perf/report.txtとbuild_perf/report.jsonに書きます。test.shも12372でLLMのモックのupstreamを起動するので、同時に実行しないでください。

変数 デフォルト 意味
ONLY_RUN 未設定 設定するとビルドを飛ばす
NUM_THREADS_ENV CPUの数の半分 ビルドの並列数。build.shへそのまま渡す
PERF_SCENARIOS test/perf/perf.rbにあるDEFAULT_SCENARIOS カンマで区切ったシナリオの名前
PERF_N 20000 計測窓のリクエスト数またはTCPセッション数
PERF_WARMUP 2000 計測窓の前のリクエスト数またはTCPセッション数
PERF_WARN_PERCENT 3 判定の値がこの割合以上変わるとWARN
PERF_FAIL_PERCENT 5 この割合以上変わるとFAIL
PERF_PORT_BASE 12370 HTTP制御のポート。次はHTTPバックエンドかTCP測定用。3つ目はモデルAPIのモック用で、streamのGC制御には接続しない
PERF_REPORT_DIR build_perf report.txtとreport.jsonを書くディレクトリ
PERF_ACCEPTED_FILE test/perf/accepted.txt 受け入れ済みの差を記録するファイル。空のファイルなら適用前の判定を表示
PERF_BASE_REF 未設定 プルリクエストのベースブランチ。pull-requestの行と照らし合わせる。PERF_PULL_REQUESTと一緒に設定する
PERF_PULL_REQUEST 未設定 プルリクエストの番号。perfジョブは、この2つの変数を両方とも設定する
PERF_REQUEST_FUNCTIONS ngx_mrb_start_fiber test/soak/nginx.confの7つのシナリオで、リクエストごとに1回と数える関数の名前。「CIで実行する」を参照

perfジョブは、作者がPRをreadyにする前に手元で流した比較を、runnerでもう一度流します。こうして、結果が1台のマシンだけに頼らないようにします。手元の流し方は実行するにあります。.github/workflows/test.ymlのperfジョブは、ビルドするreadyのPRで始まります。ビルドするのは、実行するジョブの選択でbuildがstandardかfullになるPRです。比べるのは、test/ci/changes.shがperfをtrueにするときです。つまり、PRが測るバイナリの入力か測定を変えるときか、PRにラベルperfがあるときです。ラベルはジョブが動くときに読むので、ラベルを付けてジョブを再実行すれば足ります。これらのファイルのうちtest.ymlだけを変えるPRは、ラベルがあるときだけ比べます。コードとテストのどれも変えないPRは、ラベルがあってもジョブをスキップします。バイナリの入力は、test/build_release.shがコピーするものです。src/、mrbgems/、mruby/、dependence/、トップレベルのビルドのファイルのbuild_config.rb、configure、config.in、Makefile.in、build.sh、nginx_versionと、gemのロックのbuild_config.rb.lockです。dependence/は、Makefile.inがnginxに加えるngx_devel_kitです。

測定は、test/perf/、test/build_release.sh、test/soak/のシナリオのファイルです。シナリオのファイルは、nginx.conf、nginx.agent.conf、nginx.stream.conf、scenarios.rb、http_client.rb、tcp_client.rb、mock_llm.rb、handlers/です。

masterのジョブも同じで、違いは2つです。masterはgemのロックをコミットしないので、masterではロックは入力ではありません。また、masterにはソークのジョブが無いので、masterのperfジョブは、nextではtest/soak/run.shが実行するLLMのモックのチェックを最初に実行します。そのチェックはruby test/soak/mock_llm_test.rbです。

nextでtest/soak/mock_llm_test.rbを変えるとsoakが真になり、soakジョブがその検査を実行します。masterにはsoakジョブがないため、このファイルだけの変更ではラベルperfがある場合だけ実行します。

nginx_versionを変えると、ヘッドは別のnginxでビルドされます。そのため、そのWARNやFAILには、ngx_mrubyのコストだけでなく、nginx自身のコストも入ります。ngx_mrubyのリグレッションとみなす前に、下に書くとおり、プロファイルの関数を読んでください。

プルリクエストのチェックアウトは、マージコミットのrefs/pull/N/mergeです。ジョブは、その1つ目の親であるベースブランチとマージコミットを比べます。そのため、差は、マージしたときのプルリクエストの変更になります。テーブルはジョブのサマリーにあり、その下に失敗した測定の理由があります。WARN、FAIL、ERROR、n/aのシナリオと、シナリオを1つも比べなかった実行は、アノテーションになります。ジョブはFAILとERRORで失敗します。測定は、次のときに失敗してERRORになります。nginxが起動しないか応答しないとき、callgrind_controlが失敗するかタイムアウトしたとき、ダンプが無いとき、error.logにerror以上のレベルの行があるとき、ウィンドウがリクエストを含まないときです。ウィンドウがリクエストを含まないとは、Irが0のときか、シナリオのリクエストの関数の呼び出しが期待した数でないときです。期待する数は、test/soak/nginx.confの7つのシナリオでは、リクエストごとにちょうど1回のngx_mrb_start_fiberの呼び出しです。エージェントプロキシのシナリオでは、「性能の比較に入れたエージェントプロキシのシナリオ」のテーブルにある関数と回数です。vgdbがプロセスに届かなかったときもcallgrind_controlは「OK.」と出力するので、空のウィンドウはここで見つかります。n/aになるのは、ベースがシナリオに期待しないレスポンスを返し、ngx_mrubyのmrb_run failedの行のほかに問題が無いときだけです。これは、ヘッドの機能を必要とするシナリオで起きます。性能の比較のしきい値とキャリブレーションを参照してください。比べるシナリオが1つも無かった実行は、失敗になります。

リクエストの関数の呼び出しは、名前で数えます。GCCが-O2で作る関数のコピーは、元の関数として数えます。コピーとは、ngx_mrb_start_fiber.part.0、.isra.0、.constprop.0、.coldのようなものです。あるコピーから別のコピーへの呼び出しは1回と数えます。そのため、GCCが関数を分割したりクローンしたりするようになる変更でも、ウィンドウのチェックは失敗しません。次の2種類のプルリクエストは、test/perf/perf.rbのREQUEST_FUNCTIONSに新しい名前を加え、古い名前を残す必要があります。ngx_mrb_start_fiberの名前を変えるプルリクエストと、Rubyの実行のfiberを始める処理を別の関数へ移すプルリクエストです。ヘッドのperf.rbはベースも測り、一覧にある2つの名前の間の呼び出しは1回と数えるからです。今は、GCCはngx_mrb_start_fiberをインライン化できません。この関数はngx_http_mruby_async.cで定義し、ngx_http_mruby_module.cから呼んでいるからです。コンパイラがこの関数をインライン化できるようにする変更では、プロファイルにこの関数の呼び出しが残りません。たとえば、ただ1つの呼び出し元のファイルの中でこの関数をstaticにする変更や、LTOでのビルドです。そうなると、7つのシナリオのウィンドウは、どれも呼び出しが0回になります。そのため、そうした変更では、実際の呼び出しが残る関数を一覧に挙げる必要があります。ローカルの実行では、カンマで区切ったPERF_REQUEST_FUNCTIONSで一覧を上書きできます。REQUEST_FUNCTION_CALLSではシナリオのリクエストあたりの呼び出しの数を、SCENARIO_REQUEST_FUNCTIONSではシナリオの関数を、別のものに設定します。ruby test/perf/perf.rb --self-testは、名前の規則とプロファイルの読み方を、用意した架空のプロファイルで確かめます。ビルドもvalgrindも要りません。compare.shとrun.shは、最初にこれを実行します。

nextでは、ci-okはこのジョブを必要とします。そのため、FAILかERRORの行があると必須のチェックが失敗し、WARNの行では失敗しません。masterのci-okはまだこのジョブを必要とせず、この後のプルリクエストで加えます。上のキャリブレーションのとおり、命令の数はランナーの速さで変わりません。#779から#791までのnextへのプルリクエストで比較したこのジョブの15回の実行では、どの実行も16のシナリオがすべてokでした。実行は2026年11月9日と10日で、GCを除いた最大の変化はresponses_stream_plain_50の0.60%です。#788、#791、#794の実行のプロファイルを、定数の参照も除いて判定し直しても、すべての行がokのままです。判定ごとにプルリクエストで何をするかは、AGENTS.mdの「Design principles」にあります。WARNはレビューを通じてオーナーに確かめ、FAILはオーナーがプルリクエストで受け入れるまでマージしません。ERRORは測定の失敗なので、原因を直すか、ジョブをもう一度実行します。

オーナーが受け入れたFAILを通すには、オーナーの受け入れがプルリクエストのコメントに書かれた後で、そのプルリクエストがtest/perf/accepted.txtに1行を加えます。コメントには、実行、シナリオ、その変化を書きます。行には、条件のpull-request、ベースブランチ、プルリクエストの番号、シナリオ、許容幅を書きます。許容幅は、判定の値で測った変化以上のパーセントです。たとえば、+6.05%ならpull-request next 812 stream_sleep 7です。「受け入れ済みの差」を参照してください。この行をpushするとジョブがもう一度動き、そのシナリオはok (accepted: ...)と表示されて、ジョブは成功します。後の変更で許容幅を超えると、またFAILになります。どの行にも当てはまらないFAILと、ERRORでは、ci-okは失敗したままです。

#766では、このジョブの2回の実行がstream_sleepを+6.05%のFAILと測り、同じベースとヘッドのコミットでの3回目の実行は-0.01%と測りました。この差は、mrubyの定数キャッシュのミスによるものでした。判定に使う値は、今はこのミスを除きます。「何を測るか」を参照してください。それらの実行のプロファイルから判定し直すと、どちらもokになります。変化は+0.19%と-0.01%で、1つ目にはconst_missesの注記が付きます。

アーティファクトのperf-callgrindには、レポートがあります。また、baseとheadのそれぞれについて、ウィンドウのプロファイル、callgrind_controlとvalgrindの出力、nginxのログがあります。プロファイルはcallgrind/callgrind.out.<scenario>です。変化がどこから来たかを見るには、同じシナリオの関数を両方のビルドで出力して比べます。

$ callgrind_annotate --inclusive=yes build_perf/head/callgrind/callgrind.out.var | head -40
$ callgrind_annotate build_perf/base/callgrind/callgrind.out.var > base.txt
$ callgrind_annotate build_perf/head/callgrind/callgrind.out.var > head.txt
$ diff base.txt head.txt

数はウィンドウ全体の値です。1つのリクエストの値は、PERF_Nで割って求めます。プロファイルは、KCachegrindやQCachegrindでも開いて読めます。

共有CTAの枠はcheck-cta-edges.mjsで検査します。通常、hover、キーボードでのfocus、押下中を、英日・明暗の両方で描画します。実際のリンクに加え、buttonとsubmitの試験用要素でも、四辺の枠が内側の塗り面から見分けられることを画素で確かめます。この検査もnpm run check:ciに含まれます。

.github/workflows/site.ymlは、nextへのpushごとと、workflow_dispatchで動き、プルリクエストでは動きません。

masterのsite-dispatch.ymlは、masterへのpushごとに、nextのsite.ymlをworkflow_dispatchで起動します。

PRをreadyにする前に、手元でサイトを検査します。デプロイ前には、マージ済みのツリーをビルドして検査します。

ジョブ 内容
build 新しいcloneでビルドし(check-fresh-clone.sh)、ネットワークを止めてもう一度ビルドし(check-offline-build.sh)、masterから2.xのページをビルドします(build-v2.mjs)。続けて、npm test、check_links.py、npm run checkの検査、contrast.py、同梱のmrubyのmrbcでのRubyのブロックの検査、check-v2.mjs --no-browserを流します。ビルドしたサイトを成果物のsiteとしてアップロードし、全部のステップが通ったときだけgithub-pagesとしてもアップロードします
deploy 成果物のgithub-pagesをGitHub Pagesに公開します。nextでだけ、buildが通った後に動きます
verify-live 公開したサイトを読み直します。成果物のコミットと公開されたコミット、environmentのブランチの制限、公開されたバイト列、HTTPSへのリダイレクト、残したGoogleの検証ファイル、公開したトップページのLighthouse、2つの組み合わせでの公開ページのスクリーンショットです

スクリーンショットはsite/scripts/screenshots-live.mjsが撮ります。このスクリプトは、エンジンと言語の組ごとに読み取り専用のbrowser contextを1つ作って公開ページを開き、400以上のステータスのレスポンス、ページの例外、失敗したリクエスト、止めたリクエスト、成果物と異なるHTMLのどれかがあると失敗します。GitHub Pagesは、デプロイの直後の短い間、一部のファイルに503を返します。2026-10-29から2026-11-16までのnextのsite.ymlのうち、失敗したか流し直して成功した14回の中で、8回はこの503だけで、デプロイの1.5〜2分後に失敗しました。残りの6回は、ビルド、デプロイ、確認のジョブの準備、そのジョブがGitHubのAPIでデプロイを確かめる工程で失敗しました。8回のうち流し直した3回では、失敗の126秒、144秒、289秒後に確認を始めて200を受け取りました。最も早い回では、503は153秒以内に終わっていました。そこで、あるcontextのエラーが、サイト自身のoriginの5xxのレスポンスと、同じURLの失敗したリクエストだけのときは、スクリプトはそれらのURLをNodeから5秒ごとに取得し直し、200が返ったら、そのcontextを最初のページから1回だけ確認し直します。1回の実行の待ち時間は、合わせて240秒までです。これで、ジョブはtimeout-minutes: 10に収まります。上限までに200を返さないURL、同じcontextの2回目の失敗、ほかの全部のエラーは、これまでと同じく、すぐにこの工程を失敗させます。スクリプトは、やり直すたびに、context、URL、ステータス、200が返るまでの秒数、1回目のエラーを表示し、evidence.jsonのretriesにも書きます。--localではやり直しません。npm run check:ciが流すsite/scripts/test-screenshots-live.mjsは、ビルドしたサイトの前にプロキシを置き、終わる503ではやり直して通ること、続く503では上限で失敗すること、404では、単独でも同じcontextの503と一緒でも、すぐに失敗することを確かめます。

デプロイの前に、ビルドしたサイトをブラウザで検査するジョブはありません。ブラウザの検査は全部、手元のsite/のnpm run check:ci(site/scripts/check-ci.sh)で流します。docs/、site/、examples/を変えるプルリクエストの作者は、readyにする前にこれを流し、結果を「How was this tested」に書きます。npm run check:ciは次を流します。

  1. buildのジョブの検査を流します。npm run build、2.xのページのビルド、npm test、gitが追跡するMarkdownのファイルへのcheck_links.py、npm run check、contrast.py、mrbcでのRubyのブロックの検査、check-v2.mjs --no-browserです。2.xのページは、NGX_MRUBY_V2_TREEのwork treeか、site/generated/v2-treeに作るorigin/masterのcloneからビルドします。mrbcは、MRBCかmruby/build/host/bin/mrbcを使い、どちらも無ければ、この検査を飛ばしたと最後に表示します。
  2. 全部のブラウザの検査を、全ページで流します。この部分だけは、前のビルドに対してnpm run check:browserで流せます。check-styles.mjsとcheck-japanese-lines.mjsを--ja-face notoでChromiumとWebKitで流し、/v2/ja/のcheck-japanese-lines.mjs、check-copy-idle.mjs、check-home-interaction.mjs、3.xと2.xのページのcheck-code-layout.mjs、check-focus.mjs、check-language-links.mjs、check-lighthouse.mjs、check-project-badges.mjs --browser、check-search-identifiers.mjs、検索も確かめるcheck-v2.mjs、test-read-only-browser.mjs、screenshots.mjs、screenshots-live.mjs --local、test-screenshots-live.mjsを流します。

新しいcloneでのビルドとネットワークを止めたビルドは、buildのジョブに残します。site/package.json、site/package-lock.json、ビルドのスクリプトを変えるプルリクエストは、この2つも手元で流します(sh scripts/check-fresh-clone.sh、npm run check:offline)。npm testが流すnode scripts/test-site-workflow.mjsは、site.ymlにプルリクエストのトリガか3つ以外のジョブが入ったときと、buildのジョブの検査かブラウザの検査がcheck-ci.shから抜けたときに失敗します。手元で早く回すために、SITE_CI_PAGES(ルートのJSONの配列)でcheck-styles.mjs、check-focus.mjs、check-code-layout.mjsを一部のページに絞れ、SITE_CI_VERSION(2か3)でcheck-code-layout.mjsを1つのバージョンに絞れます。絞った実行は、プルリクエストの証拠になりません。

baseでcodeかtestsが変わると、プルリクエストの手元の実行の後に、src/、test/、build_config.rb(ディレクティブのテーブル、テストのケース、gem)を読むサイトの検査が落ちることがあります。マージのpushで動くsite.ymlが、デプロイの前にこれを見つけます。直しは別のプルリクエストにします。AGENTS.mdの「Review and merge」の条件2を参照してください。

masterをnextへマージするプルリクエストもdocs/を変えるので、作者は、readyにする前に、そのheadのsite/でnpm run check:ciを流します。masterのdocs/test/README.mdにある「The 2.x pages of the site」の検査は、この実行の代わりになりません。その検査は、3.xのページを、マージを含まないnextのcheckoutからビルドし、マージした後のツリーからはビルドしないからです。マージで、docs/ja/に日本語のページがある英語のページの変更が入るときは、同じプルリクエストで日本語のページも直します。docs/releases/README.mdがその例です。check-japanese.mjsが、2つのページのコードブロックを比べるからです。こうすると、マージのpushで動くsite.ymlが、マージした後のツリーの検査で止まり、サイトをデプロイできなくなることを防げます。

サイトのレイアウトと折り返しの検査(check-styles.mjs、check-japanese-lines.mjs)は、2つの組み合わせだけを測ります。PCの全画面にあたるChromiumの1440pxと、iPhoneのSafariにあたるWebKitの402pxです。site/scripts/lib/patterns.mjsがこの2つを持ちます。

4つのトップページの帯にあるバッジのうち、test、nginx-tests、valgrind-nightly、CodeQL、zizmorのworkflowのバッジはGitHubから、OpenSSF Best Practicesのバッジはbestpractices.devから読みます。これらが、サイトで唯一の、別のoriginの画像です。ライセンスのバッジはサイトのファイルです。トップページのリリースのバッジとヘッダーのスターの数は、ビルドのときに作ります。スターの数は、site.ymlがビルドの前にGitHubのAPIから読み、NGX_MRUBY_SITE_STARSとNGX_MRUBY_SITE_STARS_DATEで渡します。この2つが無いビルドは、数を表示しません。読み取り専用のbrowser contextはscripts/lib/read-only-browser.mjsにあり、同じoriginへのGETだけを許します。呼び出す側は画像のURLを正確に指定でき、そのURLへのGETには、ネットワークの代わりにローカルのfixtureで答えます。npm run check:ciが手元で流すブラウザの検査のcheck-project-badges.mjs、check-home-interaction.mjs、screenshots-live.mjs --localと、check-layout-parity.mjsは、これらのURLにscripts/lib/project-badges.mjsの代わりの画像で答えます。そのため、外部のサービスが遅いか止まっていても、これらの検査は止まりません。check-project-badges.mjsは、外部の画像を断った状態でも各トップページを開き、帯の位置と大きさが変わらないことを確かめます。本物の画像を取るのは、デプロイの後のcheck-live.mjsだけです。check-live.mjsは、問題を報告する前に画像ごとに3回再試行します。