instrumentable 0.0.4 → 1.0.0

data/README.md

@@ -1,12 +1,18 @@
-# Instrumentable
+# Instrumentable (1.0.0)
+-note, this version is not backwards compatiable
 
-TODO: Write a gem description
+Decorate all your favorite methods with ActiveSupport::Notifications.instrument
+
+This gem allows you to wrap methods on your classes for use with AS::N without having
+to put AS::N.instrument do blocks around everything. You can customize the
+payload sent with the event, and in addition all of the method args(if any) are sent
+as well
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'instrumentable'
+    gem "instrumentable", "~> 1.0.0"
 
 And then execute:
 
@@ -17,20 +23,75 @@ Or install it yourself as:
     $ gem install instrumentable
 
 ## Usage
+include the gem in your class
+```ruby
+include Instrumentable
+```
+to instrument an instance method
+```ruby
+instrument_method :method_name, 'event.to.fire', :payload_key => :payload_value
+```
+
+``` :method_name ```
+
+Is the name of the method you want to instrument
+
+``` 'event.to.fire' ```
+
+Is the name of the event you'll setup your subscriber for
+This can be any string
+
+``` :payload_key => :payload_value ```
+
+The last part is the payload, which consists of a key and a value.
+What is sent to the subscriber depends on what is passed in as the value
++ String
+  + ex: ```'static_string'```
+  + string is passed in as-is to the payload
++ Symbol
+  + ex: ```:method_name```
+  + calls symbol as a method on the class in the current context (class, intance)
++ Proc
+  + ex: ```Proc.new { Time.now }```
+  + calls the proc, returning the value
+
+All payloads will recieve a list of the arugments called with the method under
+```:_method_args```, this will be an empty array if the method was called with no args
+
+If you want to instrument a class method, you must use a separate method
+```ruby
+class_instrument_method  self, :method_name, 'event.to.fire', :payload_key => :payload_value
+```
+You must use ```class_instrument_method``` instead and pass the first argument in as ```self```
+
+## Examples
 ```ruby
 require "instrumentable"
 
 class WidgetRenderer
   include Instrumentable
 
-  attr_reader   :id
-  attr_accessor :name
+  attr_reader :id, :name
 
   def render
     # do crazy render here
   end 
 
-  instrument_for :render, 'load.widget', :widget_id => :id, :widget_name => :name
+  def load(options)
+    # make call here
+  end
+
+  def self.add(location)
+    # ...
+  end
+
+  private
+  def valid?
+    # returns if call is valid
+  end
+  instrument_method :render, 'render.widget', :widget_id => :id, :widget_name => :name
+  instrument_method :load, 'load.widget', :status => 'loading', :valid => :valid?
+  class_instrument_method :add, 'add.widget'
 end
 ```
 
@@ -39,7 +100,7 @@ end
 
 ## Running Tests
 
-    ruby -Itest test/instrumentable_test.rb
+    rake test
 
 ## Contributing
 

data/lib/instrumentable.rb

@@ -3,41 +3,99 @@ require "active_support/concern"
 require "active_support/notifications"
 require "instrumentable/version"
 
-# Includes +instrument_for+ into the class. The class uses it by adding
-# the instrument_for method to the end of the class specifying
-# what method to apply it to.
+# Instrumentable is a module you can include in your classes to help with
+# setting up instrumention with ActiveSupport::Notifications.instrument
+# Commoningly you would use ActiveSupport::Notifications.instrument and
+# wrap it around the code you want you care about in order to fire off
+# the approiate event. This allows you to do the same thing but without
+# having to modify your existing method definitions.
+#
+#  ==== Example
+#
+#   class Person
+#     include Instrumentable
+#     attr_reader :phone
+#
+#     def call
+#       puts "Calling at #{@phone} number"
+#     end
+#
+#     def self.find(id)
+#       PersonStore.find(id)
+#     end
+#
+#     instrument_method :call, 'person.call', :phone => :phone
+#     class_instrument_method :find, 'person.find'
+#   end
+#
+#   person = Person.find(5)
+#   person.call
+#
+# Result:
+#   An event with name 'person.find' would fire when `Person.find` is called
+#   with a payload of { :_method_args => 5 }
+#
+#   An event with name 'person.call' would fire when person.call is called
+#   with a payload of { :phone => (555)555-555 }
 module Instrumentable
   extend ActiveSupport::Concern
 
   module ClassMethods
-    # Internal: Decorates :method_to_instrument with  AS::N.instrument
-    # firing with :event_name to the matching AS::N.subscribe
+    # Wraps method_to_instrument in an AS:N:instrument with event_name as
+    # the name and passes the payload given to it.
     #
