HN 日本語サマリー

← 一覧へ戻る
プログラミング

Kino: Ruby 4.0 用の高性能 Ractor Web サーバー

Kino: A high-performance Ractor web server for Ruby 4.0 (github.com)

58 pointsby ksec11 コメント

要約

Kinoは、Ruby 4.0以降向けの高性能なRactorベースのWebサーバーです。従来のRubyのプロセスフォーク方式と比較して、メモリ使用量を大幅に削減し、I/O負荷の低いエンドポイントやCPUバウンドなタスクにおいて高いパフォーマンスを発揮します。Ractorモードと、RailsなどのRactor非対応アプリも実行できるスレッドフォールバックモードを提供し、Pumaに似た使いやすさを目指しています。

全文翻訳

Kino: Ruby 4.0向け高性能Ractorウェブサーバー

Kino は Ruby 4.0 以降向けの高性能 Ractor ウェブサーバーです。

画像: GitHub Release 画像: Docs

RubyのスレッドはRubyコードを並列実行できないため、本番環境ではコアごとにプロセスをフォークし、メモリコピーのコストを負担する必要があります。Kinoは、1つの小さなプロセス内で各コア上のコードを実行します。Rust (tokio + hyper) のフロントエンドがネットワークを管理し、並列 Ractor が Rack 3 アプリを実行し、スレッドフォールバックモードがそれ以外のもの(Railsを含む)を実行します。

  • 高速。実際の8コアサーバーで、I/O負荷の低いエンドポイントでは、Kinoの各モードはPumaのフォーククラスターより1.5〜1.7倍高速です。ネイティブ HTTP/2 は同じサーバーでHTTP/1.1よりさらに+79%高速化します。Ractorモードは純粋なCPU処理でも+25%の性能向上をもたらします。詳細は以下のベンチマークを参照してください。
  • メモリ使用量がわずか。単純なベンチマークアプリ(Ractorモード)では約8分の1、フォールバックスレッドモードでRailsを処理する場合でもPumaクラスターの4分の1のメモリで済みます。
  • フォークなしの並列処理。Ractorモードは、同じ小さなプロセス内で、Kino自身のGVLバウンドスレッドモードよりもCPU処理を5倍以上高速に実行します。
  • 本番環境向けの機能完備。安全なドレイン、クラッシュ監視と再起動、503エラーを返すバウンドキュー、リクエストタイムアウト、堅牢な受付処理(スローロリスおよびTLSハンドシェークのデッドライン、接続数とボディサイズの制限)、エラー追跡用のon_errorフック、TLS (rustls)、ライブ統計情報、非同期アクセス、アプリロギングが含まれます。
  • 理由を提示。kino --check は、アプリがractorモードで実行できない理由を正確にリストアップし、Ractor::IsolationError を自分でデコードする必要がなくなります。
  • Pumaライク。同じworkers × threadsトポロジー、使い慣れた設定DSL、kino CLI。Pumaを実行できるならKinoも実行できます。

注記: RactorはRuby 4.0では公式に実験的であり、このサーバーも同様です。スレッドモードは安定しています。それでも、Kinoは今日Ractorを試すための最良の方法であり、Ractorが安定した際には最高のRactorサーバーとなることを目指しています。


目次

なぜ

GVL(Global VM Lock)により、一度に1つのRubyスレッドしかRubyコードを実行できません。すべてのコアを使用するために、Rubyサーバーはプロセスをフォークしますが、各フォークはアプリの完全なコピーのコストを発生させます。Ractorにはこの制限がありません。各Ractorは独自のロックを持つため、1つのプロセスでRubyを並列実行できます。欠けていたのは、それらにリクエストをディスパッチするサーバーでした。Ruby 4.0ではRactor(Ractor::Port、shareable_proc、ロック競合の低減)が改修され、これを構築する価値が出てきました。

Ractorサーバーがこの方法で構築される理由、そしてどのRust部分がRactorをここで高速化しているかについては、doc/why-kino.md を参照してください。完全な設計ノートはdoc/architecture.md にあります。

ベンチマーク

実際のサーバーで測定:AWS c7a.2xlarge(8コアAMD EPYC 9R14、16 GB、Amazon Linux 2023)。これは現実的なアプリサーバーのサイズです。

