expands the documentation of AS::Notifications
This commit is contained in:
parent
f575e21025
commit
b33232f1b2
@ -1,36 +1,68 @@
|
||||
module ActiveSupport
|
||||
# Notifications provides an instrumentation API for Ruby. To instrument an
|
||||
# action in Ruby you just need to do:
|
||||
# = Notifications
|
||||
#
|
||||
# ActiveSupport::Notifications.instrument(:render, :extra => :information) do
|
||||
# +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
|
||||
# render :text => "Foo"
|
||||
# end
|
||||
#
|
||||
# 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
|
||||
#
|
||||
# You can consume those events and the information they provide by registering
|
||||
# a log subscriber. For instance, let's store all instrumented events in an array:
|
||||
# a subscriber. For instance, let's store all "render" events in an array:
|
||||
#
|
||||
# @events = []
|
||||
# events = []
|
||||
#
|
||||
# ActiveSupport::Notifications.subscribe do |*args|
|
||||
# @events << ActiveSupport::Notifications::Event.new(*args)
|
||||
# ActiveSupport::Notifications.subscribe("render") do |*args|
|
||||
# events << ActiveSupport::Notifications::Event.new(*args)
|
||||
# end
|
||||
#
|
||||
# ActiveSupport::Notifications.instrument(:render, :extra => :information) do
|
||||
# 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
|
||||
# render :text => "Foo"
|
||||
# end
|
||||
#
|
||||
# event = @events.first
|
||||
# event.name # => :render
|
||||
# event = events.first
|
||||
# event.name # => "render"
|
||||
# event.duration # => 10 (in milliseconds)
|
||||
# event.payload # => { :extra => :information }
|
||||
#
|
||||
# When subscribing to Notifications, you can pass a pattern, to only consume
|
||||
# events that match the pattern:
|
||||
# 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.
|
||||
#
|
||||
# ActiveSupport::Notifications.subscribe(/render/) do |event|
|
||||
# @render_events << event
|
||||
# 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.
|
||||
#
|
||||
# You can also subscribe to all events whose name matches a certain regexp:
|
||||
#
|
||||
# ActiveSupport::Notifications.subscribe(/render/) do |*args|
|
||||
# ...
|
||||
# end
|
||||
#
|
||||
# and even pass no argument to +subscribe+, in which case you are subscribing
|
||||
# to all events.
|
||||
#
|
||||
# Notifications ships with a queue implementation that consumes and publish events
|
||||
# to log subscribers in a thread. You can use any queue implementation you want.
|
||||
#
|
||||
|
Loading…
Reference in New Issue
Block a user