perl plugin: Added a plugin to embed a Perl interpreter into collectd.
authorSebastian Harl <sh@tokkee.org>
Mon, 9 Apr 2007 16:26:48 +0000 (18:26 +0200)
committerFlorian Forster <octo@leeloo.lan.home.verplant.org>
Mon, 9 Apr 2007 22:17:52 +0000 (00:17 +0200)
commit3f0a64bdf677571a791988a934f43516246f9a0e
tree98c4523aada7a9b6f6b529d3d3ddb2e9cde91377
parentc5207d43c5a998dbeee023d5d2889172e8dd4bf3
perl plugin: Added a plugin to embed a Perl interpreter into collectd.

This is the long awaited plugin that makes it possible to write plugins in
plain Perl. This is my first glance at using Perl's C API, so I'm pretty sure
there are some things that could habe been done better. Much of the plugin
could have been written in Perl as well, but I decided not to do so mainly for
exercise reasons ;-)

This plugin still needs a lot of testing. Also comments on the API, code, etc.
are very welcome.

Basically, the plugin is just the glue that's required for Perl plugins to
access collectd's internals. The following API is currently available:

Collectd::plugin_register:
  register working functions or data sets with collectd

  arguments:
  type - type of the registered data
  name - name of the plugin
  data - reference to the plugin's working subroutine or the data set

Collectd::plugin_unregister:
  unregister working functions or data sets from collectd

  arguments:
  type - type of the data to be unregistered
  name - name of the plugin

Collectd::plugin_dispatch_values:
  dispatch the collected values to the write functions

  arguments:
  name - name of the plugin
  values - list of values to submit

The plugin type may be any of the following:
  Collectd::TYPE_INIT
  Collectd::TYPE_READ
  Collectd::TYPE_WRITE
  Collectd::TYPE_LOG
  Collectd::TYPE_SHUTDOWN
  Collectd::TYPE_DATASET

A data set is represented as a reference to an array containing hashes with the
following elements:
  name => $ds_name (required)
  type => $ds_type (default: COUNTER)
  min  => $ds_min (default: NAN)
  max  => $ds_max (default: NAN)

A value list is represented as a reference to a hash with the following
elements:
  values => [ @values ] (required)
  time   => $time (default: time(NULL))
  host   => $hostname (default: hostname_g)
  plugin => $plugin (default: "")
  plugin_instance => $plugin_instance (default: "")
  type_instance   => $type_instance (default: "")

The default value is used whenever the element is not defined.

Three arguments are passed to write functions: the plugin's type, the plugin's
data set and the value list.

Two arguments are passed to log functions: the log level and the log message.

In case a function returns false (as interpreted by Perl) the following actions
are taken depending on the function type:
  read: the function will be disabled for an increasing amount of time
  init: the plugin will be disabled completely
  anything else: a warning is logged

In addition to the ones listed above the following constants are also exported:
  Collectd::DS_TYPE_COUNTER
  Collectd::DS_TYPE_GAUGE
  Collectd::LOG_ERR
  Collectd::LOG_WARNING
  Collectd::LOG_NOTICE
  Collectd::LOG_INFO
  Collectd::LOG_DEBUG

There is no need to load any Collectd modules - everything is completely
integrated into collectd.

TODO:
  add support for accessing the config file
  write documentation
  add checks for perl to configure

Signed-off-by: Sebastian Harl <sh@tokkee.org>
AUTHORS
configure.in
src/Makefile.am
src/collectd.conf.in
src/perl.c [new file with mode: 0644]