1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
module ActiveSupport
# = 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.
#
module Notifications
autoload :Instrumenter, 'active_support/notifications/instrumenter'
autoload :Event, 'active_support/notifications/instrumenter'
autoload :Fanout, 'active_support/notifications/fanout'
@instrumenters = Hash.new { |h,k| h[k] = notifier.listening?(k) }
class << self
attr_accessor :notifier
def publish(name, *args)
notifier.publish(name, *args)
end
def instrument(name, payload = {})
if @instrumenters[name]
instrumenter.instrument(name, payload) { yield payload if block_given? }
else
yield payload if block_given?
end
end
def subscribe(*args, &block)
notifier.subscribe(*args, &block).tap do
@instrumenters.clear
end
end
def subscribed(callback, *args, &block)
subscriber = subscribe(*args, &callback)
yield
ensure
unsubscribe(subscriber)
end
def unsubscribe(args)
notifier.unsubscribe(args)
@instrumenters.clear
end
def instrumenter
Thread.current[:"instrumentation_#{notifier.object_id}"] ||= Instrumenter.new(notifier)
end
end
self.notifier = Fanout.new
end
end
|
