2009-09-16 18:53:49 -04:00
|
|
|
module ActiveSupport
|
2011-11-05 13:29:28 -04:00
|
|
|
# = Notifications
|
2009-09-16 18:53:49 -04:00
|
|
|
#
|
2011-11-05 13:29:28 -04:00
|
|
|
# +ActiveSupport::Notifications+ provides an instrumentation API for Ruby.
|
|
|
|
#
|
|
|
|
# == Instrumenters
|
|
|
|
#
|
|
|
|
# To instrument an event you just need to do:
|
|
|
|
#
|
|
|
|
# ActiveSupport::Notifications.instrument("render", :extra => :information) do
|
2009-09-16 18:53:49 -04:00
|
|
|
# render :text => "Foo"
|
|
|
|
# end
|
|
|
|
#
|
2011-11-05 13:29:28 -04:00
|
|
|
# That executes the block first and notifies all subscribers once done.
|
|
|
|
#
|
|
|
|
# In the example above "render" is the name of the event, and the rest is called
|
|
|
|
# the _payload_. The payload is a mechanism that allows instrumenters to pass
|
|
|
|
# extra information to subscribers. Payloads consist of a hash whose contents
|
|
|
|
# are arbitrary and generally depend on the event.
|
|
|
|
#
|
|
|
|
# == Subscribers
|
|
|
|
#
|
2009-10-06 08:42:42 -04:00
|
|
|
# You can consume those events and the information they provide by registering
|
2011-11-05 13:29:28 -04:00
|
|
|
# a subscriber. For instance, let's store all "render" events in an array:
|
2009-09-16 18:53:49 -04:00
|
|
|
#
|
2011-11-05 13:29:28 -04:00
|
|
|
# events = []
|
2009-10-06 08:42:42 -04:00
|
|
|
#
|
2011-11-05 13:29:28 -04:00
|
|
|
# ActiveSupport::Notifications.subscribe("render") do |*args|
|
|
|
|
# events << ActiveSupport::Notifications::Event.new(*args)
|
2009-10-06 08:42:42 -04:00
|
|
|
# end
|
2009-09-16 18:53:49 -04:00
|
|
|
#
|
2011-11-05 13:29:28 -04:00
|
|
|
# That code returns right away, you are just subscribing to "render" events.
|
|
|
|
# The block will be called asynchronously whenever someone instruments "render":
|
|
|
|
#
|
|
|
|
# ActiveSupport::Notifications.instrument("render", :extra => :information) do
|
2009-09-16 18:53:49 -04:00
|
|
|
# render :text => "Foo"
|
|
|
|
# end
|
|
|
|
#
|
2011-11-05 13:29:28 -04:00
|
|
|
# event = events.first
|
|
|
|
# event.name # => "render"
|
2010-07-29 20:30:04 -04:00
|
|
|
# event.duration # => 10 (in milliseconds)
|
|
|
|
# event.payload # => { :extra => :information }
|
2009-09-16 18:53:49 -04:00
|
|
|
#
|
2011-11-05 13:29:28 -04:00
|
|
|
# The block in the +subscribe+ call gets the name of the event, start
|
|
|
|
# timestamp, end timestamp, a string with a unique identifier for that event
|
|
|
|
# (something like "535801666f04d0298cd6"), and a hash with the payload, in
|
|
|
|
# that order.
|
|
|
|
#
|
|
|
|
# If an exception happens during that particular instrumentation the payload will
|
|
|
|
# have a key +:exception+ with an array of two elements as value: a string with
|
|
|
|
# the name of the exception class, and the exception message.
|
|
|
|
#
|
|
|
|
# As the previous example depicts, the class +ActiveSupport::Notifications::Event+
|
|
|
|
# is able to take the arguments as they come and provide an object-oriented
|
|
|
|
# interface to that data.
|
2009-10-06 08:42:42 -04:00
|
|
|
#
|
2011-11-05 13:29:28 -04:00
|
|
|
# You can also subscribe to all events whose name matches a certain regexp:
|
|
|
|
#
|
|
|
|
# ActiveSupport::Notifications.subscribe(/render/) do |*args|
|
|
|
|
# ...
|
2009-10-06 08:42:42 -04:00
|
|
|
# end
|
|
|
|
#
|
2011-11-05 13:29:28 -04:00
|
|
|
# and even pass no argument to +subscribe+, in which case you are subscribing
|
|
|
|
# to all events.
|
|
|
|
#
|
2009-10-15 17:51:51 -04:00
|
|
|
# Notifications ships with a queue implementation that consumes and publish events
|
2010-02-15 09:44:30 -05:00
|
|
|
# to log subscribers in a thread. You can use any queue implementation you want.
|
2009-09-16 18:53:49 -04:00
|
|
|
#
|
2009-10-15 17:51:51 -04:00
|
|
|
module Notifications
|
2009-11-28 15:49:07 -05:00
|
|
|
autoload :Instrumenter, 'active_support/notifications/instrumenter'
|
|
|
|
autoload :Event, 'active_support/notifications/instrumenter'
|
|
|
|
autoload :Fanout, 'active_support/notifications/fanout'
|
2009-09-30 07:59:15 -04:00
|
|
|
|
2010-07-21 19:29:26 -04:00
|
|
|
@instrumenters = Hash.new { |h,k| h[k] = notifier.listening?(k) }
|
|
|
|
|
2009-10-01 18:00:22 -04:00
|
|
|
class << self
|
2011-02-09 17:02:38 -05:00
|
|
|
attr_accessor :notifier
|
2011-02-09 16:46:47 -05:00
|
|
|
|
|
|
|
def publish(name, *args)
|
|
|
|
notifier.publish(name, *args)
|
|
|
|
end
|
2010-07-21 19:29:26 -04:00
|
|
|
|
2010-07-25 14:46:42 -04:00
|
|
|
def instrument(name, payload = {})
|
2010-07-21 19:29:26 -04:00
|
|
|
if @instrumenters[name]
|
2010-07-25 14:46:42 -04:00
|
|
|
instrumenter.instrument(name, payload) { yield payload if block_given? }
|
2010-07-21 19:29:26 -04:00
|
|
|
else
|
2010-07-25 14:46:42 -04:00
|
|
|
yield payload if block_given?
|
2010-07-21 19:29:26 -04:00
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
def subscribe(*args, &block)
|
|
|
|
notifier.subscribe(*args, &block).tap do
|
|
|
|
@instrumenters.clear
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
2011-02-09 17:33:56 -05:00
|
|
|
def unsubscribe(args)
|
|
|
|
notifier.unsubscribe(args)
|
2010-07-21 19:29:26 -04:00
|
|
|
@instrumenters.clear
|
|
|
|
end
|
2009-10-01 18:00:22 -04:00
|
|
|
|
2010-01-06 16:23:29 -05:00
|
|
|
def instrumenter
|
|
|
|
Thread.current[:"instrumentation_#{notifier.object_id}"] ||= Instrumenter.new(notifier)
|
|
|
|
end
|
2009-10-01 18:00:22 -04:00
|
|
|
end
|
2011-02-09 17:02:38 -05:00
|
|
|
|
|
|
|
self.notifier = Fanout.new
|
2009-09-16 18:53:49 -04:00
|
|
|
end
|
|
|
|
end
|