metrify

= metrify

Via the creation of a YAML file specifying statistics to track, and an extension class to specify the way to find those statistics, Metrify provides an easy way to aggregate and display statistics over time. The minimal unit of aggregation is 1 day, and provided input times are set to midnight before calculations.

If Highcharts is used in your project, functionality is included to immediately use a default chart.

Install metrify:

$ gem install metrify

In your environment.rb file, add to Rails::Initializer.run do |config| block:

config.gem "metrify"

To add the ability for a class to generate aggregated statistics over time, perform the following steps:

1. Create .yml file defining metrics, and optional metric grouping filters
2. Include module functionality in class that will calculate metrics, and provide a method for each metric to be calulated.

You can create multiple classes that use this module. By default, the YML file loaded for the class will be on /config/(classname)_metrify.yml. Otherwise, specify the filename as an argument when calling "acts_as_metrify" within the class (shown below). RAILS_ROOT will be prepended.

Example YML file:

stats: element_a_count: display_name: Element A Count value_type: currency precision: 2 show_variance: true element_b_count: display_name: Element B Count element_1_count: display_name: Element 1 Count element_cat_count: display_name: Cat Count
element_dog_count: display_name: Dog Count

stat_order: [element_a_count, element_b_count, element_1_count, element_dog_count, element_cat_count]

filters: type: numbers: set: [element_1_count] description: 'Numbers' letters: set: [element_a_count, element_b_count] description: 'Letts' animals: set: [element_cat_count, element_dog_count] description: 'Animals' furriness: furry: set: [element_cat_count, element_dog_count] description: 'Furry' not_furry: set: [element_1_count, element_a_count, element_b_count, element_c_count] description: 'Not Furry'

Example Class, implementing calculation methods for metrics defined in YML file:

class MetricsClass < ActiveRecord::Base include Metrify acts_as_metrify

class << self
  def element_a_count(start_date, end_time)
    # Code calculating number (probably a SQL query using start and end dates) 
  end

  ...(more methods, one for each defined metric)

end

end

The class will need the minimal columns defined in this example migration:

create_table :metrics_class, :force => true do |t| t.datetime :finish_time t.integer :number_of_hours t.string :stat_hash end

This will grant the following functionality to the MetricsClass defined above:

MetrifiedClass.element_a_count_name # => "Element A Count"

example_finish_time = Time.zone.now.midnight # be sure to use ActiveRecord Time.zone, not Time, so lookups are correct number_of_hours = 7*24 historical_values = MetrifiedClass.historical_values(example_finish_time, 10, :day) # => returns array of 10 aggregations, each over 1 day, older values listed first, ended at the most recent aggregation date (example_finish_time). (:day, :month options) historical_values[0].element_a_count # => generated for the given time frame using the 'element_a_count' method implemented in MetricsClass

MetrifiedClass.stat_names # => stat names available, provided in YML file

filters = {'type' => ['numbers', 'letters'], 'furriness' => ['furry', 'not_furry']} MetrifiedClass.stat_names(filters) # => return only stat names available from filters stat_names = {'element_1_count', 'element_dog_count'} MetrifiedClass.sorted_stat_names() # => return stat names provided in order, using "stat_order" specified in YAML file. Alphabetical if not specified

#Any of these not specified in YAML file will return nil MetrifiedClass.value_type('element_a_count') # => currency - returns type of value (currently only currency). This is useful for knowing how to display MetrifiedClass.show_variance('element_a_count') # => true - whether or not this value's % +/- change over last time period should be displayed MetrifiedClass.value_precision('element_a_count') # if specified in YML file, will round floats using provided precision

MetrifiedClass.sorted_stat_names(['element_dog_count', 'element_cat_count', 'element_b_count']) # => ['element_b_count', 'element_dog_count', 'element_cat_count'] ordered as defined by stat_order in yml, alphabetical if not configured

== Using with Highcharts for instant views

Assuming your application is configured to use Highcharts, optional controller, view, and helper components are included to provide charts with filters. To use:

1. Include MetrifyController module in controller and implement 'metrified_class' and 'set_classname'.
2. Include partials (graph and/or chart) in views
3. Include route in routes.rb as such (where controller for 'metrified' model is dashboard): map.dashboard '/dashboard/:action.:format', :controller => 'dashboard', :action => 'index'

Example Controller:

class DashboardController < ApplicationController include MetrifyController

def metrify_model
  Dashboard     # Dashboard is the class using the Metrify module
end

end

Example View for graph:

.metrify_graph {width:auto;height:400px;background-color:white}

<%= render :partial => "metrify/graph" %>

Depending on the jscript framework you are using, you will also want to define an new instance of Breakdown, defining the Ajax method appropriately:

Prototype:

Mootools:

Example View for chart:

.metrify_chart {width: auto; background: white; color: black; overflow:auto;} .metrify_chart thead td {font-weight:bold;background-color:#ddd;} .metrify_chart thead td a {color:#116;} .metrify_chart table, th, td {border: 1px solid #ccc; border-width:0 1px 1px 0;} .metrify_chart tr:first-child td {border-top-width:1px;} .metrify_chart td:first-child {border-left-width:1px;} .metrify_chart td {padding:5px;}

<%= render :partial => "metrify/chart" %>

== Using Mailer View

A simple view for displaying multiple metrics charts in a email is also available. To use, specify the 'metrified' class and create a hash of charts you would like delivered, specifying the chart name and the chart:

@metrified_class = MetrifiedClass

@charts = { "Hourly", MetrifiedClass.historical_values(end_time, 168, :hour), "Daily", MetrifiedClass.historical_values(end_time, 7, :day), "Weekly", MetrifiedClass.historical_values(end_time, 52, :week), "Monthly", MetrifiedClass.historical_values(end_time, 12, :month) }

Then, include the partial in your Mailer's view:

<%= render :partial => 'metrify/mailer_charts_summary' %>

== Note on Patches/Pull Requests

• Fork the project.
• Make your feature addition or bug fix.
• Add tests for it. This is important so I don't break it in a future version unintentionally.
• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
• Send me a pull request. Bonus points for topic branches.

== Copyright

Copyright (c) 2010 Stephen Abrams. See LICENSE for details.