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 # (take a look at the types.db file for a large list of predefined data-sets)
  25 my $dataset =
  26 [
  27         {
  28                 name => 'my_ds',
  29                 type => DS_TYPE_GAUGE,
  30                 min  => 0,
  31                 max  => 65535,
  32         },
  33 ];
  34
  35 # This code is executed after loading the plugin to register it with collectd.
  36 plugin_register (TYPE_LOG, 'myplugin', 'my_log');
  37 plugin_register (TYPE_DATASET, 'myplugin', $dataset);
  38 plugin_register (TYPE_INIT, 'myplugin', 'my_init');
  39 plugin_register (TYPE_READ, 'myplugin', 'my_read');
  40 plugin_register (TYPE_WRITE, 'myplugin', 'my_write');
  41 plugin_register (TYPE_SHUTDOWN, 'myplugin', 'my_shutdown');
  42
  43 # For each of the functions below see collectd-perl(5) for details about
  44 # arguments and the like.
  45
  46 # This function is called once upon startup to initialize the plugin.
  47 sub my_init
  48 {
  49         # open sockets, initialize data structures, ...
  50
  51         # A false return value indicates an error and causes the plugin to be
  52         # disabled.
  53         return 1;
  54 } # my_init ()
  55
  56 # This function is called in regular intervals to collectd the data.
  57 sub my_read
  58 {
  59         # value list to dispatch to collectd:
  60         # see section "DATA TYPES" in collectd-perl(5) for details
  61         my $vl = {};
  62
  63         # do the magic to read the data:
  64         # the number of values has to match the number of data sources defined in
  65         # the registered data set
  66         $vl->{'values'} = [ rand(65535) ];
  67         $vl->{'plugin'} = 'myplugin';
  68         # any other elements are optional
  69
  70         # dispatch the values to collectd which passes them on to all registered
  71         # write functions - the first argument is used to lookup the data set
  72         # definition
  73         plugin_dispatch_values ('myplugin', $vl);
  74
  75         # A false return value indicates an error and the plugin will be skipped
  76         # for an increasing amount of time.
  77         return 1;
  78 } # my_read ()
  79
  80 # This function is called after values have been dispatched to collectd.
  81 sub my_write
  82 {
  83         my $type = shift;
  84         my $ds   = shift;
  85         my $vl   = shift;
  86
  87         if (scalar (@$ds) != scalar (@{$vl->{'values'}})) {
  88                 plugin_log (LOG_WARNING,
  89                         "DS number does not match values length");
  90                 return;
  91         }
  92
  93         for (my $i = 0; $i < scalar (@$ds); ++$i) {
  94                 # do the magic to output the data
  95                 print "$vl->{'host'}: $vl->{'plugin'}: ";
  96
  97                 if (defined $vl->{'plugin_instance'}) {
  98                         print "$vl->{'plugin_instance'}: ";
  99                 }
 100
 101                 print "$type: ";
 102
 103                 if (defined $vl->{'type_instance'}) {
 104                         print "$vl->{'type_instance'}: ";
 105                 }
 106
 107                 print "$vl->{'values'}->[$i]\n";
 108         }
 109         return 1;
 110 } # my_write()
 111
 112 # This function is called before shutting down collectd.
 113 sub my_shutdown
 114 {
 115         # close sockets, ...
 116         return 1;
 117 } # my_shutdown ()
 118
 119 # This function is called when plugin_log () has been used.
 120 sub my_log
 121 {
 122         my $level = shift;
 123         my $msg   = shift;
 124
 125         print "LOG: $level - $msg\n";
 126         return 1;
 127 } # my_log ()
 128