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.
11 # Notes:
12 # - each of the functions below (and the corresponding plugin_register call)
13 # is optional
15 package Collectd::Plugin::MyPlugin;
17 use strict;
18 use warnings;
20 use Collectd qw( :all );
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 ];
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');
49 # For each of the functions below see collectd-perl(5) for details about
50 # arguments and the like.
52 # This function is called once upon startup to initialize the plugin.
53 sub my_init
54 {
55 # open sockets, initialize data structures, ...
57 # A false return value indicates an error and causes the plugin to be
58 # disabled.
59 return 1;
60 } # my_init ()
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 = {};
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
79 # dispatch the values to collectd which passes them on to all registered
80 # write functions
81 plugin_dispatch_values ($vl);
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 ()
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;
95 if (scalar (@$ds) != scalar (@{$vl->{'values'}})) {
96 plugin_log (LOG_WARNING, "DS number does not match values length");
97 return;
98 }
100 for (my $i = 0; $i < scalar (@$ds); ++$i) {
101 # do the magic to output the data
102 print "$vl->{'host'}: $vl->{'plugin'}: ";
104 if (defined $vl->{'plugin_instance'}) {
105 print "$vl->{'plugin_instance'}: ";
106 }
108 print "$type: ";
110 if (defined $vl->{'type_instance'}) {
111 print "$vl->{'type_instance'}: ";
112 }
114 print "$vl->{'values'}->[$i]\n";
115 }
116 return 1;
117 } # my_write()
119 # This function is called before shutting down collectd.
120 sub my_shutdown
121 {
122 # close sockets, ...
123 return 1;
124 } # my_shutdown ()
126 # This function is called when plugin_log () has been used.
127 sub my_log
128 {
129 my $level = shift;
130 my $msg = shift;
132 print "LOG: $level - $msg\n";
133 return 1;
134 } # my_log ()
136 # This function is called when plugin_dispatch_notification () has been used
137 sub my_notify
138 {
139 my $notif = shift;
141 my ($sec, $min, $hour, $mday, $mon, $year) = localtime ($notif->{'time'});
143 printf "NOTIF (%04d-%02d-%02d %02d:%02d:%02d): %d - ",
144 $year + 1900, $mon + 1, $mday, $hour, $min, $sec,
145 $notif->{'severity'};
147 if (defined $notif->{'host'}) {
148 print "$notif->{'host'}: ";
149 }
151 if (defined $notif->{'plugin'}) {
152 print "$notif->{'plugin'}: ";
153 }
155 if (defined $notif->{'plugin_instance'}) {
156 print "$notif->{'plugin_instance'}: ";
157 }
159 if (defined $notif->{'type'}) {
160 print "$notif->{'type'}: ";
161 }
163 if (defined $notif->{'type_instance'}) {
164 print "$notif->{'type_instance'}: ";
165 }
167 print "$notif->{'message'}\n";
168 return 1;
169 } # my_notify ()