lib/event.cf
agent bundles
event_register
Prototype: event_register(prefix, type, name, persistence, metadata)
Description: Register a event_$(prefix)_$(type)_$(name)
class with meta=metadata
Arguments:
prefix
: The prefix (usually the issuing bundle name)type
: The event typename
: The event namepersistence
: the time, in minutes, the class should persist on disk (unless collected)metadata
: A slist with the event metadata
This bundle creates a class that conforms to the ad-hoc event protocol defined herein.
See also: event_handle
Implementation:
bundle agent event_register(prefix, type, name, persistence, metadata)
{
vars:
"e" string => "event_$(prefix)_$(type)_$(name)";
"metadata_string" string => format("%S", metadata);
classes:
"$(e)" scope => "namespace",
persistence => $(persistence),
meta => { "event", "prefix=$(prefix)", "type=$(type)", "name=$(name)", @(metadata) };
reports:
inform_mode::
"$(this.bundle): creating event $(e) persistent for $(persistence) minutes with metadata $(metadata_string)";
}
event_handle
Prototype: event_handle(prefix, type)
Description: Handle all the events matching prefix
and type
through delegation
Arguments:
prefix
: A prefix for the event, can be.*
for alltype
: A type for the event, can be.*
for all
This bundle looks for all the event classes matching prefix
and type
, then
for all the bundles that have declared they can handle that prefix and type,
and then passes the corresponding event classes to each bundle.
See also: event_register
Implementation:
bundle agent event_handle(prefix, type)
{
vars:
"events_prefix" slist => classesmatching("event_.*", "prefix=$(prefix)");
"events_type" slist => classesmatching("event_.*", "type=$(type)");
"events" slist => intersection(events_prefix, events_type);
"events_string" string => format("%S", events);
"handlers_prefix" slist => bundlesmatching("default:event_.*", format("event_prefix=(%s|ALL)", escape($(prefix))));
"handlers_type" slist => bundlesmatching("default:event_.*", format("event_type=(%s|ALL)", escape($(type))));
"handlers" slist => intersection(handlers_prefix, handlers_type);
"handlers_string" string => format("%S", handlers);
methods:
"" usebundle => $(handlers)(@(events)),
classes => event_cancel_events(@(events));
reports:
inform_mode::
"$(this.bundle): with prefix $(prefix) and type $(type) found events $(events_string)";
"$(this.bundle): with prefix $(prefix) and type $(type) found handlers $(handlers_string)";
}
event_debug_handler
Prototype: event_debug_handler(events)
Description: Debug all the events matching the meta tags event_prefix
and event_type
Arguments:
events
: The list of events, passed fromevent_handle
This is an event handler that just prints out all the events it finds. To be
registered as a handler, it must have the meta tags
indicated below.
See also: event_handle
, event_register
Implementation:
bundle agent event_debug_handler(events)
{
meta:
"tags" slist => { "event_handler", "event_prefix=.*", "event_type=.*" };
vars:
"events_string" string => format("%S", events);
"tags_string" string => format("%S", "$(this.bundle)_meta.tags");
reports:
inform_mode::
"$(this.bundle): with tags $(tags_string) got events $(events_string)";
}
event_install_handler
Prototype: event_install_handler(events)
Description: Handle all the install events matching the meta tags event_prefix
and event_type
Arguments:
events
: The list of events, passed fromevent_handle
This is an event handler that just prints out all the install events it finds.
To be registered as a handler, it must have the meta tags
indicated below.
The subtlety in event_prefix=ALL
is that we want to match only
event_handle(ANYTHING, "install")
but not event_handle(".*", ANYTHING)
. If
you're confused, just remember: debug handlers use event_prefix=.*
and
everything else uses event_prefix=ALL
.
See also: event_handle
, event_register
Implementation:
bundle agent event_install_handler(events)
{
meta:
"tags" slist => { "event_handler", "event_prefix=ALL", "event_type=install" };
vars:
"events_string" string => format("%S", events);
"tags_string" string => format("%S", "$(this.bundle)_meta.tags");
reports:
inform_mode::
"$(this.bundle): with tags $(tags_string) got events $(events_string)";
}
event_usage_example
Prototype: event_usage_example
Description: Simple demo of event_register and event_handle usage
You can run it like this: cf-agent -K ./event.cf -b event_usage_example
Or for extra debugging, you can run it like this: cf-agent -KI ./event.cf -b event_usage_example
See also: event_handle
, event_register
Expected output with -KI
:
R: event_register: creating event event_event_usage_example_restart_apache persistent for 1440 minutes with metadata { }
R: event_register: creating event event_event_usage_example_install_php persistent for 2880 minutes with metadata { }
R: event_install_handler: with tags { "event_handler", "event_prefix=ALL", "event_type=install" } got events { "event_event_usage_example_install_php" }
R: event_handle: with prefix event_usage_example and type install found events { "event_event_usage_example_install_php" }
R: event_handle: with prefix event_usage_example and type install found handlers { "default:event_install_handler" }
R: event_debug_handler: with tags { "event_handler", "event_prefix=.*", "event_type=.*" } got events { "event_event_usage_example_restart_apache", "event_event_usage_example_install_php" }
R: event_handle: with prefix .* and type .* found events { "event_event_usage_example_restart_apache", "event_event_usage_example_install_php" }
R: event_handle: with prefix .* and type .* found handlers { "default:event_debug_handler" }
Implementation:
bundle agent event_usage_example
{
vars:
"empty" slist => {};
methods:
# register a restart event named "apache" with persistence = 1 day
"" usebundle => event_register($(this.bundle), "restart", "apache", 1440, @(empty)); # 1 day
# register an install event named "php" with persistence = 2 days
"" usebundle => event_register($(this.bundle), "install", "php", 2880, @(empty));
# the following can be run immediately, or up to 2 days later to collect
# the install event above
"" usebundle => event_handle($(this.bundle), "install");
# the following can be run immediately, or up to 1 day later to collect
# the restart event above
"" usebundle => event_handle(".*", ".*");
}
classes bodies
event_cancel_events
Prototype: event_cancel_events(events)
Description: Cancel any events
Arguments:
events
: A slist of events to cancel
Implementation:
body classes event_cancel_events(events)
{
cancel_notkept => { @(events) };
cancel_kept => { @(events) };
cancel_repaired => { @(events) };
}