これらのテーブルは、小さな合成Rackアプリを実行しています。プレーンテキスト、10 KBのボディ、CPUバウンドなfib、5 msの待機—サーバーを測定するため、アプリ自体ではなく、意図的に小さくしています。これはRactor共有可能であるため、Kinoはこれを:ractorモード(比較のために:threadedモードも)で実行します。実際のRailsアプリは異なります。Ractor共有可能ではないため、Kinoの:threadedフォールバックモードでのみ実行され、独自の数値になります。詳細は以下のRailsを参照してください。Ruby 4.0.6(YJIT使用、2026-09再測定)、すべてのサーバーはデフォルト設定:Pumaは8ワーカー×3スレッドをフォーク、Kinoは1プロセス(8ワーカー;ractorモードでは各1スレッド、スレッドモードでは3スレッド)で実行。数値はwrkによるreq/s(8秒ウィンドウ、64接続、同じホスト)。方法論:doc/benchmarks.md。

エンドポイントKino :ractor+ lanes:ractor, workers 32²Kino :threadedPuma (クラスター)
/plaintext222,980244,652115,553213,104142,094
/10k175,182188,365103,147132,009125,116
/cpu (fib)76,695¹71,83054,06213,46361,329
/io (5 ms)1,5481,5565,3884,7224,699
/io_native1,5701,5736,2074,6954,693

メモリは、持続的な負荷後のPSS(比例セットサイズ;注参照)によって、アプリに応じて2つの異なる物語を語ります。

小さなベンチマークアプリ(Ractor共有可能、そのためKinoは:ractorまたは:threadedで実行)。KinoはPumaクラスターよりも:ractorモードで約8分の1、:threadedモードで約10分の1のメモリ使用量です。この差が大きいのは、単純なアプリはほとんどがワーカーごとのプライベートヒープであり、コピーオンライトでは共有できないためです。

小さなアプリ、KinoKino (単一プロセス)Puma クラスター (8 ワーカー)比率
:ractor (8×1)135 MB1,072 MB~8倍
:threaded (8×3)107 MB³1,072 MB~10倍

実際のRailsアプリ(Ractor共有可能ではない—Kinoの:threadedフォールバックのみ、以下参照)。差は約4倍で、Railsの大きなフレームワークがPumaのフォーク間でコピーオンライトで共有されるため、差は小さくなります。

Rails hello-worldKino :threadedPuma クラスター (8 ワーカー)比率
PSS95 MB405 MB~4倍

「+ lanes」は実験的なワーカーキューディスパッチャー(lanes true)です。これはここで最も高速なプレーンテキスト/10kを生成します。詳細:doc/benchmarks.md。

¹ デフォルト設定、チューニングなし。Ractorモードはフォーククラスターを純粋CPUで+25%上回ります(lanes使用時+17%;Puma 8.0.2はこれを7.xに対する+34%から縮小しました)。スレッドモードは、単一プロセスRubyサーバーがすべてヒットするGVLの上限を示します。古いCPUチューニングレシピは廃止されました。そのthreads 1半分はデフォルトであり、tokio_threads 1半分は実際のハードウェアでコストがかかります。詳細はdoc/benchmarks.mdを参照してください。

² 待機バウンドのスループットはスロット÷待機であり、デフォルト列はクラスターの24スレッドに対して8シングルスレッドワーカーをもたらします。Kinoスロットはプロセスではなくスレッドです。アプリが待機を多用する場合、workersを増やしてください。workers 32列はそのチューニングです:純粋CPUでクラスターを上回りつつ、/ioで+15%(Kino.sleep経由で+32%)向上します。コストはCPU負荷の低い行(8コアをオーバーサブスクライブする32個のractor)です。アプリの待機プロファイルに必要なトポロジーを選択してください。詳細はdoc/benchmarks.mdを参照してください。

³ MALLOC_ARENA_MAX=2(標準的なRubyデプロイ設定;Herokuのデフォルト)を使用。これがない場合、1つのglibcヒープバルーンを約647 MBに膨らませる10 KBレスポンスを処理する24スレッド—これはリークではなくアリーナ断片化の落とし穴であり、ractorモードはこれを回避します。詳細はdoc/benchmarks.mdを参照してください。

一般的な最初のアイデアは、現在のサーバーを維持し、アプリをractorプールでラップすることです。これも測定しました(同じボックス;分析はドキュメントにあります)。

エンドポイントKino :ractor (8×3)Puma + ractor ラッパーFalcon + ractor ラッパー
/plaintext190,20622,055107,203
/cpu (fib)68,23016,52850,101
/io (5 ms)4,4771,4821,545

(ここでのKino列は8×3を実行します—ラッパーが得るのと同じ24スロットです。そのため、/io行は比較可能です。メインテーブルのractor列は8×1のデフォルトを実行します。)

HTTP/2 直接対決

KinoはHTTP/2をネイティブにサポートしているため、通常のnginx終端ホップをスキップします。上記のテーブルと同じボックス;すべてTLS経由、h2load、64同時実行、同じアプリ:

/plaintextreq/s/upload (64 KB)
Kino ネイティブ h2164,04419,226
Kino HTTP/1.1 (同じ起動)80,78917,210
nginx h2 → Kino HTTP/1.1109,2191,217¹
Falcon (ネイティブ h2)55,63718,838

ネイティブh2は、同じTLSサーバーでHTTP/1.1スループットを2倍にします(クリアテキストh2cで+79%;より少なく、より大きなソケット操作、およびHPACKはCookieの再送信を節約します)。また、同じKinoをnginxでフロントエンド化するよりも+50%高速です—プロキシホップは純粋なコストです。アップロード、h2の古典的な弱点、はHTTP/1と同等の速度で実行されます。完全なマトリックス、クリアテキストh2cレーン、および方法論:doc/benchmarks.md;bench/h2.shで再現可能です。

¹ nginxデフォルト設定のh2リクエストボディフロー制御;ドキュメントを参照してください。

Rails

Railsは現在Ractor共有可能ではないため、Kinoはそれを:threadedフォールバックモードで提供します(1つのGVLバウンドプロセス)。同じボックスで(examples/rails-hello、エッジRails、本番、8×5):

Rails hello-worldreq/sメモリ (PSS)
Kino :threaded (単一プロセス)2,73195 MB
Puma クラスター (8 ワーカー)15,422405 MB

正直なトレードオフ:Pumaのフォーククラスターは8コアすべてを使用するため、スループットは約5.6倍になりますが、メモリは約4倍かかります。RactorモードのRailsは、単一プロセスメモリコストでスループットのギャップを埋めるでしょう。上流のブロッカーはdoc/rails-on-ractors.mdで追跡されています。

要するに:小さな合成アプリでは、ractorモードはフォークレベルのCPU並列処理(Kino自身のGVLバウンドスレッドモードより5.7倍、クラスターより+25%)を単一プロセスで、クラスターメモリの約8分の1(実際のRailsアプリでは約4倍)で上回ります。すべてのKinoモードは、I/O負荷の低いエンドポイントでクラスターより1.5〜1.7倍高速であり、ネイティブHTTP/2はHTTP/1.1に対して+79%の追加性能をもたらします。macOSの数値(二次的;そこではすべてループバック上限に達します)とYJIT × Ractorsの注意点はdoc/benchmarks.mdにあります。

再現方法:メインテーブルはbench/run.sh [seconds] [concurrency]、フォローアップ(CPUレシピ、トポロジー、スケーリング、シャーディングI/O、ロギング、メモリ)はbench/studies.sh、HTTP/2マトリックスはbench/h2.shを使用してください。

インストール

Ruby >= 4.0 が必要です。Kinoをアプリケーションのバンドルに追加してください:

bundle add kino      # または: gem install kino (バンドルの外で)

または、Gemfileに自分で追加してください:

gem "kino"

次に設定を生成して起動します:

bundle exec kino --init    # kino.rb を書き出します;すべてのディレクティブはインプレースで文書化されます
bundle exec kino           # config.ru + kino.rb を読み込み、:9292 で起動します

(スタンドアロンのgem installの後、kinoコマンドはbundle execなしで動作します。)

フレームワーク独自のコマンドを優先しますか? KinoはRackハンドラーを提供しているため、rails server -u kino および rackup -s kino もそれを起動します。これらは同じkino.rb(またはconfig/kino.rb)を読み込み、ホストの-p/-bフラグがファイルより優先され、rackup -s kino -O Workers=4 -O Mode=threadedで残りのオプションにアクセスできます(rackup -s kino --helpで一覧表示)。

Rustコンパイラは不要です:リリースバージョンは、Linux(x86_64/aarch64、glibcおよびmusl)およびmacOS(arm64)用にプリコンパイルされたネイティブgemを提供します。他のプラットフォームでは、gemはインストール時にコンパイルされます。これにはRustツールチェーン、Linuxではclang/libclangが必要です。

使い方

require "kino"

# RactorモードはRactor共有可能なアプリが必要です:何もキャプチャせず、設定をフリーズします。
app = Ractor.shareable_proc do |env|
  [200, { "content-type" => "text/plain" }, ["Hello from #{Ractor.current}"]]
end

Kino::Server.run(app, port: 9292)   # INT/TERMをトラップします;Ctrl-Cで安全にドレインします

または、すべてを明示的に指定して埋め込む場合:

