Zenn
📕

詳解 Sidekiq Config

に公開
Rails
Ruby
ActiveJob
Sidekiq
tech

はじめに

sidekiq に関する設定は yml などで定義可能である。
しかしながら、公式ドキュメントの説明があまりにも不足していると感じた。

私の参加するプロジェクトの config/sideki.yml には、timeout という項目があった。
当初、私はこう推測した。
「job が performing 状態になってから、タイムアウトするまでの n 分 を定義しているのでは？」
そこで、この推測が正しいかどうか判断するためにドキュメントをさらった。

具体的には、下記に config の定義の説明が述べられている。
https://github.com/sidekiq/sidekiq/wiki/Advanced-Options

しかし、timeout に関する説明が、ない・・・。

結局、ソースコードを読みに行って解決した。

ドキュメントを漁ったり AI に聞いたりと効率の悪い作業だったので、メモ書き兼私のような思いをする人が少しでも減るように、config の内容を2025年9月4日現在のソースを引用しつつまとめておく。

Sidekiq 設定オプション詳細解説

基本設定 (ファイル例：config/sidekiq.yml)

コア設定

:concurrency (デフォルト: 5)

  • 説明: Sidekiq プロセスが使用するワーカー スレッド数
  • ソース: lib/sidekiq/config.rb:15
  • 詳細: 各 Sidekiq プロセスで同時実行可能なジョブ数を制御。高い値は並行性を向上させるが、CPU とメモリ使用量が増加
  • 設定例:
    :concurrency: 10

:timeout (デフォルト: 25秒)

  • 説明: Sidekiq プロセスが quiet になってから shutdown するまでの猶予時間
  • ソース: lib/sidekiq/config.rb:16
  • 詳細: launcher.rb:58でdeadline = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + @config[:timeout]として使用
  • CLIオプション: -t, --timeout NUM (cli.rb:361-363)

:environment (デフォルト: nil)

  • 説明: アプリケーションの実行環境
  • ソース: lib/sidekiq/config.rb:14
  • 詳細: APP_ENV、RAILS_ENV、RACK_ENV の順で環境変数から自動検出される (cli.rb:236)

キュー設定

:queues

  • 説明: 処理するキューのリストと重み付け
  • ソース: capsule.rb:57-75
  • モード:
    • :strict - 重み0、順序固定で処理
    • :weighted - 重み付きランダム処理
    • :random - 全キュー重み1でランダム処理
  • 設定例:
    :queues:
  - critical
  - [default, 2]  # 重み付き
  - low

スケジューリング設定

:average_scheduled_poll_interval (デフォルト: 5秒)

  • 説明: スケジュールされたジョブの Redis チェック間隔
  • ソース: lib/sidekiq/config.rb:18
  • 詳細: 各プロセスがこの値の倍数だけ待機してから Redis をチェック

:poll_interval_average (デフォルト: nil)

エラーハンドリング設定

:error_handlers (デフォルト: [])

  • 説明: エラー処理のためのプロシージャ配列
  • ソース: lib/sidekiq/config.rb:24
  • 詳細: デフォルトでは ERROR_HANDLER が自動追加される (config.rb:64)

:death_handlers (デフォルト: [])

:on_complex_arguments (デフォルト: :raise)

Dead Job 設定

:dead_max_jobs (デフォルト: 10,000)

:dead_timeout_in_seconds (デフォルト: 15,552,000秒 = 6ヶ月)

  • 説明: Dead ジョブの保持期間
  • ソース: lib/sidekiq/config.rb:37
  • 計算: 180 * 24 * 60 * 60 = 180日 × 24時間 × 60分 × 60秒

ライフサイクルイベント設定

:lifecycle_events (デフォルト: 各イベント用空配列)

  • 説明: プロセスライフサイクルの各段階でのコールバック設定
  • ソース: lib/sidekiq/config.rb:26-35
  • イベント種類:
    • startup: プロセス開始時
    • quiet: quietモード移行時
    • shutdown: シャットダウン開始時
    • exit: プロセス終了時
    • heartbeat: 初回ハートビートまたはネットワーク復旧時
    • beat: 10秒ごとの定期ハートビート

Iteration 設定

:iteration (デフォルト: {})

  • 説明: バッチ ジョブのイテレーション設定
  • ソース: lib/sidekiq/config.rb:20-23
  • サブオプション:
    • max_job_runtime: 最大実行時間 (nil = 無制限)
    • retry_backoff: リトライ時のバックオフ時間 (デフォルト: 0秒)

その他の設定

:labels (デフォルト: Set.new)

:require (デフォルト: ".")

:reloader (デフォルト: proc { |&block| block.call })

:backtrace_cleaner (デフォルト: ->(backtrace) { backtrace })

CLI オプション

以下のオプションがコマンドラインから指定可能:

Capsule 設定

Sidekiq 7.0 以降、特定のキューを独立した Capsule として設定可能:

Sidekiq.configure_server do |config|
  config.capsule("unsafe") do |cap|
    cap.concurrency = 1
    cap.queues = %w[queue_a queue_b]  # strict priority
  end
end

各 Capsule は独自の並行実行数とキュー設定を持つ (capsule.rb:32-39)。

設定例

基本的な設定ファイル例

---
:concurrency: 5
:timeout: 30
:queues:
  - critical
  - default
  - low
:labels:
  - worker_type:background

# 環境別設定
staging:
  :concurrency: 10
  :timeout: 60

production:
  :concurrency: 25
  :timeout: 25
  :dead_max_jobs: 50000
  :dead_timeout_in_seconds: 7776000  # 3ヶ月

プログラムによる設定例

Sidekiq.configure_server do |config|
  # エラーハンドラーの追加
  config.error_handlers << proc { |ex, ctx| 
    ErrorReportingService.notify(ex, ctx) 
  }
  
  # デスハンドラーの追加
  config.death_handlers << proc { |job, ex|
    SlackNotifier.notify("Job #{job['class']} failed permanently: #{ex}")
  }
  
  # ライフサイクルイベント
  config.on(:startup) do
    puts "Sidekiq starting up!"
  end
  
  config.on(:shutdown) do
    puts "Sidekiq shutting down!"
  end
end

Discussion