Module: ActiveSupport::Notifications
- Defined in:
- lib/active_support/notifications.rb,
lib/active_support/notifications/fanout.rb,
lib/active_support/notifications/instrumenter.rb
Overview
Notifications
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 subscriber. For instance, let’s store all “render” events in an array:
events = []
ActiveSupport::Notifications.subscribe("render") do |*args|
events << ActiveSupport::Notifications::Event.new(*args)
end
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.duration # => 10 (in milliseconds)
event.payload # => { :extra => :information }
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.
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.
Temporary Subscriptions
Sometimes you do not want to subscribe to an event for the entire life of the application. There are two ways to unsubscribe.
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.
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
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.
Defined Under Namespace
Classes: Event, Fanout, Instrumenter
Class Attribute Summary collapse
-
.notifier ⇒ Object
Returns the value of attribute notifier.
Class Method Summary collapse
- .instrument(name, payload = {}) ⇒ Object
- .instrumenter ⇒ Object
- .publish(name, *args) ⇒ Object
- .subscribe(*args, &block) ⇒ Object
- .subscribed(callback, *args, &block) ⇒ Object
- .unsubscribe(args) ⇒ Object
Class Attribute Details
.notifier ⇒ Object
Returns the value of attribute notifier.
115 116 117 |
# File 'lib/active_support/notifications.rb', line 115 def notifier @notifier end |
Class Method Details
.instrument(name, payload = {}) ⇒ Object
121 122 123 124 125 126 127 |
# File 'lib/active_support/notifications.rb', line 121 def instrument(name, payload = {}) if @instrumenters[name] instrumenter.instrument(name, payload) { yield payload if block_given? } else yield payload if block_given? end end |
.instrumenter ⇒ Object
147 148 149 |
# File 'lib/active_support/notifications.rb', line 147 def instrumenter Thread.current[:"instrumentation_#{notifier.object_id}"] ||= Instrumenter.new(notifier) end |
.publish(name, *args) ⇒ Object
117 118 119 |
# File 'lib/active_support/notifications.rb', line 117 def publish(name, *args) notifier.publish(name, *args) end |
.subscribe(*args, &block) ⇒ Object
129 130 131 132 133 |
# File 'lib/active_support/notifications.rb', line 129 def subscribe(*args, &block) notifier.subscribe(*args, &block).tap do @instrumenters.clear end end |
.subscribed(callback, *args, &block) ⇒ Object
135 136 137 138 139 140 |
# File 'lib/active_support/notifications.rb', line 135 def subscribed(callback, *args, &block) subscriber = subscribe(*args, &callback) yield ensure unsubscribe(subscriber) end |
.unsubscribe(args) ⇒ Object
142 143 144 145 |
# File 'lib/active_support/notifications.rb', line 142 def unsubscribe(args) notifier.unsubscribe(args) @instrumenters.clear end |