contrib/examples/myplugin.c

   1 /*
   2  * /usr/share/doc/collectd/examples/myplugin.c
   3  *
   4  * A plugin template for collectd.
   5  *
   6  * Written by Sebastian Harl <sh@tokkee.org>
   7  *
   8  * This is free software; you can redistribute it and/or modify it under
   9  * the terms of the GNU General Public License as published by the Free
  10  * Software Foundation; only version 2 of the License is applicable.
  11  */
  12
  13 /*
  14  * Notes:
  15  * - plugins are executed in parallel, thus, thread-safe
  16  *   functions need to be used
  17  * - each of the functions below (except module_register)
  18  *   is optional
  19  */
  20
  21 #include <stdio.h>
  22 #include <stdlib.h>
  23
  24 #include <string.h>
  25
  26 #ifndef __USE_ISOC99 /* required for NAN */
  27 # define DISABLE_ISOC99 1
  28 # define __USE_ISOC99 1
  29 #endif /* !defined(__USE_ISOC99) */
  30 #include <math.h>
  31 #if DISABLE_ISOC99
  32 # undef DISABLE_ISOC99
  33 # undef __USE_ISOC99
  34 #endif /* DISABLE_ISOC99 */
  35
  36 #include <collectd/collectd.h>
  37 #include <collectd/common.h>
  38 #include <collectd/plugin.h>
  39
  40 /*
  41  * data source definition:
  42  * - name of the data source
  43  * - type of the data source (DS_TYPE_GAUGE, DS_TYPE_COUNTER)
  44  * - minimum allowed value
  45  * - maximum allowed value
  46  */
  47 static data_source_t dsrc[1] =
  48 {
  49         { "my_ds", DS_TYPE_GAUGE, 0, NAN }
  50 };
  51
  52 /*
  53  * data set definition:
  54  * - name of the data set
  55  * - number of data sources
  56  * - list of data sources
  57  */
  58 static data_set_t ds =
  59 {
  60         "myplugin", STATIC_ARRAY_SIZE (dsrc), dsrc
  61 };
  62
  63 /*
  64  * This function is called once upon startup to initialize the plugin.
  65  */
  66 static int my_init (void)
  67 {
  68         /* open sockets, initialize data structures, ... */
  69
  70         /* A return value != 0 indicates an error and causes the plugin to be
  71            disabled. */
  72     return 0;
  73 } /* static int my_init (void) */
  74
  75 /*
  76  * This function is called in regular intervalls to collect the data.
  77  */
  78 static int my_read (void)
  79 {
  80         value_t values[1]; /* the size of this list should equal the number of
  81                                                   data sources */
  82         value_list_t vl = VALUE_LIST_INIT;
  83
  84         /* do the magic to read the data */
  85         values[0].gauge = random ();
  86
  87         vl.values     = values;
  88         vl.values_len = 1;
  89         vl.time       = time (NULL);
  90         strcpy (vl.host, hostname_g);
  91         strcpy (vl.plugin, "myplugin");
  92         /* optionally set vl.plugin_instance and vl.type_instance to reasonable
  93          * values (default: "") */
  94
  95         /* dispatch the values to collectd which passes them on to all registered
  96          * write functions - the first argument is used to lookup the data set
  97          * definition */
  98         plugin_dispatch_values ("myplugin", &vl);
  99
 100         /* A return value != 0 indicates an error and the plugin will be skipped
 101          * for an increasing amount of time. */
 102     return 0;
 103 } /* static int my_read (void) */
 104
 105 /*
 106  * This function is called after values have been dispatched to collectd.
 107  */
 108 static int my_write (const data_set_t *ds, const value_list_t *vl)
 109 {
 110         char name[1024] = "";
 111         int i = 0;
 112
 113         if (ds->ds_num != vl->values_len) {
 114                 plugin_log (LOG_WARNING, "DS number does not match values length");
 115                 return -1;
 116         }
 117
 118         /* get the default base filename for the output file - depending on the
 119          * provided values this will be something like
 120          * <host>/<plugin>[-<plugin_type>]/<instance>[-<instance_type>] */
 121         if (0 != format_name (name, 1024, vl->host, vl->plugin,
 122                         vl->plugin_instance, ds->type, vl->type_instance))
 123                 return -1;
 124
 125         for (i = 0; i < ds->ds_num; ++i) {
 126                 /* do the magic to output the data */
 127                 printf ("%s (%s) at %i: ", name,
 128                                 (ds->ds->type == DS_TYPE_GAUGE) ? "GAUGE" : "COUNTER",
 129                                 (int)vl->time);
 130
 131                 if (ds->ds->type == DS_TYPE_GAUGE)
 132                         printf ("%f\n", vl->values[i].gauge);
 133                 else
 134                         printf ("%lld\n", vl->values[i].counter);
 135         }
 136         return 0;
 137 } /* static int my_write (data_set_t *, value_list_t *) */
 138
 139 /*
 140  * This function is called when plugin_log () has been used.
 141  */
 142 static void my_log (int severity, const char *msg)
 143 {
 144         printf ("LOG: %i - %s\n", severity, msg);
 145         return;
 146 } /* static void my_log (int, const char *) */
 147
 148 /*
 149  * This function is called before shutting down collectd.
 150  */
 151 static int my_shutdown (void)
 152 {
 153         /* close sockets, free data structures, ... */
 154         return 0;
 155 } /* static int my_shutdown (void) */
 156
 157 /*
 158  * This function is called after loading the plugin to register it with
 159  * collectd.
 160  */
 161 void module_register (void)
 162 {
 163         plugin_register_log ("myplugin", my_log);
 164         plugin_register_data_set (&ds);
 165         plugin_register_read ("myplugin", my_read);
 166         plugin_register_init ("myplugin", my_init);
 167         plugin_register_write ("myplugin", my_write);
 168         plugin_register_shutdown ("myplugin", my_shutdown);
 169     return;
 170 } /* void module_register (void) */
 171