Coverband: production line-of-code coverage for Ruby applications

What Coverband measures that test coverage cannot

Test coverage tells you which lines a test suite touched. Coverband answers a different question: which lines ran in production, and how often. The README describes it as "a gem to measure production code usage, showing a counter for the number of times each line of code is executed." That counter is the product. If a method has a green line in a test report but zero runtime hits in Coverband, no real user has exercised it.

The intended audience is teams running Ruby applications in production, particularly Rails applications, who want to find dead code, understand which branches real traffic reaches, and decide what is safe to delete. The README states plainly that Coverband "is not intended for test code coverage; for that we recommend using SimpleCov." Treat that as a design boundary rather than a missing feature. A tool that instruments code inside a test process and a tool that instruments code inside a long-running server process have different constraints, and Coverband has chosen the second set.

The README lists the standard execution paths it supports out of the box: web requests, cron, background jobs and rake tasks. That breadth matters because a Rails app's real behaviour is spread across all of them, and a coverage tool that only sees HTTP requests would miss the scheduled job that runs once a night.

How the Redis-backed collection and reporting loop works

Coverband stores its coverage data in Redis. The README gives the endpoint resolution order explicitly: COVERBAND_REDIS_URL first, then REDIS_URL, then localhost:6379. The store can also be set directly in config/coverband.rb, which is what you do when you need a URL the environment variables do not carry.

Reporting is decoupled from the request path. The README notes that with older versions, projects reported to Redis through Rack or Sidekiq middleware, and that after Coverband 4.0 this "should no longer be required and could cause performance issues." Reporting now happens automatically in a background thread with no custom code. That architectural change is the main reason the gem can claim low overhead: the request thread records counters, and a separate thread flushes them.

A distinction the README makes repeatedly is between load-time and runtime usage. Rails eager loading executes class and method definitions at boot, so those lines register as hit even if no user ever triggers them. Coverband splits the two. The web UI exposes % runtime, defined as the percentage of runtime lines covered, where runtime lines are lines hit after the application has been eagerly loaded. It also reports Lines runtime, which the README defines as total lines minus uncoverable lines minus lines only hit during eager loading. A class definition can therefore show green while the method body beneath it shows red, and the README calls that out as expected behaviour.

The web UI itself is mountable, so reports can be shared across a team rather than living on one developer's machine. The README points to a hosted demo application and to a separate example repository for running it locally.

For Sinatra applications the README recommends requiring the gem as early as possible, directly in config.ru, because requiring it in an initializer may miss boot-up coverage.

Installing the coverband gem and getting a first report

Installation is a Gemfile entry plus a Redis instance. The README says to add the gem and run bundle install. The README also notes that Coverband should be required after Rails within the Gemfile, since the Railtie integration handles the rest.

gem 'coverband'

After bundle install, the gem needs to find Redis. The resolution order is COVERBAND_REDIS_URL, then REDIS_URL, then localhost:6379, so a local Redis on the default port needs no configuration at all. If your Redis requires TLS, the README says to use the rediss:// scheme instead of redis://, and that the Redis gem enables TLS automatically when it detects that scheme.

REDIS_URL=rediss://my-elasticache.abcdef.cache.amazonaws.com:6379

The same endpoint can be set in config/coverband.rb when you would rather not depend on environment variables. The README shows constructing the store with an explicit Redis client.

config.store = Coverband::Adapters::RedisStore.new(
  Redis.new(url: "rediss://my-elasticache-endpoint:6379")
)

For a Sinatra app the README recommends requiring Coverband in config.ru before the environment, so boot-up coverage is not lost.

require 'coverband'
require File.dirname(__FILE__) + '/config/environment'

use Coverband::BackgroundMiddleware
run ActionController::Dispatcher.new

Once collection is running, the web UI is where you read results. The README states that clearing coverage from the UI is disabled by default because it is "a dangerous operation in production," and is enabled with config.web_enable_clear. The alternative is the rake task documented for clearing coverage. If you enable the UI clear button, understand that the README describes it as wiping all collected data.

The eager-load problem and other places Coverband misleads

