danmayer / coverband翻译 / 编辑

最近提交:1天前
创建时间:2013.11.04

语言构成

Ruby98.3%
Gnuplot1.7%

README

Coverband

Build Status: Build Status

Key FeaturesCoverband DemoHow To UseInstallationConfigurationUsageLicenseChange Log / Roadmap

A gem to measure production code usage, showing each line of code that is executed. Coverband allows easy configuration to collect and report on production code usage. It can be used as Rack middleware, wrapping a block with sampling, or manually configured to meet any need (like usage during background jobs).

Note: Coverband is not intended for test code coverage, for that just check out SimpleCov.

Key Features

The primary goal of Coverband is giving deep insight into your production runtime usage of your application code, while having the least impact on performance possible.

  • Low performance overhead
  • Various controls from sampling, data collection rate, etc to further control performance
  • Ignore directories to avoid overhead data collection on vendor, lib, etc.
  • Development mode, offers deep insight of code usage details (number of LOC execution during single request, etc) during development.
  • Easy setup for any Ruby Rack based web framework (Rails, Sinatra, etc)
  • Allows for integration with any other Ruby application flows (background jobs, crons, scripts)

Coverband Demo

Take Coverband for a spin on the live Heroku deployed Coverband Demo. The full source code for the demo is available to help with configuration and understanding of basic usage.

How To Use

Below is my Coverband workflow, which hopefully will help other best use this library.

  • install coverband
  • start your app and hit a few endpoints
  • validate data collection and code coverage with rake coverband:coverage
  • test setup in development (hit endpoints and generate new report)
  • deploy to staging and verify functionality
  • deploy to production and verify functionality
  • every 2 weeks or so, with major releases
    • clear old coverage: rake coverband:clear
    • deploy and verify coverage is matching expectations
  • COVERAGE DRIFT
    • we are working to address this early in the 3.0.x feature set
    • if you never clear you have lines of code drift from when they were recorded
    • if you clear on every deploy you don't capture as useful of data
    • there is a tradeoff on accuracy and data value
    • I recommend clearing after major code changes, significant releases, or some regular schedule.

Example Output

Since Coverband is Simplecov output compatible it should work with any of the SimpleCov::Formatter's available. The output below is produced using the default Simplecov HTML formatter.

Index Page image

Details on a example Sinatra app image

Installation

Follow the below section to install and configure Coverband.

coverband installation

Prerequisites

  • Coverband 3.0 requres Ruby 2.3+

Gem Installation

Add this line to your application's Gemfile:

gem 'coverband'

And then execute:

$ bundle

Or install it yourself as:

$ gem install coverband

Configuration

After you have the gem, you will want to setup the needed integration:

  1. Coverband Config File Setup
  2. Configure Rake
  3. Insert Coverband Rack Middleware

1. Coverband Config File Setup

You need to configure cover band you can either do that passing in all configuration options to Coverband.configure in block format, or a simpler style is to call Coverband.configure with nothing while will load config/coverband.rb expecting it to configure the app correctly. Below is an example config file for a Rails 5 app:

#config/coverband.rb
Coverband.configure do |config|
  config.root              = Dir.pwd
  config.store             = Coverband::Adapters::RedisStore.new(Redis.new(url: ENV['REDIS_URL'])) if defined? Redis
  config.ignore            = %w[vendor .erb$ .slim$]
  # add paths that you deploy to that might be different than your local dev root path
  config.root_paths        = []

  # reporting frequency, how often coverage data is sent to the store
  # if you are debugging changes to coverband I recommend setting to 100.0
  config.reporting_frequency = Rails.env.production? ? 1.0 : 100.0
  config.logger              = Rails.logger

  # config options false, true, or 'debug'. Always use false in production
  # true and debug can give helpful and interesting code usage information
  # they both increase the performance overhead of the gem a little.
  # they can also help with initially debugging the installation.
  # config.verbose           = 'debug'
end

2. Configure Rake

Either add the below to your Rakefile or to a file included in your Rakefile such as lib/tasks/coverband.rake if you want to break it up that way.

require 'coverband'
Coverband.configure
require 'coverband/utils/tasks'

This should give you access to a number of Coverband tasks