server = Kino::Server.new(app,
  bind: "127.0.0.1",          # またはプロキシの後ろで "unix:///run/kino.sock"
  port: 9292,                 # 0 = エフェメラル;server.port 経由で読み戻し
  workers: Kino.available_parallelism, # ractor数(並列性);デフォルト
  max_workers: nil,           # 実験的:負荷下でworkersを超えるまで増加(Elastic pool参照)
  scale_down_after: 30,       # アイドル状態が続いた後に余分なワーカーがリタイアするまでの秒数
  threads: 1,                 # ワーカーあたり;ractorデフォルト1、threadedデフォルト3
  mode: :auto,                # :auto | :ractor | :threaded
  queue_depth: 1024,          # バウンドキュー;オーバーフロー → 503
  queue_timeout: 5.0,         # キューがいっぱいの場合の503までの秒数
  request_timeout: nil,       # 遅いレスポンスが504になるまでの秒数(nil = オフ)
  max_connections: 8192,      # 同時接続数の上限;デフォルト:ulimit -n の大部分
  max_body_size: 50 * 1024 * 1024,  # 413エラーになる前のバイト数;nil = プロキシに任せる
  on_error: ->(e, env) { ErrorTracker.capture(e) },  # クライアントが500を受け取った後
  shutdown_timeout: 30,       # ドレインの締め切り
  control_bind: "127.0.0.1:9293",   # モニタリング: /stats /metrics /ready /live;ポート0はserver.control_port 経由で読み戻し
  control_token: ENV["KINO_CONTROL_TOKEN"],  # /stats + /metrics のためのオプションのBearer認証
  tls: { cert: "cert.pem", key: "key.pem" },  # ファイルパスまたはインラインPEM
  http2: true,                # TLS上のALPN h2 + クリアテキストh2c;false = HTTP/1のみ
)
server.start
server.shutdown               # 安全なドレイン → 締め切り → 残りのリクエストを強制終了
モード
  • :ractor: workers個のRactor × 各threads個のスレッド。アプリはRactor.shareable?(フリーズされたミドルウェア、shareable_procエンドポイント)である必要があります。共有不可能なアプリで:ractorを強制するとKino::UnshareableAppErrorが発生します。クラッシュしたractorは、インフライトリクエストにすぐに500を返し、その後再起動します。
  • :threaded:同じ仕組みをworkers × threadsの通常のThreadで実行します。今日、Railsを含むあらゆるRackアプリを実行できます。I/Oに対しては並列、CPUに対してはGVLによって直列化されます。
  • :auto(デフォルト):アプリが共有可能な場合は:ractor、それ以外の場合は警告が出て:threadedになります。ただし、1つの注意点:Rackアプリとして使用されるクラスは、たとえその呼び出しが共有不可能な状態に触れる場合でも、常に「共有可能」(クラスは共有可能であるため)と見なされます。そのような場合は:threadedを強制してください。
シャーディングI/O

io_shards true(デフォルトオフ)は、HTTP I/OをTokioの共有マルチスレッドランタイムからカレントスレッドのシャーディングに移動させます。1つのスレッドが接続を受け入れ、各接続を最も負荷の低いシャードに渡し、そのシャードが接続のライフタイム全体を所有します。ホットパスでのワークスティーリングやクロススレッドウェイクアップはありません。8コアのリファレンスボックスでは、高速ハンドラーは+1〜3%向上します(io_threads 8で最適)。スケジューラ競合が増えるとパフォーマンスが向上するため、コア数に応じて測定してください。Rubyバウンドエンドポイントは変更されません。モードとは独立しており、Rust側のみの形状を変更します。

# kino.rb
io_shards true
io_threads 8  # オプション;デフォルト:利用可能なCPUの半分
HTTP/2

デフォルトで有効になっており、両方のトランスポートで、設定不要です:

  • TLSバインドはALPN経由でh2をアドバタイズするため、ブラウザやh2対応クライアントはHTTP/2をネゴシエートし、それ以外はHTTP/1.1のままです。
  • クリアテキストバインドは事前知識h2cを提供します:HTTP/2プリフィックス(h2を優先するロードバランサー、gRPCスタイルのバックエンドホップ、curl --http2-prior-knowledge)で開いたクライアントはHTTP/2を取得します。通常のクライアントは以前と同じHTTP/1.1です。ブラウザはクリアテキストでh2を送信しないため、証明書のないkinoはそれらに対して同じように動作します。

Rack側はh2で仕様を完全に満たしています:SERVER_PROTOCOLは"HTTP/2"、HTTP_HOST/SERVER_NAME/SERVER_PORTは:authority擬似ヘッダーから取得されます(h2リクエストにはHostヘッダーがありません)。分割されたCookieヘッダーは; で再結合され、ストリーミングアップロードはHTTP/1と同じバックプレッシャ付きボディチャネルを流れます。ストリームはキープアライブリクエストと同じワーカー・スロットにマルチプレックスされます。workers × threadsがいずれの場合も並列性を制限します。(rack.hijackはh1と同様にh2でも使用されません。プロトコルにはハイジャックするための101アップグレードがありません。)http2 falseはサーバーをHTTP/1に固定し、h2をALPNから削除します。

