¶ ↑
Key Performance IndicatorsThis gem helps you to track key indicators in your Rails app.
Have you even wanted to get daily reports with information:
-
how many users registered to my app?
-
how many users registered today?
-
what is a total revenue today?
-
how many times certain event occurred in app?
and so on?
This gem lets you define your application state reports with ease. Look:
¶ ↑
Installation¶ ↑
Rails 3.xAdd to your Gemfile:
gem "kpi"
and run in console in project directory:
$ bundle
¶ ↑
Rails 2.xThis gem is tested with Rails 2.3.8.
¶ ↑
Defining reportExample report in app/models/daily_kpi_report.rb:
class DailyKpiReport < KPI::Report def users_count result "Users count", User.count, :description => "Total users count" end def today_registrations_count result "Today registrations count", User.where("created_at > ?", @time - 24.hours) end def total_income result "Total income", Order.sum(:total), :unit => 'EUR' end def today_income result "Total income", Order.where(:created_at => today).sum(:total), :unit => 'EUR' end private def today ((time - 24.hours)..time) end end
Each defined method should return a KPI::Entry object with following accessors:
-
name
-
value
-
description
-
unit
A collection of KPI::Entry is available through Enuberable: Report#entries
It is important, if your indicator depends on current time (last 24 hours, last week), to rely on @time instance variable instead of Time.now. This lets you to generate report for every moment in history:
report = DailyKpiReport.new(:time => 2.days.ago)
¶ ↑
Merged reportsYou can create merged report from two or more reports of the same type. Look at examples:
> today = DailyKpiReport.new > today.users_count.value # => 20 > today.today_income.value # => 350 > yesterday = DailyKpiReport.new(:time => 1.day.ago) > yesterday.users_count.value # => 16 > yesterday.today_income.value # => 250 > diff = KPI::MergedReport.new(today, yesterday) do |today, yesterday| > KPI::Entry.new "$$ (change)", today.value - yesterday.value > end > avg = KPI::MergedReport.new(today, yesterday) do |*entries| > KPI::Entry.new "$$ (avg)", entries.map(&:value).inject(:+) / entries.size > end > diff.users_count.value # => 4 > avg.today_income.value # => 300 > avg.today_income.unit # => "EUR"
More reports can be passed to constructor of Merged report:
avg = KPI::MergedReport.new(week_now, week_last, week_next_to_last) do |*entries| # ... end
¶ ↑
Other-
You can override report title by overriding title method in report:
class DailyKpiReport < KPI::Report def title; "Your daily report"; end # ... end
-
You can use Whenever gem to generate periodic reports
-
Private methods are not considered as indicator methods and can be used as helper methods:
class WeeklyReport < KPI::Report # ... private def week_range t_prev_mon_begin = time - (time.wday-1)*24*60*60 - time.hour*60*60 - time.min*60 - time.sec t_next_sun_end = t_prev_mon_begin + 7*24*60*60 - 1 (t_prev_mon_begin..t_next_sun_end) end end
¶ ↑
Todo-
Generators for configuration and reports
-
Database persistence - storing reports in different databases: PostgreSQL & Mongo prioritized - should be done in external gems
-
Support for “result” helper in block passed to constructor of MergedReport
-
Remove ActiveSupport requirement
¶ ↑
Contributing to KPI-
Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet
-
Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it
-
Fork the project
-
Start a feature/bugfix branch
-
Commit and push until you are happy with your contribution
-
Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.
-
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
¶ ↑
CopyrightCopyright © 2011 Artur Roszczyk. See LICENSE.txt for further details.