2012-03-21 14:33:23 -04:00
|
|
|
require 'active_support/notifications/instrumenter'
|
|
|
|
require 'active_support/notifications/fanout'
|
2013-04-09 19:20:49 -04:00
|
|
|
require 'active_support/per_thread_registry'
|
2012-03-21 14:33:23 -04:00
|
|
|
|
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
|
|
|
#
|
2012-09-17 01:22:18 -04:00
|
|
|
# <tt>ActiveSupport::Notifications</tt> provides an instrumentation API for
|
|
|
|
# Ruby.
|
2011-11-05 13:29:28 -04:00
|
|
|
#
|
|
|
|
# == Instrumenters
|
|
|
|
#
|
|
|
|
# To instrument an event you just need to do:
|
|
|
|
#
|
2012-09-12 14:46:33 -04:00
|
|
|
# ActiveSupport::Notifications.instrument('render', extra: :information) do
|
|
|
|
# render text: 'Foo'
|
2009-09-16 18:53:49 -04:00
|
|
|
# end
|
|
|
|
#
|
2011-11-05 13:29:28 -04:00
|
|
|
# That executes the block first and notifies all subscribers once done.
|
|
|
|
#
|
2012-09-12 14:46:33 -04:00
|
|
|
# In the example above +render+ is the name of the event, and the rest is called
|
2011-11-05 13:29:28 -04:00
|
|
|
# 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
|
2012-09-27 15:37:24 -04:00
|
|
|
# a subscriber.
|
|
|
|
#
|
|
|
|
# ActiveSupport::Notifications.subscribe('render') do |name, start, finish, id, payload|
|
|
|
|
# name # => String, name of the event (such as 'render' from above)
|
|
|
|
# start # => Time, when the instrumented block started execution
|
|
|
|
# finish # => Time, when the instrumented block ended execution
|
|
|
|
# id # => String, unique ID for this notification
|
|
|
|
# payload # => Hash, the payload
|
|
|
|
# end
|
|
|
|
#
|
|
|
|
# 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
|
|
|
#
|
2012-09-12 14:46:33 -04:00
|
|
|
# ActiveSupport::Notifications.subscribe('render') do |*args|
|
2011-11-05 13:29:28 -04:00
|
|
|
# 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.
|
2012-06-16 07:35:55 -04:00
|
|
|
# The block is saved and will be called whenever someone instruments "render":
|
2011-11-05 13:29:28 -04:00
|
|
|
#
|
2012-09-12 14:46:33 -04:00
|
|
|
# ActiveSupport::Notifications.instrument('render', extra: :information) do
|
|
|
|
# render text: 'Foo'
|
2009-09-16 18:53:49 -04:00
|
|
|
# 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)
|
2012-09-12 14:46:33 -04:00
|
|
|
# event.payload # => { extra: :information }
|
2009-09-16 18:53:49 -04:00
|
|
|
#
|
2012-04-12 17:48:53 -04:00
|
|
|
# The block in the <tt>subscribe</tt> call gets the name of the event, start
|
2011-11-05 13:29:28 -04:00
|
|
|
# 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
|
2012-04-12 17:48:53 -04:00
|
|
|
# have a key <tt>:exception</tt> with an array of two elements as value: a string with
|
2011-11-05 13:29:28 -04:00
|
|
|
# the name of the exception class, and the exception message.
|
|
|
|
#
|
2012-04-12 17:48:53 -04:00
|
|
|
# As the previous example depicts, the class <tt>ActiveSupport::Notifications::Event</tt>
|
2011-11-05 13:29:28 -04:00
|
|
|
# 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
|
|
|
#
|
2012-04-12 18:24:43 -04:00
|
|
|
# It is also possible to pass an object as the second parameter passed to the
|
|
|
|
# <tt>subscribe</tt> method instead of a block:
|
|
|
|
#
|
|
|
|
# module ActionController
|
|
|
|
# class PageRequest
|
|
|
|
# def call(name, started, finished, unique_id, payload)
|
2012-09-12 14:46:33 -04:00
|
|
|
# Rails.logger.debug ['notification:', name, started, finished, unique_id, payload].join(' ')
|
2012-04-12 18:24:43 -04:00
|
|
|
# end
|
|
|
|
# end
|
|
|
|
# end
|
|
|
|
#
|
|
|
|
# ActiveSupport::Notifications.subscribe('process_action.action_controller', ActionController::PageRequest.new)
|
|
|
|
#
|
|
|
|
# resulting in the following output within the logs including a hash with the payload:
|
|
|
|
#
|
|
|
|
# notification: process_action.action_controller 2012-04-13 01:08:35 +0300 2012-04-13 01:08:35 +0300 af358ed7fab884532ec7 {
|
2012-11-10 15:15:13 -05:00
|
|
|
# controller: "Devise::SessionsController",
|
|
|
|
# action: "new",
|
|
|
|
# params: {"action"=>"new", "controller"=>"devise/sessions"},
|
|
|
|
# format: :html,
|
|
|
|
# method: "GET",
|
|
|
|
# path: "/login/sign_in",
|
|
|
|
# status: 200,
|
|
|
|
# view_runtime: 279.3080806732178,
|
|
|
|
# db_runtime: 40.053
|
2012-04-12 18:24:43 -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
|
|
|
|
#
|
2012-04-12 17:48:53 -04:00
|
|
|
# and even pass no argument to <tt>subscribe</tt>, in which case you are subscribing
|
2011-11-05 13:29:28 -04:00
|
|
|
# to all events.
|
|
|
|
#
|
2011-11-05 15:02:54 -04:00
|
|
|
# == Temporary Subscriptions
|
|
|
|
#
|
|
|
|
# Sometimes you do not want to subscribe to an event for the entire life of
|
2011-11-05 15:09:18 -04:00
|
|
|
# the application. There are two ways to unsubscribe.
|
2011-11-05 15:02:54 -04:00
|
|
|
#
|
2012-01-12 17:57:58 -05:00
|
|
|
# WARNING: The instrumentation framework is designed for long-running subscribers,
|
|
|
|
# use this feature sparingly because it wipes some internal caches and that has
|
|
|
|
# a negative impact on performance.
|
|
|
|
#
|
2011-11-05 15:02:54 -04:00
|
|
|
# === Subscribe While a Block Runs
|
|
|
|
#
|
|
|
|
# You can subscribe to some event temporarily while some block runs. For
|
|
|
|
# example, in
|
|
|
|
#
|
|
|
|
# callback = lambda {|*args| ... }
|
|
|
|
# ActiveSupport::Notifications.subscribed(callback, "sql.active_record") do
|
|
|
|
# ...
|
|
|
|
# end
|
|
|
|
#
|
|
|
|
# the callback will be called for all "sql.active_record" events instrumented
|
|
|
|
# during the execution of the block. The callback is unsubscribed automatically
|
|
|
|
# after that.
|
|
|
|
#
|
|
|
|
# === Manual Unsubscription
|
|
|
|
#
|
|
|
|
# The +subscribe+ method returns a subscriber object:
|
|
|
|
#
|
|
|
|
# subscriber = ActiveSupport::Notifications.subscribe("render") do |*args|
|
|
|
|
# ...
|
|
|
|
# end
|
|
|
|
#
|
|
|
|
# To prevent that block from being called anymore, just unsubscribe passing
|
|
|
|
# that reference:
|
|
|
|
#
|
|
|
|
# ActiveSupport::Notifications.unsubscribe(subscriber)
|
|
|
|
#
|
|
|
|
# == Default Queue
|
|
|
|
#
|
2013-05-21 02:53:05 -04:00
|
|
|
# Notifications ships with a queue implementation that consumes and publishes events
|
|
|
|
# to all log subscribers. 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-10-01 18:00:22 -04:00
|
|
|
class << self
|
2012-06-19 18:33:14 -04: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 = {})
|
2012-06-19 13:19:48 -04:00
|
|
|
if notifier.listening?(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)
|
2012-06-19 13:19:48 -04:00
|
|
|
notifier.subscribe(*args, &block)
|
2010-07-21 19:29:26 -04:00
|
|
|
end
|
|
|
|
|
2011-11-05 15:02:54 -04:00
|
|
|
def subscribed(callback, *args, &block)
|
|
|
|
subscriber = subscribe(*args, &callback)
|
|
|
|
yield
|
|
|
|
ensure
|
|
|
|
unsubscribe(subscriber)
|
|
|
|
end
|
|
|
|
|
2011-02-09 17:33:56 -05:00
|
|
|
def unsubscribe(args)
|
|
|
|
notifier.unsubscribe(args)
|
2010-07-21 19:29:26 -04:00
|
|
|
end
|
2009-10-01 18:00:22 -04:00
|
|
|
|
2010-01-06 16:23:29 -05:00
|
|
|
def instrumenter
|
2013-11-06 19:32:47 -05:00
|
|
|
InstrumentationRegistry.instance.instrumenter_for(notifier)
|
2013-04-08 16:50:05 -04:00
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
# This class is a registry which holds all of the +Instrumenter+ objects
|
|
|
|
# in a particular thread local. To access the +Instrumenter+ object for a
|
|
|
|
# particular +notifier+, you can call the following method:
|
|
|
|
#
|
|
|
|
# InstrumentationRegistry.instrumenter_for(notifier)
|
|
|
|
#
|
|
|
|
# The instrumenters for multiple notifiers are held in a single instance of
|
|
|
|
# this class.
|
|
|
|
class InstrumentationRegistry # :nodoc:
|
2013-04-09 19:20:49 -04:00
|
|
|
extend ActiveSupport::PerThreadRegistry
|
2013-04-08 16:50:05 -04:00
|
|
|
|
|
|
|
def initialize
|
|
|
|
@registry = {}
|
|
|
|
end
|
|
|
|
|
|
|
|
def instrumenter_for(notifier)
|
|
|
|
@registry[notifier] ||= Instrumenter.new(notifier)
|
2012-06-19 13:06:49 -04:00
|
|
|
end
|
|
|
|
end
|
2012-06-19 18:33:14 -04:00
|
|
|
|
|
|
|
self.notifier = Fanout.new
|
2009-09-16 18:53:49 -04:00
|
|
|
end
|
|
|
|
end
|