設定ファイルとCLI

設定はPumaスタイルのRuby DSLファイルに保存できます:作業ディレクトリにあるkino.rb、またはconfig/kino.rb(Railsのレイアウト)は自動的に読み込まれます。-C PATHで他のパスを指定できます。優先順位:明示的なキーワード引数とCLIフラグ > 設定ファイル > デフォルト。

# kino.rb
port 9292
workers 8
threads 1
mode :ractor
kino --init                   # コメント付きのサンプルkino.rbを書き出します
kino                          # config.ru + kino.rb、ポート9292
kino --check                  # アプリが:ractorモードで実行できるかどうかを説明します
kino -C config/kino.rb -p 3000 -w 4 -m ractor my_app.ru

生成されたサンプルは、Railsの設定やパフォーマンスに関する注記を含む、すべてのディレクティブを文書化しています。

kino --check

アプリが:ractorモードで実行できない場合、Kinoは単なるRactor::IsolationErrorではなく、その理由を教えてくれます。チェックは何も変更せず(オブジェクトをフリーズしません)、各ブロッカーの名前を挙げます:定義場所と共にキャプチャされた変数、パスによるインスタンス変数、クラススタイルのアプリをキャッチするクラスレベルのインスタンス変数トラップ:

$ kino --check
check: app is NOT Ractor-shareable
  - app (Proc at app.rb:12)—captures `cache` = {} (Hash) (unshareable)
  - app (HelloApp).@instance—class-level ivar holds #<HelloApp…>—classes
    pass Ractor.shareable?, but reading this from a worker ractor raises
    Ractor::IsolationError on the first request
  hints: freeze config at boot; build endpoints with Ractor.shareable_proc;
  keep per-worker resources in Ractor.store_if_absent; or run mode :threaded.

終了ステータスは0/1なので、CIでも機能します。プログラム形式はKino::Check.report(app)です。

リクエストタイムアウト

request_timeout: seconds(またはkino.rbでrequest_timeout 30)は、アプリがレスポンスを生成するのにかかる時間を制限します。デッドラインを超えると、クライアントは即座に504を受け取りますが、ハンドラーは実行を続行します。その遅いレスポンスは無害にドロップされます。デフォルトではオフです。任意のRubyコードの実行を中断することは安全ではないため、ハンドラーは意図的に終了させられません。スタックしたハンドラーは、戻るまでワーカー・スロットを占有し続けるため、最も遅い正当なエンドポイントよりもデッドラインを長く設定し、stats[:timeouts]を確認してください。

タイムアウトはアプリを保護し、ネットワーク受付は自身を保護します。max_connections(デフォルト:ulimit -nの大部分)を超える新しい接続はカーネルバックログで待機します。max_body_size(デフォルト50 MB、nilはプロキシに委任)を超えるリクエストボディは413を受け取り、固定デッドラインは遅いヘッダークライアント(15秒)、停止したTLSハンドシェーク(10秒)、およびボディの途中で停止したアップロード(30秒)をドロップします。ワーカーがアプリまたは配信エラーを検出すると、クライアントが500を受け取った後にon_error ->(error, env) { ErrorTracker.capture(error) }が呼び出されます。これは、レスポンスが書き込まれている間に発生したエラーをトラッカーが見ることができる唯一の場所です(:ractorモードでは、ハンドラーをRactor.shareable_procで構築します)。

ライフサイクルフック

Kinoは、on_errorと並んで4つのライフサイクルフックを発火させます。発火コンテキストによって分割されます。

ワーカーコンテキストフックはワーカー内で実行され、すべてのワーカーで利用可能です:

  • after_worker_boot { |worker_id| }:ワーカーがサービスを開始する前に一度実行されます。IDはワーカーのスロットIDです。:ractorモードではワーカーractor内で実行され、Ractor.shareable_procである必要があります。
  • after_request_complete { |env, status| }:各成功したレスポンスの後、ワーカー内で発火します。これはホットパスです。ゼロコストにするために未設定のままにしてください。:ractorモードではRactor.shareable_procである必要があります。

メインコンテキストフックはワーカー外のメインスレッドで実行され、通常のプロックです:

  • after_boot { }:ワーカープールが起動した後、一度実行されます。ここで準備完了を通知します(sd_notify、"server ready"メトリックなど)。
  • on_worker_exit { |worker_index, error| }:ワーカーが終了したときに、そのインデックスとクラッシュの原因(クリーンな終了の場合はnil)と共に発火します。

