schrodingersbox/meter_cat README

This Rails engine makes monitoring the usage history of your Rails environment easier. It provides meters, similar to the odometer in a car, which can be incremented when significant actions happen in your app, and are recorded on a daily basis.

Meters are managed in RAM and periodically flushed to DB after a configurable amount of time, when the calendar day rolls over, or when the process exits.

Some examples of useful meters would be number of users created, number of emails sent, or other events particular to your application. Even in cases where the equivalent value could be determined with a count query, it can still be more efficient to look up a set of meter values, rather than run a bunch of count queries.

Getting Started

1. Add this to your Gemfile and bundle install

   gem 'meter_cat'
   

2. Add this to your config/routes.rb

   mount MeterCat::Engine => '/meter_cat'
   

3. Install and run migrations

   rake meter_cat:install:migrations
   rake db:migrate db:test:prepare
   

4. Generate some random data

   rake meter_cat:random[my_test,0,100,365]

5. Restart your Rails server

6. Visit http://yourapp/meter_cat in a browser for an HTML meter report

Configuration

All configuration should go in config/initializers/meter_cat.rb.

  MeterCat.configure do |config|

    config.layout = 'meters'
    config.expiration = 60

    config.ratio( :failed_to_create_ratio, :login_failed, :user_created )
    config.percentage( :failed_to_create_percentage, :login_failed, :user_created )
    config.sum( :failed_plus_create, [ :login_failed, :user_created ] )

    config.to = 'ops@schrodingersbox.com'
    config.from = 'ops@schrodingersbox.com'
    config.subject = "#{Rails.env.upcase} MeterCat Report"
    config.mail_days = 7

    config.authenticate_with do
      warden.authenticate! scope: :user
    end

    config.authorize_with do
      redirect_to main_app.root_path unless current_user.try(:admin?)
    end

  end

How To

Increment A Meter

The easiest way is to call MeterCat.add.

    MeterCat.add( :any_name_you_like )

You can also optionally pass a value and date.

    MeterCat.add( :any_name_you_like, value = 1, created_on = Date.today )

Set A Meter

The easiest way is to call MeterCat.set.

    MeterCat.set( :any_name_you_like )

You can also optionally pass a value and date.

    MeterCat.set( :any_name_you_like, value = 1, created_on = Date.today )

This is useful where you want to record a single value for the day, such as from a daily cron job.

Add Calculated Values

Calculated values (ratios, percentages, and sums) can be defined in config/initializers/meter_cat.rb

  MeterCat.configure do |config|
    config.ratio( :failed_to_create_ratio, :login_failed, :user_created )
    config.percentage( :failed_to_create_percentage, :login_failed, :user_created )
    config.sum( :failed_plus_create, [ :login_failed, :user_created ] )
  end

Generate Development Data

rake meter_cat:random[name, min, max, days] can be used to generate random data for development.

The arguments are defined as follows:

• name = String, Any string up to 64 characters long
• min = Integer, Minimum generated value
• max = Integer, Maximum generated value
• days = Integer, Days prior to date to generate values for

e.g. The following command will generate data for :my_test with value between 0 and 100 for the last year.

    rake meter_cat:random[my_test,0,100,365]

Configure Email Settings

Create or add to config/initializers/meter_cat.rb

MeterCat.configure do |config|
  config.to = 'ops@schrodingersbox.com'
  config.from = 'ops@schrodingersbox.com'
  config.subject = "#{Rails.env.upcase} MeterCat Report"
end

Email A Meter Report

You can email a meter report using rake:

rake meter_cat:mail

You can email a meter report in code:

MeterCat.mail

Require authentication

Create or add to config/initializers/meter_cat.rb

MeterCat.configure do |config|
  config.authenticate_with do
    warden.authenticate! scope: :user
  end
end

Require authorization

Create or add to config/initializers/meter_cat.rb

MeterCat.configure do |config|
  config.authorize_with do
    redirect_to main_app.root_path unless current_user.try(:admin?)
  end
end

Apply a custom layout

Create or add to config/initializers/meter_cat.rb

MeterCat.configure do |config|
  config.layout = 'admin'
end

Get Started Developing

1. cp spec/dummy/config/passwords.yml.sample spec/dummy/config/passwords.yml
   
2. rake app:db:create app:db:migrate app:db:test:prepare

Reference

• Getting Started with Engines
• Testing Rails Engines With Rspec
• How do I write a Rails 3.1 engine controller test in rspec?
• Best practice for specifying dependencies that cannot be put in gemspec?
• Clarifying the Roles of the .gemspec and Gemfile
• The Semi-Isolated Rails Engine
• FactoryGirl
• Add Achievement Badges to Your Gem README
• Publishing your gem

History

• Version 0.0.8 = Rails 4 compatible
• Version 5.0.0 = Rails 5 compatible