The most common misreading of a Coverband report is treating a green line as proof of use. The README addresses this directly: when viewing an individual file, a class or method definition line may appear green because the application eager loaded it, while still never being hit at runtime by actual users. If you skim the % covered column and ignore % runtime, you will conclude that code is alive when it is not. The runtime columns exist precisely because the aggregate number is misleading under eager loading.

A second constraint is the Redis dependency. There is no documented store other than Redis in the README. If your production environment has no Redis and you are not willing to add one, Coverband is the wrong tool. The TLS section exists because managed Redis services often require it, which tells you the maintainers expect production deployments, not just local experiments.

A third issue is scope. The README says Coverband monitors .rb files under app/, lib/ and config/, as long as they are not listed in config.ignore. Code outside those paths is not part of the picture by default. If your application keeps meaningful logic somewhere else, the report will not cover it unless configuration is changed, and the README does not document every path option in the excerpt available here.

Finally, the force-collection feature in the UI is described as triggering collection on the current webserver process. The README warns this is "useful in development but confusing in production environments where many ruby processes are usually running." Pressing it in production gives you one process's view, not the fleet's.

Coverband compared with SimpleCov and with instrumentation platforms

The README names SimpleCov as the tool to use for test coverage, and the difference in approach is fundamental. SimpleCov runs inside a test process, starts before the suite, and reports at the end of the run. Its subject is the test suite. Coverband runs inside your production processes, keeps a counter per line, and flushes periodically to a shared Redis store. Its subject is real traffic. Neither substitutes for the other, and the README's recommendation is not a hedge; it reflects that the two operate in different phases of the lifecycle with different failure modes.

The comparison with commercial application monitoring services is less clean. Those platforms typically report request-level traces, error rates and latency, and they sample. Coverband reports line-level execution counts, which is a finer grain than most APM products offer, but it has no tracing, no error aggregation and no latency measurement. If your question is why a request was slow, Coverband will not answer it. If your question is whether anyone still calls a particular private method, it will.

The web UI is also a different shape from an APM dashboard. It is a mountable Rack application showing overall coverage, per-file coverage, and per-file line detail, with the first-seen and last-activity data described in the README. Sharing it means mounting it inside your own application, not pointing at a vendor's console.

Maintenance, licence and the cost of keeping it running

The repository is not archived, and the last push was on 2026-09-18, which is recent. The most recent release listed is v6.2.0 from 2026-04-07, with v6.1.8 and v6.1.7 released the same day. The changelog lives in changes.md and the project also keeps a roadmap.md, so upgrade history is inspectable rather than implied.

The upgrade cost is dominated by the Redis contract and the Rails integration, not by the gem's own API. Since reporting moved into a background thread at 4.0, the README says custom Rack or Sidekiq middleware is no longer required and could cause performance issues. That means an application carrying old middleware from a pre-4.0 setup should remove it when upgrading, which is a code change rather than a version bump. The repository ships separate Gemfiles for Rails 7.0, 7.1, 7.2 and 8.0, which indicates the maintainers test against those lines and gives you a way to judge whether your Rails version is in scope.

Licence is MIT, per the repository metadata, which permits commercial use and modification with the usual attribution and warranty disclaimer. That is a permissive arrangement, but it is not legal advice; check how MIT interacts with your own distribution and compliance obligations.

The operational cost is a Redis instance and a background thread in every application process. On a large fleet, that is a real line item in both infrastructure and memory, and the README does not quantify it. If you are already running Redis for caching or jobs, the marginal cost is small. If you are not, the decision is about adding a stateful dependency to production.

Editorial conclusion

Adopt Coverband if you run a Ruby or Rails application in production, already operate Redis, and want to know which lines actually execute for real users rather than in tests. Do not adopt it as a replacement for SimpleCov, and do not adopt it if you cannot add a Redis dependency or tolerate a background reporting thread in your app processes. Before rolling it out, verify three things: that the Redis endpoint resolves in the order the README documents (COVERBAND_REDIS_URL, then REDIS_URL, then localhost:6379), that your deployment actually loads the gem after Rails in the Gemfile so the Railtie engages, and that your ignore configuration excludes vendor or generated code you do not want counted. The README does not document rollback, so plan how you would disable collection if the overhead or the data proves unhelpful.

Frequently asked questions

Official sources

1. danmayer/coverband on GitHub
2. License: MIT
3. Project website
4. README
5. Releases