after_worker_bootの引数はワーカーのスロットIDですが、:ractorモードではon_worker_exitの引数は終了したractor(0..workers - 1)を識別します(異なる数値空間)。そのため、:ractorモードではブートと終了をその数値で相関させないでください。

フックで例外が発生した場合、それはログに記録され、ワーカーを終了させることはありません。

Elastic pool(実験的)

静かな時間帯に合わせてプールをサイズ設定し、忙しい時間帯には拡張できるようにします:

# kino.rb
workers 4            # 常に実行中
max_workers 16       # 負荷がかかった場合にのみ到達
scale_down_after 30  # アイドル状態が続いた後に余分なワーカーがリタイアするまでの秒数

またはKino::Server.new(app, workers: 4, max_workers: 16)を使用します。max_workersを未設定のままにすると、プールは以前と同様にworkersで固定されます。

リクエストがキューで待機している間、Kinoはキューがクリアされるかプールがmax_workersに達するまで100ミリ秒ごとにワーカーを追加します。負荷が過ぎると、workersを超えるワーカーは、アイドル状態がscale_down_after秒続いた後に、1つずつリタイアします。各ワーカーは現在のリクエストを最初に完了します。:ractorおよび:threadedモードで同じ動作をします。

アプリが待機する場合に使用します:データベース、アップストリームサービス、遅いクライアント。workersをコア数に設定した場合、すべてのワーカーがI/Oでブロックされる可能性があり、コアはアイドル状態になります。より高い上限はそれらのコアを仕事に使い、ractorはマイクロ秒で開始されるため、プールは負荷に密接に追従します。純粋なCPU処理はコア数を超えても何も得られません。:ractorモードでは、Ruby自体は最大でRUBY_MAX_CPU個のractorのRubyコードを一度に実行します(デフォルトは8)。プールがそれを超える可能性がある場合、Kinoは起動時に警告します。より大きなボックスでは:

RUBY_MAX_CPU=16 kino

それが呼吸する様子を監視します:server.stats、GET /stats、およびGET /metricsで:

$ curl -s localhost:9293/stats | jq '{workers, max_workers, active_workers, scale_ups, scale_downs}'
{
  "workers": 4,
  "max_workers": 16,
  "active_workers": 9,
  "scale_ups": 12,
  "scale_downs": 7
}

Prometheusはkino_max_workers、kino_active_workers、kino_scale_ups_total、およびkino_scale_downs_totalを取得します。after_worker_bootはプールが追加するすべてのワーカーに対して発火し、on_worker_exit(nilの原因付き)はリタイアするすべてのワーカーに対して発火します。

スタックワーカー隔離

quarantine_timeout: seconds(またはkino.rbでquarantine_timeout 60)は、デッドラインよりも長く実行されているリクエストを持つディスパッチスロットを隔離し、代替ワーカーを起動して容量を回復します。これはrequest_timeoutとは異なり、クライアントに504を返しますが、スロットは占有されたままです。quarantine_max(デフォルト::ractorモードではワーカー数、:threadedモードではワーカー×スレッド数)は、プロセス寿命全体での置換イベントの総数を上限とします。それを超えると、モニターは置換を停止し、サーバーは削減された容量で実行されます。

スタックしたワーカーは中断または強制終了されることはなく、そのスロットは永久に隔離されたままです。:threadedモードでは、ブロックされたスレッドが最終的に戻った場合、同じスロットでリクエストを処理し続けますが、そのスロット自体はプロセス全体で隔離済み(busy_msは0と報告される)のままです。:ractorモードでは、スタックしたractor(およびそのスーパーバイザスレッド)はプロセスが終了するまでリークします。なぜなら、スタックしたractorは安全に中断できないからです。隔離アクティビティはserver.stats(トップレベルのquarantinedカウントとスロットごとのworker_status[].quarantinedフラグ)、GET /stats(同じ)、およびGET /metrics(kino_quarantined_workersゲージとkino_quarantine_replacements_totalカウンター)で監視してください。

統計情報

server.statsはライブスナップショットを返します:設定とネイティブレイヤーからのカウンター(1つのリクエストあたり1つのリラックスしたアトミック、測定可能なコストなし):

server.stats
# => {mode: :ractor, lanes: false, workers: 8, threads: 1, batch: 1,
#     respawns: 0, queued: 0, in_flight: 2, served: 1041, rejected: 0,
#     timeouts: 0, worker_status: [...]}
# lanesがオンの場合はlane_depths: [...]も追加

外部からは、kill -USR1 <pid>が同じスナップショットを1行でログ出力します(pidfileと組み合わせてpidを見つけます):