-    # Example:
+    # Payload is a hash of payload_name to payload_value
     #
-    #   # Decorates render method with AS:N:instrument 'model.render' and passes
-    #   # a payload of :model_name and :id to the subscribe method
-    #   instrument_for :render, 'model.render', {:model_name => :model_name, :id => :id
-    def instrument_for(method_to_instrument, event_name, payload={})
-      instrument_method = :"instrument_for_#{method_to_instrument}"
+    #   payload_value supported types:
+    #
+    #     String::  Passes the string straight to the payload_name
+    #               and does nothing else with it
+    #     Symbol::  A method to call on the class being instrumented
+    #     Proc::    A proc to call with the object
+    #
+    #   All of these have their value then calculated (if needed) and set
+    #   as the value for the given key
+    def instrument_method(method_to_instrument, event_name, payload={})
+      Instrumentality.begin(self, method_to_instrument, event_name, payload)
+    end
 
-      # Hide original method under new method
-      alias_method instrument_method, method_to_instrument
+    # Class implementation of +instrument_method+
+    def class_instrument_method(klass, method_to_instrument, event_name, payload={})
+      class << klass; self; end.class_eval do
+        Instrumentality.begin(self, method_to_instrument, event_name, payload)
+      end
+    end
+  end
 
-      # Redefine method_to_instrument to call inside the Notification
-      define_method(method_to_instrument) do |*args, &block|
-        callable_payload = payload.inject({}) do |result, (payload_key, payload_value)|
-          value = if respond_to?(payload_value)
-                    __send__ payload_value
-                  else
-                    payload_value
-                  end
+  private
+  class Instrumentality
+
+    def self.begin(klass, method, event, payload)
+      instrumentality = self
+      instrumented_method = :"_instrument_for_#{method}"
+      klass.send :alias_method, instrumented_method, method
+
+      klass.send(:define_method, method) do |*args, &block|
+        event_payload = payload.inject({}) do |result, (payload_key, payload_value)|
+          value = instrumentality.invoke_value(self, payload_value)
           result.tap { |r| r[payload_key] = value }
         end
-        ActiveSupport::Notifications.instrument event_name, callable_payload do
-          __send__(instrument_method, *args, &block)
+        event_payload.merge!({:_method_args => args})
+        ActiveSupport::Notifications.instrument event, event_payload do
+          __send__(instrumented_method, *args, &block)
         end
       end
     end
+
+    def self.invoke_value(klass, obj)
+      case obj
+      when Symbol
+        klass.__send__ obj
+      when Proc
+        obj.call
+      when String
+        obj
+      end
+    end
   end
 end

data/lib/instrumentable/version.rb

@@ -1,3 +1,3 @@
 module Instrumentable
-  VERSION = "0.0.4"
+  VERSION = "1.0.0"
 end

data/test/instrumentable_test.rb

@@ -1,56 +1,118 @@
 require "minitest_helper"
 require_relative "../lib/instrumentable"
 
-class FakeModel
+class FatherCat
   include Instrumentable
-  def simple_event; end
-  def false_event; end
-  def payload_event; end
-  instrument_for :simple_event,   'event.name',   :my_payload => :id
-  instrument_for :false_event,    'event.name',   :my_payload => :valid
-  instrument_for :payload_event,  'payload.name', :my_payload => 'megaman'
+  def hello_everynyan; end
+  def fake_cat; end
+  def osaka; end
+  def teachers(home, pe, geo); end
+  def self.omg; end
+  def self.sorry; "I'mma so sorry"; end
+  def self.who?(person); end
+
+  # String
+  instrument_method :hello_everynyan, 'fathercat.greet', :payload => 'FatherCat'
+  # Symbol
+  instrument_method :fake_cat, 'fathercat.rant', :payload => :look_alike
+  # Proc
+  instrument_method :osaka, 'fathercat.ask', :payload => Proc.new { 'also cat tounged' }
+  # Args
+  instrument_method :teachers, 'fathercat.teachers', :payload => 'teachers'
+
+  # Class
+  class_instrument_method self, :omg, 'fathercat.anger', :payload => :sorry
+  # Args
+  class_instrument_method self, :who?, 'fathercat.who', :payload => 'who?'
 end
 
 describe Instrumentable do
 
-  it "must instrument simple_event" do
-    fm = FakeModel.new
-    def fm.id; 1; end
-    expected = ["event.name-#{fm.id}"]
-    events = []
+  describe ".instrument_method" do
+    it "must instrument fathercat.greet" do
+      cat = FatherCat.new
+      expected = ["fathercat.greet-FatherCat"]
+      events = []
 
