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)dorenderplain:'Foo'end
That first executes the block and then notifies all subscribers once done.
In the example aboverender is the name of the event, and the rest is called thepayload. 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.
ActiveSupport::Notifications.subscribe('render')do|event|event.name# => "render"event.duration# => 10 (in milliseconds)event.payload# => { extra: :information }event.allocations# => 1826 (objects)end
Event objects record CPU time and allocations. If you don’t need this it’s also possible to pass a block that accepts five arguments:
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 executionfinish# => Time, when the instrumented block ended executionid# => String, unique ID for the instrumenter that fired the eventpayload# => Hash, the payloadend
Here, thestart andfinish values represent wall-clock time. If you are concerned about accuracy, you can register a monotonic subscriber.
ActiveSupport::Notifications.monotonic_subscribe('render')do|name,start,finish,id,payload|name# => String, name of the event (such as 'render' from above)start# => Float, monotonic time when the instrumented block started executionfinish# => Float, monotonic time when the instrumented block ended executionid# => String, unique ID for the instrumenter that fired the eventpayload# => Hash, the payloadend
For instance, let’s store all “render” events in an array:
events = []ActiveSupport::Notifications.subscribe('render')do|event|events<<eventend
That code returns right away, you are just subscribing to “render” events. The block is saved and will be called whenever someone instruments “render”:
ActiveSupport::Notifications.instrument('render',extra::information)dorenderplain:'Foo'endevent =events.firstevent.name# => "render"event.duration# => 10 (in milliseconds)event.payload# => { extra: :information }event.allocations# => 1826 (objects)
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. The:exception_object key of the payload will have the exception itself as the value:
event.payload[:exception]# => ["ArgumentError", "Invalid value"]event.payload[:exception_object]# => #<ArgumentError: Invalid value>
As the earlier example depicts, the classActiveSupport::Notifications::Event is able to take the arguments as they come and provide an object-oriented interface to that data.
It is also possible to pass an object which responds tocall method as the second parameter to thesubscribe method instead of a block:
moduleActionControllerclassPageRequestdefcall(name,started,finished,unique_id,payload)Rails.logger.debug ['notification:',name,started,finished,unique_id,payload].join(' ')endendendActiveSupport::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 { 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 }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 tosubscribe, 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 {|event| ... }ActiveSupport::Notifications.subscribed(callback, "sql.active_record") do ...endthe callback will be called for all “sql.active_record” events instrumented during the execution of the block. The callback is unsubscribed automatically after that.
To recordstarted andfinished values with monotonic time, specify the optional:monotonic option to thesubscribed method. The:monotonic option is set tofalse by default.
callback = lambda {|name, started, finished, unique_id, payload| ... }ActiveSupport::Notifications.subscribed(callback, "sql.active_record", monotonic: true) do ...endManual Unsubscription¶↑
Thesubscribe method returns a subscriber object:
subscriber = ActiveSupport::Notifications.subscribe("render") do |event| ...endTo prevent that block from being called anymore, just unsubscribe passing that reference:
ActiveSupport::Notifications.unsubscribe(subscriber)
You can also unsubscribe by passing the name of the subscriber object. Note that this will unsubscribe all subscriptions with the given name:
ActiveSupport::Notifications.unsubscribe("render")
Subscribers using a regexp or other pattern-matching object will remain subscribed to all events that match their original pattern, unless those events match a string passed tounsubscribe:
subscriber =ActiveSupport::Notifications.subscribe(/render/) { }ActiveSupport::Notifications.unsubscribe('render_template.action_view')subscriber.matches?('render_template.action_view')# => falsesubscriber.matches?('render_partial.action_view')# => true
Default Queue¶↑
Notifications ships with a queue implementation that consumes and publishes events to all log subscribers. You can use any queue implementation you want.
- CLASSActiveSupport::Notifications::Event
- CLASSActiveSupport::Notifications::Fanout
- CLASSActiveSupport::Notifications::InstrumentationSubscriberError
- CLASSActiveSupport::Notifications::Instrumenter
Attributes
| [RW] | notifier |
Class Public methods
instrument(name, payload = {})Link
instrumenter()Link
monotonic_subscribe(pattern = nil, callback = nil, &block)Link
Performs the same functionality as subscribe, but thestart andfinish block arguments are in monotonic time instead of wall-clock time. Monotonic time will not jump forward or backward (due to NTP or Daylights Savings). Usemonotonic_subscribe when accuracy of time duration is important. For example, computing elapsed time between two events.
publish(name, *args)Link
subscribe(pattern = nil, callback = nil, &block)Link
Subscribe to a given event name with the passedblock.
You can subscribe to events by passing aString to match exact event names, or by passing aRegexp to match all events that match a pattern.
If the block passed to the method only takes one argument, it will yield anEvent object to the block:
ActiveSupport::Notifications.subscribe(/render/)do|event|@event =eventend
Otherwise theblock will receive five arguments with information about the event:
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 executionfinish# => Time, when the instrumented block ended executionid# => String, unique ID for the instrumenter that fired the eventpayload# => Hash, the payloadend
Raises an error if invalid event name type is passed:
ActiveSupport::Notifications.subscribe(:render) {|event| ...}#=> ArgumentError (pattern must be specified as a String, Regexp or empty)