Module: Webmachine::Events

Defined in:
lib/webmachine/events.rb,
lib/webmachine/events/instrumented_event.rb

Overview

Events implements the [ActiveSupport::Notifications](rubydoc.info/gems/activesupport/ActiveSupport/Notifications) instrumentation API. It delegates to the configured backend. The default backend is [AS::Notifications](rubydoc.info/gems/as-notifications/AS/Notifications).

# Published events

Webmachine publishes some internal events by default. All of them use the ‘wm.` prefix.

## ‘wm.dispatch` (Events.instrument)

The payload hash includes the following keys.

  • ‘:resource` - The resource class name

  • ‘:request` - A copy of the request object

  • ‘:code` - The response code

Defined Under Namespace

Classes: InstrumentedEvent

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.backend ⇒ Object

The class that Webmachine::Events delegates all messages to. (default [AS::Notifications](rubydoc.info/gems/as-notifications/AS/Notifications))

It can be changed to an [ActiveSupport::Notifications](rubydoc.info/gems/activesupport/ActiveSupport/Notifications) compatible backend early in the application startup process.

Examples:

require 'webmachine'
require 'active_support/notifications'

Webmachine::Events.backend = ActiveSupport::Notifications

Webmachine::Application.new {|app|
  # setup application
}.run


43
44
45
 
# File 'lib/webmachine/events.rb', line 43

def backend
  @backend
end

Class Method Details

.instrument(name, payload = {}, &block) ⇒ Object

Instrument the given block by measuring the time taken to execute it and publish it. Notice that events get sent even if an error occurs in the passed-in block.

If an exception happens during an 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. (when using the default [AS::Notifications](rubydoc.info/gems/as-notifications/AS/Notifications) backend)

Examples:

Webmachine::Events.instrument('wm.dispatch') do |payload|
  execute_some_method

  payload[:custom_payload_value] = 'important'
end

Parameters:

  • name (String) —

    the event name

  • payload (Hash) (defaults to: {}) —

    the initial payload



74
75
76
 
# File 'lib/webmachine/events.rb', line 74

def instrument(name, payload = {}, &block)
  backend.instrument(name, payload, &block)
end

.publish(name, *args) ⇒ Object

Publishes the given arguments to all listeners subscribed to the given event name.

Examples:

Webmachine::Events.publish('wm.foo', :hello => 'world')

Parameters:

  • name (String) —

    the event name



50
51
52
 
# File 'lib/webmachine/events.rb', line 50

def publish(name, *args)
  backend.publish(name, *args)
end

.subscribe(name) {|name, start, end, event_id, payload| ... } ⇒ Object .subscribe(name) {|name, *args| ... } ⇒ Object .subscribe(name, listener) ⇒ Object

Note:

The documentation of this method describes its behaviour with the default backed [AS::Notifications](rubydoc.info/gems/as-notifications/AS/Notifications). It can change if a different backend is used.

Subscribes to the given event name.

Overloads:

  • .subscribe(name) {|name, start, end, event_id, payload| ... } ⇒ Object

    Subscribing to an instrument event. The block arguments can be passed to InstrumentedEvent.

    Examples:

    # Subscribe to all 'wm.dispatch' events
Webmachine::Events.subscribe('wm.dispatch') {|*args|
  event = Webmachine::Events::InstrumentedEvent.new(*args)
}

# Subscribe to all events that start with 'wm.'
Webmachine::Events.subscribe(/wm\.*/) {|*args| }

    Parameters:

    • name (String, Regexp) —

      the event name to subscribe to

    Yield Parameters:

    • name (String) —

      the event name

    • start (Time) —

      the event start time

    • end (Time) —

      the event end time

    • event_id (String) —

      the event id

    • payload (Hash) —

      the event payload

    Returns:

    • (Object) —

      the subscriber object (type depends on the backend implementation)

  • .subscribe(name) {|name, *args| ... } ⇒ Object

    Subscribing to a publish event.

    Examples:

    Webmachine::Events.subscribe('custom.event') {|name, *args|
  args #=> [obj1, obj2, {:num => 1}]
}

Webmachine::Events.publish('custom.event', obj1, obj2, {:num => 1})

    Parameters:

    • name (String, Regexp) —

      the event name to subscribe to

    Yield Parameters:

    • name (String) —

      the event name

    • *args (Array) —

      the published arguments

    Returns:

    • (Object) —

      the subscriber object (type depends on the backend implementation)

  • .subscribe(name, listener) ⇒ Object

    Subscribing with a listener object instead of a block. The listener object must respond to ‘#call`.

    Examples:

    class CustomListener
  def call(name, *args)
    # ...
  end
end

Webmachine::Events.subscribe('wm.dispatch', CustomListener.new)

    Parameters:

    • name (String, Regexp) —

      the event name to subscribe to

    • listener (#call) —

      a listener object

    Returns:

    • (Object) —

      the subscriber object (type depends on the backend implementation)



137
138
139
 
# File 'lib/webmachine/events.rb', line 137

def subscribe(name, *args, &block)
  backend.subscribe(name, *args, &block)
end

.subscribed(callback, name, &block) ⇒ Object

Note:

The documentation of this method describes its behaviour with the default backed [AS::Notifications](rubydoc.info/gems/as-notifications/AS/Notifications). It can change if a different backend is used.

Subscribe to an event temporarily while the block runs.

The callback in the following example will be called for all “sql.active_record” events instrumented during the execution of the block. The callback is unsubscribed automatically after that.

Examples:

callback = lambda {|name, *args| handle_event(name, *args) }

Webmachine::Events.subscribed(callback, 'sql.active_record') do
  call_active_record
end


157
158
159
 
# File 'lib/webmachine/events.rb', line 157

def subscribed(callback, name, &block)
  backend.subscribed(callback, name, &block)
end

.unsubscribe(subscriber) ⇒ Object

Note:

The documentation of this method describes its behaviour with the default backed [AS::Notifications](rubydoc.info/gems/as-notifications/AS/Notifications). It can change if a different backend is used.

Unsubscribes the given subscriber.

Examples:

subscriber = Webmachine::Events.subscribe('wm.dispatch') {|*args| }

Webmachine::Events.unsubscribe(subscriber)

Parameters:

  • subscriber (Object) —

    the subscriber object (type depends on the backend implementation)



172
173
174
 
# File 'lib/webmachine/events.rb', line 172

def unsubscribe(subscriber)
  backend.unsubscribe(subscriber)
end