Sidekiq::Status

Inside a worker that includes Sidekiq::Status::Worker, you can use total, at, and store to manage job state.

• total(n): Sets the total number of items to process.
• at(n, message): Updates the current progress and an optional status message. This automatically calculates the percentage complete.
• store(key: value): Stores custom metadata. Values are retrieved as Strings.
• retrieve(key): Retrieves custom data stored via store.

class MyJob
  include Sidekiq::Worker
  include Sidekiq::Status::Worker

  def perform(user_id, options = {})
    total 100
    store user_id: user_id

    (1..100).each do |i|
      # ... work ...
      at i, "Processing item #{i}"
      store current_item: i
    end
  end
end

To use Sidekiq::Status in your application, add the gem to your Gemfile or install it directly via the command line. The project supports Ruby 3.2+ and Sidekiq 7.0+.

# In your Gemfile
gem 'sidekiq-status'

# Or via terminal
gem install sidekiq-status

When testing with Sidekiq's inline mode, you can use sidekiq-status/testing/inline to bypass Redis and return a stubbed :complete status. This ensures that synchronous execution in tests doesn't cause status queries to fail.

# In your test/spec helper
require 'sidekiq/testing/inline'
require 'sidekiq-status/testing/inline'

The gem provides a dashboard to monitor job statuses, progress bars, and custom metadata. To enable it, require sidekiq-status/web and mount Sidekiq::Web in your routing configuration.

require 'sidekiq/web'
require 'sidekiq-status/web'

# In Rails routes.rb:
mount Sidekiq::Web => '/sidekiq'

This project uses Appraisal to test compatibility across different Sidekiq versions (7.0, 7.3, 8.0, etc.).

Workflow

1. Install Dependencies: Run bundle install followed by bundle exec appraisal install to generate version-specific Gemfiles.
2. Run All Tests: bundle exec appraisal rake spec runs the suite against all configured Sidekiq versions.
3. Run Specific Version: Use bundle exec appraisal <version-name> rake spec (e.g., bundle exec appraisal sidekiq-8.0 rake spec).
4. Interactive Debugging: Start an IRB session for a specific version using bundle exec appraisal <version-name> irb.

# Install all appraisal gemfiles
bundle install
bundle exec appraisal install

# Test against a specific version
bundle exec appraisal sidekiq-8.x rake spec

Version 4.0.0 introduces several breaking changes and compatibility updates:

• Compatibility: Adds support for Ruby 3.3, 3.4, and Sidekiq 8.x. It drops support for Sidekiq 6.x and Ruby versions 2.7.x through 3.1.x.
• Breaking Change (Storage): The way job timestamps are stored in Redis has changed.
• Breaking Change (API): The method #working_at has been renamed to #updated_at.
• Improvements: Includes enhanced progress bars and improved web interface styling.

To enable job status tracking, you must add sidekiq-status to your Sidekiq middleware chains for both the client and the server. You can optionally provide an :expiration parameter (in seconds) to set the default TTL for job data in Redis. The default expiration is 30 minutes.

require 'sidekiq'
require 'sidekiq-status'

Sidekiq.configure_client do |config|
  # accepts :expiration (optional)
  Sidekiq::Status.configure_client_middleware config, expiration: 30.minutes.to_i
end

Sidekiq.configure_server do |config|
  # accepts :expiration (optional)
  Sidekiq::Status.configure_server_middleware config, expiration: 30.minutes.to_i

  # accepts :expiration (optional)
  Sidekiq::Status.configure_client_middleware config, expiration: 30.minutes.to_i
end

To track progress and store/retrieve job data, include the Sidekiq::Status::Worker module in your worker class. Only jobs that include this module will have their statuses tracked.

To override the global expiration time for a specific worker, define an expiration method within that class that returns the desired TTL in seconds.

class MyJob
  include Sidekiq::Worker
  include Sidekiq::Status::Worker # enables job status tracking

  def expiration
    @expiration ||= 60 * 60 * 24 * 30 # 30 days
  end

  def perform(*args)
    # your code goes here
  end
end

You can set up a development environment using VS Code Dev Containers (recommended), Docker Compose, or a manual local setup.

VS Code Dev Containers

1. Open the project in VS Code.
2. Click "Reopen in Container" when prompted.
3. The container provides Ruby 3.4, Redis 7.4.0, and necessary extensions.

Docker Compose

# Start environment
docker compose -f .devcontainer/docker-compose.yml up -d

# Enter container
docker compose -f .devcontainer/docker-compose.yml exec app bash

Manual Setup

Requires Ruby 3.2+ and Redis installed locally.

git clone https://github.com/kenaniah/sidekiq-status.git
cd sidekiq-status
bundle install

For applications processing thousands of jobs, use these patterns to maintain performance:

1. Increase Expiration: Use longer expiration times to reduce the frequency of Redis operations.
2. Throttled Progress Updates: Instead of updating progress on every iteration, update it every N items (e.g., every 100 items).
3. Redis Pipelining: Use conn.pipelined when performing batch status updates to reduce network round-trips.

# Optimization: Throttled progress updates
class HighVolumeJob
  include Sidekiq::Worker
  include Sidekiq::Status::Worker

  def perform(items)
    total items.size
    items.each_with_index do |item, index|
      process_item(item)
      if (index + 1) % 100 == 0
        at index + 1, "Processed #{index + 1} items"
      end
    end
  end
end