kino[4213] main: stats mode=:ractor lanes=false workers=8 threads=1 batch=1 respawns=0 queued=0 in_flight=2 served=1041 rejected=0 timeouts=0

プルベースのモニタリングのために、control_bind "127.0.0.1:9293"(またはunix://パス)は、独自のフォールトトレラントスレッドから読み取り専用のコントロールプレーンを提供します。これは、すべてのRubyワーカーがビジーまたはスタックしている場合でも応答し続け、安全なシャットダウン中にdrainingを報告します:

  • GET /stats—server.statsと同じスナップショットをJSON形式で(stateとversionも追加)。
  • GET /metrics—Prometheusテキスト形式(kino_requests_served_total、kino_queue_depth、kino_readyなど)。

/statsと/metricsは、カウンターをディスパッチスロットごとに分解します。/statsはworker_status配列(index、served、in_flight、busy_ms)を含み、/metricsはkino_worker_*{worker="N"}シリーズを生成します。これは実行スロットごと(workers × threads)です。クラッシュしたワーカーのスロットは再利用されないため、停止した時点のカウンターと共にリストに残ります。つまり、配列(およびそのworker="N"メトリックシリーズ)は、すべての再起動ごとに1つずつ増加します。busy_msはスロットの現在のリクエストが実行されている時間です(アイドル時は0)。したがって、他のスロットが0で静止している間に単一スロットが上昇している場合、それはスタックしたワーカーを示しています。

/statsレスポンスとserver.statsはqueue_time(カウントと合計秒数)を含み、/metricsはkino_request_queue_secondsを公開します。これはキュー待機時間のPrometheusヒストグラムであり、ワーカー飽和のシグナルです。カウントは受け入れられたリクエストのみを対象とします。キュー待機後の503はrejectedに、queue_timeには行きません。

  • GET /ready—起動中またはドレイン中は503、サービス中は200:ロードバランサーまたはKubernetesの準備プローブに接続します。
  • GET /live—プロセスが生きている限り200:ライブネスプローブです。

control_token "..."は/statsと/metricsをAuthorization: Bearerで保護します。プローブは開いたままです。

ロギング

リクエストごとに1行のログで、Kino::Loggerは共有::Loggerの1.7倍のスループット(ベンチマークボックスで155k対90k req/s)を維持しました。ネイティブコンポーネントは2つあります。どちらもロックフリーチャネルを通じてRustのフラッシャースレッドに書き込むため、リクエストスレッドはログミューテックスを取得せず、書き込みシステムコールも実行しません:

  • アクセスログ(log_requests true):標準出力にリクエストごとに2つのレコード。アプリに到達しなかった503エラーも含まれます。到着行はアプリが実行される前にキューに入れられるため、ハングしたリクエストは回答のない矢印として表示されます。完了行にはステータス、合計時間、および内訳が含まれます:rubyはリクエストがRubyで費やした時間(GCポーズとそれに割り当てられたオブジェクトを含む)、kinoはサーバー自体のオーバーヘッド、waitはワーカーが処理するまでのキュー時間です。開発での使用を推奨します。本番環境でも十分な低コストです。カラーターミナルでは、完了行はステータスクラスによって色付けされます:2xxは緑、3xxは黄、4xxはマルーン、5xxは明るい赤:
2026-08-22 14:03:11 +0300 → GET /users?q=1  from 127.0.0.1
2026-08-22 14:03:11 +0300 ← 200 GET /users?q=1  12.4ms (ruby 9.1ms [gc 0.8ms; 1.5k obj]; kino 3.2ms; wait 0.1ms)

GCと割り当ての数値はVMのプロセス全体カウンターから取得されるため、一度に1つのリクエストしか所有できない場所でのみ表示されます。:threadedモード、またはworkers 1の:ractorモードです。並列ractorは互いの作業を請求するため、そこでは内訳は(ruby; kino; wait)のみになります。

  • Kino::Logger:同じ非同期シンクを介した::Loggerで、アプリ自身のロギング用です(Kino::Logger.new("log/production.log")、または引数なしで標準出力)。生のIOライクデバイスはKino::Logger::Deviceで、::Loggerフォーマットなしでバイトを扱いたい統合のために使用されます。デバイスはフリーズされ、Ractor共有可能であるため、1つのデバイスがすべてのワーカーにサービスを提供します。

RailsアプリでのKino::Logger:これは実際の::Loggerサブクラスであるため、Railsがロガーを期待する場所ならどこでも適合します:

# config/environments/production.rb、最も簡単な形式:
config.logger = Kino::Logger.new                          # 標準出力
config.logger = Kino::Logger.new("log/production.log")    # ファイル
# ファイルと標準出力の両方:
config.logger = ActiveSupport::BroadcastLogger.new(
  Kino::Logger.new("log/production.log"), Kino::Logger.new
)
# タグ付きロギングは、他の::Loggerと同様にラップします:
config.logger = ActiveSupport::TaggedLogging.new(Kino::Logger.new)

プレーンなRackアプリから、ミドルウェアにロガーを渡すか、Rack::CommonLoggerに生のデバイスを渡します(これは単にwriteを呼び出すだけです):

# config.ru
use Rack::CommonLogger, Kino::Logger::Device.new   # アクセスログスタイル
run MyApp

(リクエスト行のみが必要な場合は、Kino自身のlog_requests trueを優先してください。これはRubyスレッドにとって無料であり、Rackに到達しなかった503も表示します。)

安全なシャットダウンは両方のログを完全にドレインします。ハードクラッシュはバッファの末尾を失う可能性があり、ディスクが処理できる速度よりも速くログを記録する場合(毎秒10万行超)、シンクはリクエストスレッドをブロックする代わりにラインをドロップします。これらのトレードオフはdoc/benchmarks.mdで測定されています。

サーバーライン。Kinoが自身について言うことすべて(ドレイン、クラッシュとその再起動、例外を発生させたフック、隔離、統計ライン、rack.errors)はkino[<pid>] <source>: messageと表示されます。ソースは発言したワーカー、worker-3(またはマルチスレッドractorではworker-3/thread-2)、またはmainです。カラーターミナルでは、ラベルはノートの場合は薄く、警告の場合は黄色、エラーの場合は赤になります。メッセージはプレーンのままです。失敗したリクエストは、生のバックトレースの代わりにレポートを受け取ります:リクエストライン、エラー、コード内の発生場所、次にあなたのフレームが先頭に来るトレース、作業ディレクトリからの相対パス、残りは折りたたまれます:

kino[4213] worker-2: 500 GET /boom · RuntimeError: kaboom (app.rb:12:in 'explode')
    app.rb:12:in 'explode'
    /usr/lib/ruby/gems/4.0.0/gems/rack-3.2.7/lib/rack/builder.rb:...
    … 38 more

フックはKino::Log.info、.warn、.errorで同じチャネルを通じてログを記録できます。ワーカーractor内でも安全です。

タイマー待機

Kino.sleep(seconds)は、GVLを解放したOSクロック上の高解像度スリープです。MRI自身のsleepは、非メインractor内で遅れてウェイクアップします(詳細と数値はdoc/benchmarks.mdにあります)。明示的なタイマー待機にはKino.sleepを使用してください。通常のブロッキングI/Oには必要ありません。

Rack 3互換性

仕様スイートは、リアルソケット経由でRack::Lintの下で各テストアプリを実行します:ストリーミングリクエストボディ(フォワードオンリーrack.input)、列挙可能および呼び出し可能(フルデュプレックスストリーム)レスポンスボディ、小文字およびマルチバリューヘッダー、HEAD/204セマンティクス。ハイジャックは意図的に除外されています。Rack 3ではオプションです。

Rails

Rails(エッジ)は現在Kinoで:threadedモードで実行されます(rails server -u kino、またはkino CLI)。RactorモードのRailsは上流でブロックされています。正確なブロッカー、Ruby::Boxの発見、およびそれを解除するものはdoc/rails-on-ractors.mdにまとめられています。例には、バンドルされたRailsバージョンに対して再テストするプローブスクリプトが含まれています。

開発

bin/setup
bundle exec rake                       # コンパイル、Rustテスト、スペック、RBS、lint
RB_SYS_CARGO_PROFILE=dev bundle exec rake compile   # 高速開発リビルド

謝辞

Mat Sadlerにmagnusを提供していただいたことに感謝します。

Reactorsについては、Koichi Sasada、John Hawthorn、Jean Boussier、Luke Gruber、およびその他のRubyコアコントリビューターに感謝します。

Rustネットワークスタックについては、Sean McArthurにhyperを、Carl Lerche、Alice Ryhl、および他のTokioメンテナーにその下のランタイムを提供していただいたことに感謝します。Joshua Barrettoにflumeを提供していただいたことに感謝します。そのチャネルは、ネットワークサイドとワーカー間のすべてのリクエストを運びます。

支援を受けた

Claude Code (Fable 5, Opus 4.8)。

貢献

バグレポートとプルリクエストは、GitHubのhttps://github.com/yaroslav/kinoで歓迎します。

ライセンス

このgemはMIT Licenseの条件の下でオープンソースとして利用可能です。