rake -T coverband
rake coverband:clear         # reset coverband coverage data
rake coverband:coverage      # report runtime coverband code coverage

3. Configure Rack to use the Coverband middleware

The middleware is what makes Coverband gather metrics while a webapp app runs.

For Rails apps

There are a number of options for starting Coverband and when to insert it into your middleware stack. At the moment this is my recommendation, to ensure you capture usage data on any files required by other plugins.

Then add the middleware to your Rails rake middle ware stack:

# config/application.rb
[...]

module MyApplication
  class Application < Rails::Application
    [...]

    # Coverband needs to be setup before any of the initializers to capture usage of them
    require 'coverband'
    Coverband.configure
    config.middleware.use Coverband::Middleware

    # if one uses before_eager_load as I did previously
    # any files that get loaded as part of railties will have no coverage
    config.before_initialize do
       Coverband.start
    end
  end
end

For Sinatra apps

For the best coverage you want this loaded as early as possible. I have been putting it directly in my config.ru but you could use an initializer, though you may end up missing some boot up coverage.

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

require 'coverband'
Coverband.configure

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

Verify Correct Installation

  • boot up your application
  • run rake coverband:coverage this will show app initialization coverage
  • run app and hit a controller (hit at least +1 time over your config.startup_delay setting default is 0)
  • run rake coverband:coverage and you should see coverage increasing for the endpoints you hit.

Installation Session

These are the steps taken to install and configure Coverband

rails new coverage_example
cd coverage_example
atom .

# open Gemfile, add lines
gem 'redis'
gem 'coverband', '>= 3.0.0.alpha2', require: false

bundle install

# create config/coverband.rb
# copy the config from the readme
# If you don't set REDIS_URL, remove that to use default localhost

# Make some code so we can look at the coverage
rails generate scaffold blogs
rake db:migrate

# open Rakefile, add lines
require 'coverband'
Coverband.configure
require 'coverband/utils/tasks'

# verify rake
rake -T coverband

# configure config/application.rb
# copy lines from readme

# start up your app
rake coverband:coverage
# view boot up coverage

rails s

open http://localhost:3000/blogs

# click around some to trigger usage

# view updated coverage
rake coverband:coverage

Usage

Example apps

View Coverage

You can view the report different ways, but the easiest is the Rake task which opens the SimpleCov formatted HTML.

rake coverband:coverage

This should auto-open in your browser, but if it doesn't the output file should be in coverage/index.html

Clear Coverage

If your code has changed and your coverage line data doesn't seem to match run time. You probably need to clear your old line data... You will need to run this in the environment you wish to clear the data from.

rake coverband:clear

Automated Clearing Line Coverage Data

After a deploy where code has changed significantly. This is to avoid coverage drift

The line numbers previously recorded in Redis may no longer match the current state of the files. If being slightly out of sync isn't as important as gathering data over a long period, you can live with minor inconsistency for some files.

As often as you like or as part of a deploy hook you can clear the recorded Coverband data with the following command.

# defaults to the currently configured Coverband.configuration.redis
Coverband::Reporter.clear_coverage
# or pass in the current target redis
Coverband::Reporter.clear_coverage(Redis.new(:host => 'target.com', :port => 6789))

You can also do this with the included rake tasks.

Manual Configuration (for example for background jobs)

