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) };
}

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(".*", ".*");
}