Module: ActiveSupport::Notifications

Defined in:
activesupport/lib/active_support/notifications.rb,
activesupport/lib/active_support/notifications/fanout.rb,
activesupport/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

Class Method Summary collapse

Class Attribute Details

.notifier ⇒ Object

Returns the value of attribute notifier



115
116
117
 
# File 'activesupport/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 'activesupport/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 'activesupport/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 'activesupport/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 'activesupport/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 'activesupport/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 'activesupport/lib/active_support/notifications.rb', line 142

def unsubscribe(args)
  notifier.unsubscribe(args)
  @instrumenters.clear
end