debian/README.Debian

   1 collectd on Debian
   2 ==================
   3
   4 General notes:
   5 --------------
   6
   7 - This package is split up into several packages to prevent you from having to
   8   install dependencies that you don't actually need. Any plugin that has
   9   dependencies other than libc gets its own package.
  10
  11 Configuring collectd:
  12 ---------------------
  13
  14 - See collectd.conf(5) for details about configuring collectd.
  15
  16 Access the collected data:
  17 --------------------------
  18
  19 collectd is able to write data to CSV (comma separated list) and RRD (round
  20 robin database - see http://oss.oetiker.ch/rrdtool/) files. However it does
  21 not create graphs from these files. This package contains two sample scripts
  22 in /usr/share/doc/collectd/examples/ which can be used for this purpose. They
  23 are meant to be a starting point for your own experiments - more sophisticated
  24 solutions are welcome.
  25
  26 - collectd2html.pl: This script by Vincent Stehlé will search for RRD files in
  27   "/var/lib/collectd/" and generate a static HTML file and a directory
  28   containing several PNG files which are graphs of the RRD files found.
  29
  30 - collection.cgi: Sample CGI script that creates graphs on the fly. The Perl
  31   modules "RRDs" (package librrds-perl), "URI:Escape" (package liburi-perl),
  32   "HTML::Entities" (package libhtml-parser-perl) and a CGI capable web server
  33   (e.g. apache2 or boa) are required for this script to run. Simply install
  34   the (gunzip'ed) script to a place where the webserver will treat it as a CGI
  35   script (/usr/lib/cgi-bin/ by default) and visit that page in a browser
  36   (http://localhost/cgi-bin/collection.cgi by default). Please refer to your
  37   webserver's documentation for more details.
  38
  39   Starting with version 4, collection.cgi requires a small config file, which
  40   is installed to /etc/collectd/collection.conf. You should not need to change
  41   anything there.
  42
  43 Building your own plugins:
  44 --------------------------
  45
  46 - Originally, plugins for collectd had to be written in C and linked as shared
  47   objects. Starting with version 4.0.0, it is also possible to use plugins
  48   written in the scripting language Perl or implemented as separate processes.
  49   See collectd-perl(5) and collectd-exec(5) for details.
  50
  51 - If you want to contribute plugins to the official distribution you should
  52   read http://collectd.org/dev-info.shtml.
  53
  54 - If you want to build C plugins for your personal use only simply install the
  55   collectd-dev package and use /usr/share/doc/collectd-dev/examples/myplugin.c
  56   as a starting point (Note: This is already a working example, though it does
  57   not collect any useful data).
  58
  59   The resulting file can be compiled as follows:
  60
  61     gcc -shared -fPIC -o myplugin.so myplugin.c
  62
  63   Copy myplugin.so to /usr/lib/collectd and add the following line to your
  64   collectd config file:
  65
  66     LoadPlugin myplugin
  67
  68   Restart collectd and you're done.
  69
  70 - The collectd-dev package also provides an example Perl plugin that can be
  71   used as a starting point for your own development. It can be found in
  72   /usr/share/doc/collectd-dev/examples/MyPlugin.pm (Note: This is already a
  73   working example, though it does not collect any useful data).
  74
  75   To enable the plugin, copy it to a place where Perl can find it (i.e. a
  76   subdirectory named "Collectd/Plugin" of a directory listed in @INC) and add
  77   the following line to the perl plugin section in your config file:
  78
  79     LoadPlugin "Collectd::Plugin::MyPlugin"
  80
  81   or
  82
  83     BaseName "Collectd::Plugin"
  84     LoadPlugin MyPlugin
  85
  86   Restart collectd and you're done.
  87
  88 Additional helper scripts:
  89 --------------------------
  90
  91 - The directory /usr/share/doc/collectd/examples/PerlLib/ contains Perl
  92   modules which can be used in conjunction with collectd. See the perldoc
  93   documentation of the .pm-files to find out what they're good for.
  94
  95 - add_rra.sh: Before version 3.9.0 collectd used to create a different set of
  96   RRAs. The most detailed of these old RRAs had a one minute resolution. This
  97   script can be used to add three more RRAs: minimum, maximum and average with
  98   a ten second resolution and 2200 rows (~6 hours). This will make hourly
  99   statistics much more interesting. Please note that no sanity-checking
 100   whatsoever is performed. You can seriously screw up your RRD files if you
 101   don't know what you're doing.
 102