| Overview |  |
Behaviours: gen_server2.
Riak events provide information about what is happening behind-the-scenes in a Riak cluster.
Events are generated using notify/1 or notify/3.
Each event consists of a Module, an EventName, the Node on which
the event is generated, and additional detail about the event.
A process can register to receive evets using
add_handler/4. Full ETS MatchSpec style matching is supported, allowing
the process to receive a subset of events, if desired. Filtering occurs at the
server level.
An application can register multiple event handlers, and can register multiple filters for a single pid.
Riak monitors running handlers, and automatically removes handlers of dead processors. Alternatively, an event handler can be removed usingremove_handler/3.
event() = {EventModule::atom(), EventName::atom(), Node::atom(), EventData::term()}
eventmessage() = {event, Event::event()}
| add_handler/4 | Register a process that will receive Riak events generated by the cluster. |
| notify/1 | Generate an event that will be sent to all handlers whose MatchSpecs match the event. |
| notify/3 | Equivalent to notify({EventModule, EventName, node(), EventDetail}). |
| remove_handler/3 | Remove the previously registered event handler. |
add_handler(Pid::pid(), Desc::string(), MatchHead::tuple(), MatchGuard::tuple()) -> ok
Register a process that will receive Riak events
generated by the cluster. Events are Erlang messages in the form
{event, {EventModule, EventName, Node, EventData}}.
During operation, Riak generates events for reporting
and monitoring purposes. By registering an event handler
an application can choose to receive all or a subset of these events.
Riak allows for an unlimited number of event handlers (bounded only by memory).
When an event handler process dies, Riak automatically removes
that event handler from the list of event handlers. Alternatively,
an event handler can be programatically removed via the
remove_handler/3 function.
Event handlers are judged to be unique based on the Pid, MatchHead, and MatchGuard. In other words, multiple event handlers can be wired to the same pid so long as either their MatchHead or MatchGuard is different. If add_handler/4 is called twice with the same exact same Pid, MatchHead, and MatchGuard, then the old handler is replaced by the new handler.
In addition, while registering an event handler, a developer can choose to filter the events that the event handler will receive. This filtering happens on the node generating the event. Riak generates a large number of events, so tight filtering is a good idea in order to minimize network traffic.
An event filter is specified using the MatchSpec syntax established by the ETS module. See ETS MatchSpec for more information.
Register for all events generated by the node 'riak@127.0.0.1':
RiakClient:add_event_handler(self(), "Description", {'_', '_', 'riak@127.0.0.1', '_'}, [])).
Register for all events generated by the riak_vnode module:
RiakClient:add_event_handler(self(), "Description", {riak_vnode, '_', '_', '_'}, []))
Register for all 'put', 'get', and 'delete' events generated by the riak_vnode module:
MatchHead = {'$1', '$2', '_', '_'},
MatchGuard = [
{'andalso', {'==', '$1', riak_vnode}, {'orelse', {'==', '$2', get}, {'==', '$2', put}, {'==', '$2', delete}}}
],
RiakClient:add_event_handler(self(), "Description", MatchHead, MatchGuard).
Events are sent once per matching filter. If a single process registers under more than one MatchSpecs, and an event matches both MatchSpecs, then the process will receive the event multiple times.
The Description parameter is used to supply a human readable string used by monitoring software to displaying connected event handlers.
Because of the way Riak shares information between clusters, it may be a few seconds before events start being sent to the handler from all nodes.notify(Event::event()) -> ok
Generate an event that will be sent to all handlers whose MatchSpecs match the event.
notify(EventModule::atom(), EventName::atom(), EventDetail::term()) -> ok
Equivalent to notify({EventModule, EventName, node(), EventDetail}).
remove_handler(Pid::pid(), MatchHead::tuple(), MatchGuard::list()) -> ok
Remove the previously registered event handler. The arguments supplied to remove_handler/3 must be the same arguments supplied to add_handler/4. remove_handler/3 returns 'ok' regardless of whether any event handlers are removed.
Because of the way Riak shares information between clusters, it may be a few seconds before events stop being sent to the handler.Generated by EDoc, Mar 10 2010, 09:21:17.