ramaze-fnordmetric 0.0.9

data/.gitignore

@@ -0,0 +1,16 @@
+# Ignore build related files
+doc
+pkg/*.gem
+.bundle
+.gems
+vendor
+
+# Ignore common crap
+.DS_Store
+Thumbs.db
+
+# Keep those funky gitkeep files
+!.gitkeep
+coverage
+
+Gemfile.lock

data/.rvmrc

@@ -0,0 +1 @@
+rvm use --create 1.9.2@ramaze_fnordmetric

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2012, Michel Blanc / ERASME
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,321 @@
+Ramaze::Helper::Fnordmetric
+===========================
+
+[![Build Status](https://secure.travis-ci.org/leucos/ramaze-fnordmetric.png?branch=master)](http://travis-ci.org/leucos/ramaze-fnordmetric)
+
+__A [Ramaze][1] helper that makes it easy to use [Fnordmetric][2] in your
+  Ramaze web-applications__
+
+----
+
+Features
+--------
+
+
+Usage
+-----
+
+### Using in your code ###
+
+#### Loading the helper ####
+
+Since this is a Ramaze helper, you can use it just like another helper :
+
+    class Users < Controller
+      helper :fnordmetric
+      ...
+    end
+
+#### Redis configuration ####
+
+Since Fnordmetric uses Redis, you can configure the server to use using traits
+in your controller :
+
+trait :fnord_redis_url => "redis://redis.example.com:6332"
+
+If not, Fnordmetric will use the default redis stuff (`redis://localhost:6379`).
+
+You can also set how long the helper internal structures (timers, see below) 
+will be kept in Redis using `trait :fnord_helper_key_ttl => 3600`
+
+By default, they will be kept `Innate::Session.options.ttl` seconds.
+
+#### Events and sessions ####
+
+All Fnordmetric events are linked to the session (`innate.sid`) of the currently
+handled request. This makes it easy to track which events occured in which
+session.
+
+If you're dealing with authenticated users, you might want to associate a name
+to the user sessions so your Fnormetric app displays a user name instead of a
+session id :
+
+    # Associates a user name to the current innate.sid
+    set_name("#{user.name} #{user.surname}")
+
+You can also set a picture for the current session, using the gravatar helper for instance :
+
+    # Fnordmetric will display a picture next to the user
+    set_picture(gravatar(user.email.to_s)) if user.email
+
+### Sending an event ###
+
+To send an event to Fnordmetric, use the `event` method :
+
+    event(:user_login, :is_admin => "yes")
+
+### Recording page views
+
+You can record a pageview Fnordmetric event using `pageview` :
+
+    pageview '/some/page/path'
+
+Since all events are sent along with the current session id, this leaves a nice 
+per-session audit trail.
+
+### Measuring execution time for code section ###
+
+If you want to measure the time taken for a particular section of code, you can start a timer before your code, and stop it when you're done.
+
+    # Measuring code execution times
+    # We just start a stopwatch
+    push_timer(:performance, :field => :whatever_you_want_here)
+
+    # Oh well, I'm doing something here that needs to be measured
+    sleep(1)
+
+    # Let's stop the stopwatch
+    # This automatically sends an event to Fnordmetric
+    pop_timer
+
+`push_timer` and `pop_timer` can be nested :
+
+    def login
+      @title = "Connect"
+
+      redirect_referer if logged_in?
+      return unless request.post?
+
+      # Let's push a timer to get the overall login timings
+      # We add some data to the event so we wan easily see what piece of code
+      # is involved in our Fnordmetric app
+
+      push_timer(:timing_data, :controller => :user, :method => :login)
+      user_login(request.subset(:email, :password))
+
+      # This is good, but we also want to see how much the following piece of
+      # code takes too
+
+      if logged_in?
+        # Ok, now let's say we want to pre-fill some kind of cache for the user
+        # and measure how long it takes
+
+        # Let's fire another stopwatch
+        push_timer(:timing_data, :code => :cache_retrieval)
+        fill_cache(user)
+
+        # Let's stop the last stopwatch, and send the event
+        pop_timer
+
+      else
+        flash[:error] = "Can't log in, invalid data"
+      end
+
+      # Ok, we've done our job, let's stop the first stopwatch we started and 
+      # send metric
+      pop_timer
+
+      redirect_referrer
+    end
+
+Easy peasy lemon squeezy.
+
+### Measuring execution time for block ###
+
+But the helper comes with block (like in &) timing methods too, so we can meke 
+the above code event simpler, replacing the inner `push_timer` and `pop_timer` 
+calls with the `times` method :
+
+        # Ok, now let's say we want to pre-fill some kind of cache for the user
+        # and measure how long it takes
+
+        # Let's fire another stopwatch
+        times(:timing_data, :code => :cache_retrieval) do
+          fill_cache(user)
+        end
+
+Easier than before. The block passed to `times` will be measured.
+
+### Measuring execution time for an action (controller method) ###
+
+While the above block thing is nice, it could be great to do the same for a 
+whole method. The helper can do this too with the `clock` method :
+
+    def login
+      @title = "Connect"
+
+      # code code ...
+
+      redirect_referrer
+    end
+    clock :login, :timing_data, :controller => :user,
+
+This will automagically measure execution time for the :login method (first
+arg), sending an event named `timing_data` with some arbitrary argument 
+(controller in our case). 
+
+Note that `clock` always sets the `:method` key value in the arguments sent in 
+the event, so the tracked method is recorded in Fnordmetric.
+
+Summing up, we can user all those methods like that :
+
+    def login
+      @title = "Connect"
+
+      redirect_referer if logged_in?
+      return unless request.post?
+
+      # Log in this fellow
+      user_login(request.subset(:email, :password))
+
+      # This is good, but we also want to see how much the following piece of
+      # code takes too
+
+      if logged_in?
+        # Hey, nice, user is logged in. Let'a associate name and picture as 
+        # shown already
+
+        set_name("#{user.name} #{user.surname}")
+        set_picture(gravatar(user.email.to_s)) if user.email
+
+        # Ok, now let's say we want to pre-fill some kind of cache for the user
+        # and measure how long it takes
+
+        # Let's fire another stopwatch
+        push_timer(:timing_data, :code => :cache_retrieval)
+        fill_cache(user)
+
+        # Let's stop the last stopwatch, and send the event
+        pop_timer
+
+      else
+        flash[:error] = "Can't log in, invalid data"
+      end
+
+      # Ok, we've done our job, let's stop the first stopwatch we started and 
+      # send metric
+      pop_timer
+
+      redirect_referrer
+    end
+    # We want to measure the whole method
+    clock :login, :timing_data, :controller => :user,
+
+
+### Measuring all your actions time ###
+
+Using Ramaze before/after controller facilities, you can easily measure 
+everything, send events before each method onvocation, etc...
+
+    class Controller < Ramaze::Controller
+      layout :default
+      helper :fnordmetric
+
+      # Let's record all pageviews for all controllers     
+      before_all do
+        pageview request.env['REQUEST_PATH']
+      end
+
+### Starting the Fnordmetric app ###
+
+Ok, now that we measure everything we want, how do we see the stuff ?
+Well, you have to write a Fnordmetric app.
+
+This is quite simple, and is explained in detail in the [Fnordmetric][2] docs.
+
+Here is a small example the show pages views :
+
+
+    #!/usr/bin/env ruby
+    #
+    require 'fnordmetric'
+
+    FnordMetric.namespace :myapp do
+
+    # Unique pageviews
+    gauge :pageviews_daily_unique, :tick => 1.day.to_i, 
+                                   :unique => true, 
+                                   :title => "Unique Visits (Daily)"
+
+    # _pageview is a special Fnordmetric event
+    # and as such starts with `_`
+    event :_pageview do
+      # increment the daily_uniques gauge by 1 if session_key hasn't been seen
+      # in this tick yet
+      incr :pageviews_daily_unique
+      # increment the pageviews_per_url_daily gauge by 1 where key = 'page2'
+      incr_field :pageviews_per_url_daily, data[:url]
+    end
+
+
+    # Widgets
+    widget 'Overview', {
+      :title => "Visits per day",
+      :type => :timeline,
+      :plot_style => :areaspline,  
+      :gauges => :pageviews_daily_unique,
+      :include_current => true,
+      :autoupdate => 10
+    }
+
+See the `examples/` directory for a worging example.
+
+Caveats
+-------
+
+If sid changes (e.g. when a user logs in), timers won't pop properly. This
+doesn't break, but will leave a nasty line in your logs. The next version will
+take care of this.
+
+Contributing
+------------
+
+fork / make a feature branch / change / specs / commit / send PR (devel branch)
+
+Ack
+---
+
+Thanks to manveru & yorick for [Ramaze][1]. Man, those Rails zealots just don't 
+realize their pathetic fate :)
+
+License
+-------
+
+`ramaze-fnordmetric` is licensed under the MIT license :
+
+Copyright (c) 2012, Michel Blanc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+
+
+  [1]: https://github.com/ramaze/ramaze
+  [2]: https://github.com/paulasmuth/fnordmetric
+
+

data/Rakefile

@@ -0,0 +1,17 @@
+task_dir = File.expand_path('../task', __FILE__)
+
+Dir.glob("#{task_dir}/*.rake").each do |f|
+  import(f)
+end
+
+#require File.expand_path('../../lib/ramaze/helper/fnordmetric', __FILE__)
+
+module Ramaze
+  module Helper
+    module Fnordmetric
+      Gemspec = Gem::Specification::load(
+        File.expand_path('../ramaze-fnordmetric.gemspec', __FILE__)
+      )
+    end
+  end
+end

data/examples/README.md

@@ -0,0 +1,25 @@
+Fnordmetric Helper Example
+==========================
+
+__Some basic messy example__
+
+----
+
+Running it
+----------
+
+Start the web app :
+
+    cd examples
+    ruby example.rb
+
+In another terminal, start the fnordmetric app :
+
+    cd examples
+    ruby fn.rb
+
+Usage
+-----
+
+Point your browser to [http://localhost:7000] and you're set !
+

data/examples/example.rb

@@ -0,0 +1,82 @@
+require 'ramaze'
+
+# use : require 'ramaze-fnordmetric-helper' IRL
+require __DIR__('../lib/ramaze/helper/fnordmetric')
+
+
+class MainController < Ramaze::Controller
+  include Ramaze::Traited
+  map '/'
+  helper :fnordmetric
+
+#  trait :fnord_redis_url => "redis://localhost:6379"
+
+  # We just use push_timer to mesure some time
+  def index
+    p request.inspect
+    push_timer :stupid_sleep
+    sleep 2
+    pop_timer
+
+    <<EOF
+<h2>push_timer/pop_timer methods</h2>
+This example uses push_timer/pop_timer methods
+
+<pre>
+  def index
+    push_timer :stupid_sleep
+    sleep 2
+    pop_timer
+  end
+</pre>
+
+If you run 'fn.rb' (bundle exec fn.rb run), you can check this <a href='http://localhost:4242' target='_blank'>link</a> to get the Fnordmetric dashboard.
+<p />
+Sorry for the wait... but congratulations won a vanilla Icecream <a href='/icecream'>Icecream</a> ! May be you prefer <a href='/icecream/strawberry'>strawberry</a>. ?
+EOF
+  end
+
+  # Here we just interested in counting icecreams
+  def icecream(flavor="vanilla")
+    event(:icecream, :flavor => flavor)
+
+    <<EOF2
+<h2>event method</h2>
+This example uses event to send an event to Fnordmetric.
+
+<pre>
+  def icecream(flavor="vanilla")
+    event(:icecream, :flavor => flavor)
+  end
+</pre>
+
+If you run 'fn.rb' (bundle exec fn.rb run), you can check the icecreams <a href='http://localhost:4242/example#dashboard/Overview' target='_blank'>page</a><p />
+Sorry for the wait... You won a vanilla Icecream <a href='/icecream'>Icecream</a>. May be you prefer <a href='/icecream/strawberry'>strawberry</a> ? <p />
+If you wish, we can <a href='/deliver'>deliver</a> the icecream to your door, but it might take some time, be patient.
+
+EOF2
+  end
+
+  def deliver
+    sleep(1 + rand)
+
+    <<EOF3
+<h2>clock class method</h2>
+This example uses 'clock' to measure the time taken by a controller method.
+
+<pre>
+  def deliver
+    sleep(rand * 10)
+  end
+  clock :deliver, :delivery_performance
+</pre>
+
+If you run 'fn.rb' (bundle exec fn.rb run), you can check the performance <a href='http://localhost:4242/example#dashboard/Performance' target='_blank'>tab</a><p />
+Your icecream has been delivered. You can get <a href='/deliver'>another one</a> or go to the <a href='/'>index</a> page.<p />
+EOF3
+  end
+  clock :deliver, :delivery_performance
+
+end
+
+Ramaze.start(:root => Ramaze.options.roots)