Skip to content
This repository
Browse code

[ci skip] Add examples of subscribing & creating ActiveSupport::Notif…

…ications
  • Loading branch information...
commit 18e1b5b8c5d7c5fd4a73a9f896f59e1ab03781bf 1 parent 2784e64
adman65 authored
74 railties/guides/source/active_support_instrumentation.textile
Source Rendered
@@ -361,7 +361,6 @@ h4. cache_exist?.active_support
361 361 }
362 362 </ruby>
363 363
364   -
365 364 h3. Rails
366 365
367 366 h4. deprecation.rails
@@ -372,5 +371,78 @@ h4. deprecation.rails
372 371
373 372 h3. Subscribing to an event
374 373
  374 +Subscribing to an event is easy. Use +ActiveSupport::Notifications.subscribe+ with a block to
  375 +listen to any notification.
  376 +
  377 +The block receives the following arguments:
  378 +
  379 +# The name of the event
  380 +# Time when is started
  381 +# Time when it finished
  382 +# An unique ID for this event
  383 +# The payload (described in previous sections)
  384 +
  385 +<ruby>
  386 +ActiveSupport::Notifications.subscribe "process_action.action_controller do |name, started, finished, unique_id, data|
  387 + # your own custom stuff
  388 + Rails.logger.info "#{name} Received!"
  389 +end
  390 +</ruby>
  391 +
  392 +Defining all those block arguments each time can be tedious. You can easily create an +ActiveSupport::Notifications::Event+
  393 +from block args like this:
  394 +
  395 +<ruby>
  396 +ActiveSupport::Notifications.subscribe "process_action.action_controller do |*args|
  397 + event = ActiveSupport::Notification::Event.new args
  398 +
  399 + event.name # => "process_action.action_controller"
  400 + event.duration # => 10 (in milliseconds)
  401 + event.payload # => { :extra => :information }
  402 +
  403 + Rails.logger.info "#{event} Received!"
  404 +end
  405 +</ruby>
  406 +
  407 +Most times you only care about the data itself. Here is a shortuct to just get the data.
  408 +
  409 +<ruby>
  410 +ActiveSupport::Notifications.subscribe "process_action.action_controller do |*args|
  411 + data = args.extract_options!
  412 + data # { :extra => :information }
  413 +</ruby>
  414 +
  415 +You may also subscribe to events matching a regular expresssion. This enables you to subscribe to
  416 +multiple events at once. Here's you could subscribe to everything from +ActionController+.
  417 +
  418 +<ruby>
  419 +ActiveSupport::Notifications.subscribe /action_controller/ do |*args|
  420 + # inspect all ActionController events
  421 +end
  422 +</ruby>
  423 +
375 424 h3. Creating custom events
376 425
  426 +Adding your own events is easy as well. +ActiveSupport::Notifications+ will take care of
  427 +all the heavy lifting for you. Simply call +instrument+ with a +name+, +payload+ and a block.
  428 +The notification will be sent after the block returns. +ActiveSupport+ will generate the start and end times
  429 +as well as the unique ID. All data passed into the +insturment+ call will make it into the payload.
  430 +
  431 +Here's an example:
  432 +
  433 +<ruby>
  434 +ActiveSupport::Notifications.instrument "my.custom.event", :this => :data do
  435 + # do your custom stuff here
  436 +end
  437 +</ruby>
  438 +
  439 +Now you can listen to this event with:
  440 +
  441 +<ruby>
  442 +ActiveSupport::Notifications.subscribe "my.custom.event" do |name, started, finished, unique_id, data|
  443 + puts data.inspect # { :this => :data }
  444 +end
  445 +</ruby>
  446 +
  447 +You should follow Rails conventions when defining your own events. The format is: +event.library+.
  448 +If you application is sending Tweets, you should create an event named +tweet.twitter+.

0 comments on commit 18e1b5b

Please sign in to comment.
Something went wrong with that request. Please try again.