lib/event.cf

Table of Contents

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 type
  • name: The event name
  • persistence: 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 all
  • type: 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 from event_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 from event_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) };
}