contrib/examples/MyPlugin.pm

   1 # /usr/share/doc/collectd/examples/MyPlugin.pm
   2 #
   3 # A Perl plugin template for collectd.
   4 #
   5 # Written by Sebastian Harl <sh@tokkee.org>
   6 #
   7 # This is free software; you can redistribute it and/or modify it under
   8 # the terms of the GNU General Public License as published by the Free
   9 # Software Foundation; only version 2 of the License is applicable.
  10
  11 # Notes:
  12 # - each of the functions below (and the corresponding plugin_register call)
  13 #   is optional
  14
  15 package Collectd::Plugin::MyPlugin;
  16
  17 use strict;
  18 use warnings;
  19
  20 # data set definition:
  21 # see section "DATA TYPES" in collectd-perl(5) for details
  22 my $dataset =
  23 [
  24         {
  25                 name => 'my_ds',
  26                 type => Collectd::DS_TYPE_GAUGE,
  27                 min  => 0,
  28                 max  => 65535,
  29         },
  30 ];
  31
  32 # This code is executed after loading the plugin to register it with collectd.
  33 Collectd::plugin_register (Collectd::TYPE_LOG, 'myplugin', \&my_log);
  34 Collectd::plugin_register (Collectd::TYPE_DATASET, 'myplugin', $dataset);
  35 Collectd::plugin_register (Collectd::TYPE_INIT, 'myplugin', \&my_init);
  36 Collectd::plugin_register (Collectd::TYPE_READ, 'myplugin', \&my_read);
  37 Collectd::plugin_register (Collectd::TYPE_WRITE, 'myplugin', \&my_write);
  38 Collectd::plugin_register (Collectd::TYPE_SHUTDOWN, 'myplugin', \&my_shutdown);
  39
  40 # For each of the functions below see collectd-perl(5) for details about
  41 # arguments and the like.
  42
  43 # This function is called once upon startup to initialize the plugin.
  44 sub my_init
  45 {
  46         # open sockets, initialize data structures, ...
  47
  48         # A false return value indicates an error and causes the plugin to be
  49         # disabled.
  50         return 1;
  51 } # my_init ()
  52
  53 # This function is called in regular intervals to collectd the data.
  54 sub my_read
  55 {
  56         # value list to dispatch to collectd:
  57         # see section "DATA TYPES" in collectd-perl(5) for details
  58         my $vl = {};
  59
  60         # do the magic to read the data:
  61         # the number of values has to match the number of data sources defined in
  62         # the registered data set
  63         $vl->{'values'} = [ rand(65535) ];
  64         $vl->{'plugin'} = 'myplugin';
  65         # any other elements are optional
  66
  67         # dispatch the values to collectd which passes them on to all registered
  68         # write functions - the first argument is used to lookup the data set
  69         # definition
  70         Collectd::plugin_dispatch_values ('myplugin', $vl);
  71
  72         # A false return value indicates an error and the plugin will be skipped
  73         # for an increasing amount of time.
  74         return 1;
  75 } # my_read ()
  76
  77 # This function is called after values have been dispatched to collectd.
  78 sub my_write
  79 {
  80         my $type = shift;
  81         my $ds   = shift;
  82         my $vl   = shift;
  83
  84         if (scalar (@$ds) != scalar (@{$vl->{'values'}})) {
  85                 Collectd::plugin_log (Collectd::LOG_WARNING,
  86                         "DS number does not match values length");
  87                 return;
  88         }
  89
  90         for (my $i = 0; $i < scalar (@$ds); ++$i) {
  91                 # do the magic to output the data
  92                 print "$vl->{'host'}: $vl->{'plugin'}: ";
  93
  94                 if (defined $vl->{'plugin_instance'}) {
  95                         print "$vl->{'plugin_instance'}: ";
  96                 }
  97
  98                 print "$type: ";
  99
 100                 if (defined $vl->{'type_instance'}) {
 101                         print "$vl->{'type_instance'}: ";
 102                 }
 103
 104                 print "$vl->{'values'}->[$i]\n";
 105         }
 106         return 1;
 107 } # my_write()
 108
 109 # This function is called before shutting down collectd.
 110 sub my_shutdown
 111 {
 112         # close sockets, ...
 113         return 1;
 114 } # my_shutdown ()
 115
 116 # This function is called when plugin_log () has been used.
 117 sub my_log
 118 {
 119         my $level = shift;
 120         my $msg   = shift;
 121
 122         print "LOG: $level - $msg\n";
 123         return 1;
 124 } # my_log ()
 125