-    callback = lambda { |*_| events << "#{_.first}-#{_.last[:my_payload]}" }
-    ActiveSupport::Notifications.subscribed(callback, 'event.name') do
-      fm.simple_event
-      ActiveSupport::Notifications.instrument('other.event')
+      callback = lambda { |*_| events << "#{_.first}-#{_.last[:payload]}" }
+      ActiveSupport::Notifications.subscribed(callback, 'fathercat.greet') do
+        cat.hello_everynyan
+        ActiveSupport::Notifications.instrument('some.other.event')
+      end
+      events.must_equal expected
+    end
+
+    it "must instrument fathercat.rant" do
+      cat = FatherCat.new
+      def cat.look_alike; 'Mori'; end
+      expected = ["fathercat.rant-#{cat.look_alike}"]
+      events = []
+
+      callback = lambda { |*_| events << "#{_.first}-#{_.last[:payload]}" }
+      ActiveSupport::Notifications.subscribed(callback, 'fathercat.rant') do
+        cat.fake_cat
+        ActiveSupport::Notifications.instrument('some.other.event')
+      end
+      events.must_equal expected
     end
-    events.must_equal expected
-  end
 
-  it "must work with callable payload that returns false" do
-    fm = FakeModel.new
-    def fm.valid; false; end
-    expected = ["event.name-#{fm.valid}"]
-    events = []
+    it "must instrument fathercat.ask" do
+      cat = FatherCat.new
+      expected = ["fathercat.ask-also cat tounged"]
+      events = []
 
-    callback = lambda { |*_| events << "#{_.first}-#{_.last[:my_payload]}" }
-    ActiveSupport::Notifications.subscribed(callback, 'event.name') do
-      fm.false_event
-      ActiveSupport::Notifications.instrument('other.event')
+      callback = lambda { |*_| events << "#{_.first}-#{_.last[:payload]}" }
+      ActiveSupport::Notifications.subscribed(callback, 'fathercat.ask') do
+        cat.osaka
+        ActiveSupport::Notifications.instrument('some.other.event')
+      end
+      events.must_equal expected
+    end
+
+    it "must pass method args to payload" do
+      cat = FatherCat.new
+      teachers = { :home => 'Yukari', :pe => 'Nyamo', :geo => 'Kimura' }
+      expected = ["fathercat.teachers-#{teachers[:home]}_#{teachers[:pe]}_#{teachers[:geo]}"]
+      events = []
+
+      callback = lambda do |*_|
+        event_name = _.first
+        payload = _.last[:_method_args].join('_')
+        events << "#{event_name}-#{payload}"
+      end
+      ActiveSupport::Notifications.subscribed(callback, 'fathercat.teachers') do
+        cat.teachers(teachers[:home], teachers[:pe], teachers[:geo])
+        ActiveSupport::Notifications.instrument('some.other.event')
+      end
+      events.must_equal expected
     end
-    events.must_equal expected
   end
 
-  it "must handle non-callable payloads" do
-    fm = FakeModel.new
-    expected = ['payload.name-megaman']
-    events = []
+  describe ".class_instrument_method" do
+    it "must instrument fathercat.anger" do
+      expected = ["fathercat.anger-#{FatherCat.sorry}"]
+      events = []
+
+      callback = lambda { |*_| events << "#{_.first}-#{_.last[:payload]}" }
+      ActiveSupport::Notifications.subscribed(callback, 'fathercat.anger') do
+        FatherCat.omg
+        ActiveSupport::Notifications.instrument('some.other.event')
+      end
+      events.must_equal expected
+    end
+
+    #class_instrument_method self, :who?, 'fathercat.who', :payload => 'who?'
+    it "must pass method args to payload" do
+      person = 'chiyo'
+      expected = ["fathercat.who-#{person}"]
+      events = []
 
-    callback = lambda { |*_| events << "#{_.first}-#{_.last[:my_payload]}" }
-    ActiveSupport::Notifications.subscribed(callback, 'payload.name') do
-      fm.payload_event
-      ActiveSupport::Notifications.instrument('other.event')
+      callback = lambda { |*_| events << "#{_.first}-#{_.last[:_method_args].first}" }
+      ActiveSupport::Notifications.subscribed(callback, 'fathercat.who') do
+        FatherCat.who?(person)
+        ActiveSupport::Notifications.instrument('some.other.event')
+      end
+      events.must_equal expected
     end
-    events.must_equal expected
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: instrumentable
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-14 00:00:00.000000000 Z
+date: 2012-12-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport