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 use Collectd qw( :all );
  21
  22 # data set definition:
  23 # see section "DATA TYPES" in collectd-perl(5) for details
  24 #
  25 # NOTE: If you're defining a custom data-set, you have to make that known to
  26 # any servers as well. Else, the server is not able to store values using the
  27 # type defined by that data-set.
  28 # It is strongly recommended to use one of the types and data-sets pre-defined
  29 # in the types.db file.
  30 my $dataset =
  31 [
  32         {
  33                 name => 'my_ds',
  34                 type => DS_TYPE_GAUGE,
  35                 min  => 0,
  36                 max  => 65535,
  37         },
  38 ];
  39
  40 # This code is executed after loading the plugin to register it with collectd.
  41 plugin_register (TYPE_LOG, 'myplugin', 'my_log');
  42 plugin_register (TYPE_NOTIF, 'myplugin', 'my_notify');
  43 plugin_register (TYPE_DATASET, 'mytype', $dataset);
  44 plugin_register (TYPE_INIT, 'myplugin', 'my_init');
  45 plugin_register (TYPE_READ, 'myplugin', 'my_read');
  46 plugin_register (TYPE_WRITE, 'myplugin', 'my_write');
  47 plugin_register (TYPE_SHUTDOWN, 'myplugin', 'my_shutdown');
  48
  49 # For each of the functions below see collectd-perl(5) for details about
  50 # arguments and the like.
  51
  52 # This function is called once upon startup to initialize the plugin.
  53 sub my_init
  54 {
  55         # open sockets, initialize data structures, ...
  56
  57         # A false return value indicates an error and causes the plugin to be
  58         # disabled.
  59         return 1;
  60 } # my_init ()
  61
  62 # This function is called in regular intervals to collectd the data.
  63 sub my_read
  64 {
  65         # value list to dispatch to collectd:
  66         # see section "DATA TYPES" in collectd-perl(5) for details
  67         my $vl = {};
  68
  69         # do the magic to read the data:
  70         # the number of values has to match the number of data sources defined in
  71         # the registered data set. The type used here (in this example:
  72         # "mytype") must be defined in the types.db, see types.db(5) for
  73         # details, or registered as "TYPE_DATASET".
  74         $vl->{'values'} = [ rand(65535) ];
  75         $vl->{'plugin'} = 'myplugin';
  76         $vl->{'type'}   = 'mytype';
  77         # any other elements are optional
  78
  79         # dispatch the values to collectd which passes them on to all registered
  80         # write functions
  81         plugin_dispatch_values ($vl);
  82
  83         # A false return value indicates an error and the plugin will be skipped
  84         # for an increasing amount of time.
  85         return 1;
  86 } # my_read ()
  87
  88 # This function is called after values have been dispatched to collectd.
  89 sub my_write
  90 {
  91         my $type = shift;
  92         my $ds   = shift;
  93         my $vl   = shift;
  94
  95         if (scalar (@$ds) != scalar (@{$vl->{'values'}})) {
  96                 plugin_log (LOG_WARNING, "DS number does not match values length");
  97                 return;
  98         }
  99
 100         for (my $i = 0; $i < scalar (@$ds); ++$i) {
 101                 # do the magic to output the data
 102                 print "$vl->{'host'}: $vl->{'plugin'}: ";
 103
 104                 if (defined $vl->{'plugin_instance'}) {
 105                         print "$vl->{'plugin_instance'}: ";
 106                 }
 107
 108                 print "$type: ";
 109
 110                 if (defined $vl->{'type_instance'}) {
 111                         print "$vl->{'type_instance'}: ";
 112                 }
 113
 114                 print "$vl->{'values'}->[$i]\n";
 115         }
 116         return 1;
 117 } # my_write()
 118
 119 # This function is called before shutting down collectd.
 120 sub my_shutdown
 121 {
 122         # close sockets, ...
 123         return 1;
 124 } # my_shutdown ()
 125
 126 # This function is called when plugin_log () has been used.
 127 sub my_log
 128 {
 129         my $level = shift;
 130         my $msg   = shift;
 131
 132         print "LOG: $level - $msg\n";
 133         return 1;
 134 } # my_log ()
 135
 136 # This function is called when plugin_dispatch_notification () has been used
 137 sub my_notify
 138 {
 139         my $notif = shift;
 140
 141         my ($sec, $min, $hour, $mday, $mon, $year) = localtime ($notif->{'time'});
 142
 143         printf "NOTIF (%04d-%02d-%02d %02d:%02d:%02d): %d - ",
 144                         $year + 1900, $mon + 1, $mday, $hour, $min, $sec,
 145                         $notif->{'severity'};
 146
 147         if (defined $notif->{'host'}) {
 148                 print "$notif->{'host'}: ";
 149         }
 150
 151         if (defined $notif->{'plugin'}) {
 152                 print "$notif->{'plugin'}: ";
 153         }
 154
 155         if (defined $notif->{'plugin_instance'}) {
 156                 print "$notif->{'plugin_instance'}: ";
 157         }
 158
 159         if (defined $notif->{'type'}) {
 160                 print "$notif->{'type'}: ";
 161         }
 162
 163         if (defined $notif->{'type_instance'}) {
 164                 print "$notif->{'type_instance'}: ";
 165         }
 166
 167         print "$notif->{'message'}\n";
 168         return 1;
 169 } # my_notify ()
 170