It is easy to use Coverband outside of a Rack environment. Make sure you configure Coverband in whatever environment you are using (such as config/initializers/*.rb). Then you can hook into before and after events to add coverage around background jobs, or for any non Rack code.

For example if you had a base Resque class, you could use the before_perform and after_perform hooks to add Coverband

require 'coverband'
Coverband.configure
Coverband.start

def after_perform(*args)
  if @recording_samples
     Coverband::Collectors::Coverage.instance.report_coverage
  end
end

or sidekiq middleware:

  # capture code usage in background jobs
  class CoverbandMiddleware
    def call(_worker, _msg, _queue)
      Coverband.start
      yield
    ensure
      Coverband::Collectors::Coverage.instance.report_coverage
    end
  end
  
  ...
  chain.add Sidekiq::CoverbandMiddleware

In general you can run Coverband anywhere by using the lines below. This can be useful to wrap all cron jobs, background jobs, or other code run outside of web requests. I recommend trying to run both background and cron jobs at 100% coverage as the performance impact is less important and often old code hides around those jobs.

require "coverband"
Coverband.configure
Coverband.start

# do whatever
Coverband::Collectors::Coverage.instance.report_coverage

Manual Configuration (for cron jobs / Raketasks)

A question about supporting cron jobs and Rake tasks was asked by @ndbroadbent, there are a couple ways to go about it including his good suggestion.

He extended the Coverband Rake tasks by adding lib/tasks/coverband.rake with support to wrap all Rake tasks with coverband support.

require 'coverband'
Coverband.configure
require 'coverband/utils/tasks'

# Wrap all Rake tasks with Coverband
current_tasks = Rake.application.top_level_tasks
if current_tasks.any? && current_tasks.none? { |t| t.to_s.match?(/^coverband:/) }
  current_tasks.unshift 'coverband:start'
  current_tasks.push 'coverband:stop_and_save'
end

namespace :coverband do
  task :start do
    Coverband.start
  end

  task :stop_and_save do
    Coverband::Collectors::Coverage.instance.report_coverage
  end
end

That is a interesting approach and if you Run all your cron jobs as Rake tasks might work well for you. In a production application where we run Coverband, we run all of our Cron jobs with the rails runner script. We took this alternative approach which will wrap all runner jobs with Coverband recording, by creating lib/railties/coverage_runner.rb.

require 'rails'

# Capture code coverage during our cron jobs
class CoverageRunner < ::Rails::Railtie
  runner do
    Coverband.start
    at_exit do
      Coverband::Collectors::Coverage.instance.report_coverage
    end
  end
end

safe_reload_files: Forcing Coverband to Track Coverage on Files loaded during boot

The way Coverband is built it will record and report code usage in production for anything required or loaded after calling Coverband.start. This means some of Rails initial files and Gems are loaded before you can generally call Coverband.start for example if you use the application.rb to initialize and start Coverband, that file will be reported as having no coverage, as it can't possibly start Coverband before the file is loaded.

The safe_reload_files reload option in the configuration options can help to ensure you can track any files you want regardless of them loading before Coverband. For example if I wanted to show the coverage of config/coverband.rb which has to be loaded before calling Coverband.start I could do that by adding that path to the safe_reload_files option.

Coverband.configure do |config|
  # ... a bunch of other options
  # using the new safe reload to enforce files loaded
  config.safe_reload_files = ['config/coverband.rb']
end

By adding any files above you will get reporting on those files as part of your coverage runtime report.

Collecting Gem / Library Usage

By default Coverband has assumed you are trying to track your application code usage not all the supporting framework and library (Gems) code usage. There has been some good points and reasons folks want to track library usage, for example to find out which Gems they aren't actually using in production. See some of the discussion on issue 21.

  • Using the Tracepoint Collector
    • just make sure to set Coverband.configuration.include_gems = true in your config options
    • note by tracking all the additional usage this can have significant performance impacts of the Tracepoint implementation
  • Using the Coverage Collector
    • use the safe_reload_files feature to add the path of all gem files you wish to track
    • --- or ---
    • ensure you call Coverband.start before loading all your gems
      • while possible this is currently hard as Rails and most environments load your whole Gemfile
      • looking for an improve and easier way to support this.

Verbose Debug / Development Mode

Note: To debug issues getting coverband working. I recommend running in development mode, by turning verbose logging on config.verbose = true and passing in the Rails.logger config.logger = Rails.logger to the Coverband config. This makes it easy to follow in development mode. Be careful to not leave these on in production as they will affect performance.


If you are trying to debug locally wondering what code is being run during a request. The verbose modes config.verbose = true and config.verbose = 'debug' can be useful. With true set it will output the number of lines executed per file, to the passed in log. The files are sorted from least used file to most active file. I have even run that mode in production without much of a problem. The debug verbose mode outputs both file usage and provides the number of calls per line of code. For example if you see something like below which indicates that the application_helper has 43150 lines executed. That might seem odd. Then looking at the breakdown of application_helper we can see that line 516 was executed 38,577 times. That seems bad, and is likely worth investigating perhaps memoizing or cacheing is required.

config.verbose = 'debug'

coverband file usage:
  [["/Users/danmayer/projects/app_name/lib/facebook.rb", 6],
  ["/Users/danmayer/projects/app_name/app/models/some_modules.rb", 9],
  ...
  ["/Users/danmayer/projects/app_name/app/models/user.rb", 2606],
  ["/Users/danmayer/projects/app_name/app/helpers/application_helper.rb",
  43150]]

file:
  /Users/danmayer/projects/app_name/app/helpers/application_helper.rb =>
  [[448, 1], [202, 1],
  ...
 [517, 1617], [516, 38577]]

Writing Coverband Results to S3

If you add some additional Coverband configuration your coverage html report will be written directly to S3, update config/coverband.rb like below.

  # configure S3 integration
  config.s3_bucket = 'coverband-demo'
  config.s3_region = 'us-east-1'
  config.s3_access_key_id = ENV['AWS_ACCESS_KEY_ID']
  config.s3_secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']

Viewing / Hosting S3 Coverband results in app

Beyond writing to S3 you can host the S3 file with a build in Sintatra app in Coverband. Just configure your Rails route config/routes.rb

Rails.application.routes.draw do
  # ... lots of routes
  mount Coverband::Reporters::Web.new, at: '/coverage'
end

NOTE: ADD PASSWORD PROTECTION OR YOU CAN EXPOSE ALL YOUR SOURCE CODE

It is easy to add some basic protect around the coverage data, below shows how you can use devise or basic auth, by adding a bit of code to your config/routes.rb file.

# protect with existing Rails devise configuration
devise_constraint = lambda do |request|
  request.env['warden'] && request.env['warden'].authenticate? && request.env['warden'].user.admin?
end

# protect with http basic auth
# curl --user foo:bar http://localhost:3000/coverage
basic_constraint = lambda do |request|
  return true if Rails.env.development?
  if ActionController::HttpAuthentication::Basic.has_basic_credentials?(request)
    credentials = ActionController::HttpAuthentication::Basic.decode_credentials(request)
    email, password = credentials.split(':')

    email == 'foo' && password = 'bar'
  end
end

Rails.application.routes.draw do
  # ... lots of routes
  constraints basic_constraint do
    mount Coverband::Reporters::Web.new, at: '/coverage'
  end
end

Conflicting .Simplecov: Issue with Missing or 0% Coverage Report

If you use SimpleCov to generate code coverage for your tests. You might have setup a .simplecov file to help control and focus it's output. Often the settings you want for your test's code coverage report are different than what you want Coverband to be reporting on. Since Coverband uses the SimpleCov HTML formatter to prepare it's report.

So if you had something like this in a .simplecov file in the root of your project, as reported in issue 83

require 'simplecov'

SimpleCov.start do
  add_filter 'app/admin'
  add_filter '/spec/'
  add_filter '/config/'
  add_filter '/vendor/'
  add_filter 'userevents'
end

You could see some confusing results... To avoid this issue Coverband has a Rake task that will ignore all Simplecov filters.

rake coverband:coverage_no_filters

This will build the report after disabling any .simplecov applied settings.

Contributing To Coverband

If you are working on adding features, PRs, or bugfixes to Coverband this section should help get you going.

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Make sure all tests are passing (run bundle install, make sure Redis is running, and then execute rake test)
  6. Create new Pull Request

Tests & Benchmarks

If you submit a change please make sure the tests and benchmarks are passing.

  • run tests: rake
  • view test coverage: open coverage/index.html
  • run the benchmarks before and after your change to see impact
    • rake benchmarks

Known Issues

  • total fail on front end code, because of the precompiled template step basically coverage doesn't work well for erb, slim, and the like.
    • related it will try to report something, but the line numbers reported for ERB files are often off and aren't considered useful. I recommend filtering out .erb using the config.ignore option.
  • If you have SimpleCov filters, you need to clear them prior to generating your coverage report. As the filters will be applied to Coverband as well and can often filter out everything we are recording.
  • coverage doesn't show for Rails config/application.rb or config/boot.rb as they get loaded when loading the Rake environment prior to starting the Coverage library.

Debugging Redis Store

What files have been synced to Redis?

Coverband.configuration.store.covered_files

What is the coverage data in Redis?

Coverband.configuration.store.coverage

License

This is a MIT License project... See the file license.txt for copying permission.

讨论区

说说你的看法