Judoscale

These gems works together with the Judoscale Heroku add-on to scale your web and worker dynos automatically. They gather a minimal set of metrics for each request and job queue, and periodically posts this data asynchronously to the Judoscale API.

Requirements

Rack-based app
Ruby 2.6 or newer
Judoscale or Rails Autoscale installed on your Heroku app

Installation

To connect your app with Judoscale, add these lines to your application's Gemfile and run bundle install:

gem "judoscale-rails"
# Uncomment the gem for your job backend:
# gem "judoscale-sidekiq"
# gem "judoscale-resque"
# gem "judoscale-delayed_job"
# gem "judoscale-good_job"
# gem "judoscale-que"

If you're using a background job queue, make sure you include the corresponding judoscale-* gem as well.

The adapters report queue metrics to Judoscale every 10 seconds. The reporter will not run in development, or any other environment missing the JUDOSCALE_URL environment variable. (This environment variable is set for you automatically when provisioning the add-on.)

Installation for Non-Rails Rack apps

If you're using another Rack-based framework (such as Sinatra), you should use judoscale-rack instead of judoscale-rails:

gem "judoscale-rack"

The gem provides a request middleware, but you'll need to insert that middleware into your app.

Bundler.require
use Judoscale::RequestMiddleware

The middleware will start the async reporter when it processes the first request.

Worker adapters

Judoscale will autoscale your worker dynos! Four job backends are supported: Sidekiq, Delayed Job, Good Job, and Que. Be sure to install the gem specific to your job backend:

gem "judoscale-sidekiq"
gem "judoscale-resque"
gem "judoscale-delayed_job"
gem "judoscale-good_job"
gem "judoscale-que"

For most apps, no additional configuration is needed. See the configuration section below for all available options.

Worker-only apps

If your app doesn't have a web process, you don't have to include the "judoscale-rails" gem. If you omit it, you'll need to start the reporter manually:

require "judoscale/reporter"
Judoscale::Reporter.start

What data is collected?

The reporter runs in its own thread so your web requests and background jobs are not impacted. The following data is submitted periodically to the Judoscale API:

Ruby version
Rails version
Job library version (for Sidekiq, etc.)
Judoscale gem versions
Dyno name (example: web.1)
PID
Collection of queue time metrics (time and milliseconds)

Judoscale aggregates and stores this information to power the autoscaler algorithm and dashboard visualizations.

Migrating from `rails_autoscale_agent`

The migration from rails_autoscale_agent to judoscale-rails (+ your job framework gem) is typically a single step: replace the gem "rails_autoscale_agent" in your Gemfile with gem "judoscale-rails" and the appropriate judoscale-* package for your back-end job framework (sidekiq, resque, delayed_job, good_job, or que) or see the Installation section above for further specifics. If you previously had any custom configuration for the rails_autoscale_agent, please note that we now use a configure block as shown below.

Looking for the old rails_autoscale_agent docs? They're available on this branch.

Migrating from `judoscale-rails`

Since Rails Autoscale rebranded to Judoscale, these gems have been dual-published as judoscale-* and rails-autoscale-*. There's no need to migrate if you don't want to.

Configuration

All autoscaling configurations are handled in the Judoscale web UI, but there a few ways you can change the behavior of the adapters. Most apps won't need to change any of the adapter configurations, in which case an initializer is not required.

The sample code below uses "sidekiq" for worker adapter configuration, but the options are available for each worker adapter. Replace "sidekiq" with your job backend to use those config options.

# config/initializers/judoscale.rb
Judoscale.configure do |config|
  # Provide a custom logger.
  # Default: (Rails logger, if available, or a basic Logger to STDOUT)
  config.logger = MyLogger.new

  # Change the log_level for debugging or to quiet the logs.
  # See more in the "logging" section of the README.
  # Default: (defer to underlying logger)
  config.log_level = :debug

  # Interval between each metrics report to the Judoscale API.
  # Default: 10 seconds
  config.report_interval_seconds = 5

  # Worker metrics will only report up to 20 queues by default. If you have more than 20 queues,
  # you'll need to configure this setting for the specific worker adapter or reduce your number of queues.
  # Default: 20 queues
  config.sidekiq.max_queues = 30

  # Specify a list of queues to collect metrics from. This overrides the default behavior which
  # automatically detects the queues. If specified, anything not explicitly listed will be excluded.
  # When setting the list of queues, `queue_filter` is ignored, but `max_queues` is still respected.
  # Default: (queues detected automatically)
  config.sidekiq.queues = %w[low default high]

  # Filter queues to collect metrics from with a custom proc.
  # Return a falsy value (`nil`/`false`) to exclude the queue, any other value will include it.
  # Default: (queues that look like a UUID are rejected)
  config.sidekiq.queue_filter = ->(queue_name) { /custom/.match?(queue_name) }

  # Enables reporting for active (busy) workers so that downscaling can be
  # suppressed.
  # See https://judoscale.com/docs/long-running-jobs/.
  # Default: false
  config.sidekiq.track_busy_jobs = true

  # Disable reporting for this worker adapter.
  # Default: true
  config.sidekiq.enabled = false
end

Logging

judoscale-rails will use the Rails logger by default. Otherwise everything will log to STDOUT.

If you wish to use a different logger, you can set it on the configuration object:

# config/initializers/judoscale.rb
Judoscale.configure do |config|
  config.logger = MyLogger.new
end

The underlying logger controls the log level by default. In case of Rails apps, that's going to be defined by the log_level config in each Rails environment. So, if your app is set to log at INFO level, you will only see Judoscale INFO logs as well. Please note that this gem has very chatty debug logs, so if your app is set to DEBUG you will also see a lot of logging from Judoscale. Our debug logs look like this:

[Judoscale] [DEBUG] Some debug log message

If you find the gem too chatty with that setup, you can quiet it down with a more strict log level that only affects Judoscale logging:

# config/initializers/judoscale.rb
Judoscale.configure do |config|
  config.log_level = :info
end

Alternatively, set the JUDOSCALE_LOG_LEVEL environment variable on your Heroku app:

heroku config:set JUDOSCALE_LOG_LEVEL=info

If that's still too chatty for you, you can restrict it further:

# config/initializers/judoscale.rb
Judoscale.configure do |config|
  config.log_level = :warn
end

Troubleshooting

Once installed, you should see something like this in your development log:

[Judoscale] Reporter not started: JUDOSCALE_URL is not set

On the Heroku app where you've installed the add-on, run heroku logs -t | grep Judoscale, and you should see something like this:

[Judoscale] Reporter starting, will report every 10 seconds

If you don't see either of these, try running bundle again and restarting your Rails application.

You can see more detailed (debug) logging by setting JUDOSCALE_LOG_LEVEL on your Heroku app:

heroku config:set JUDOSCALE_LOG_LEVEL=debug

Reach out to help@judoscale.com if you run into any other problems.

Development

After checking out the repo, run bin/setup to install dependencies across all the judoscale-* libraries, or install each one individually via bundle install. Then, run bin/test to run all the tests across all the libraries, or inside each judoscale-* library, run bundle exec rake test. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install each gem onto your local machine, run bundle exec rake install.

To release a new version:

Use Conventional Commits, and release branches will be created automatically via Release Please. This updates the changelog and the version of judoscale-ruby.
On the release branch, run bin/sync-versions and bin/setup to update the versions of all gems.
After merging the release branch, run bin/release to publish all gems to Rubygems. If this fails with Tag vx.x.x does not point to current HEAD, wait for GH Actions to finish, then git fetch.

Note: We keep all gem versions in sync to provide a better developer experience for our users. Eventually we'll automate steps 2 & 3 above.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/judoscale/judoscale-ruby.

License

The gem is available as open source under the terms of the MIT License.

judoscale-delayed_job

Runtime