First steps
This short and incomplete article should guide the novice user through the process of getting collectd to work. Pointers to the manpages are provided where appropriate.
Since no OS is like the other, I'll talk about my Linux distribution, Debian, here. So the location of some files or commands to install packages may differ for your system.
There are currently two "major versions" of collectd: Version 4 and version 5. This is the first number of the full version number of a release. Version 4 is outdated and should not be used for new setups anymore, so make sure you get a version that starts with "5.*".
To get the executable binaries, you have the choice between two possibilities: Find a binary package or compile the source yourself. We strongly recommend to use a binary package unless you have very specific needs.
For many Linux distributions there are binary packages. Please make sure not to use the old version 4 (Debian Squeeze ships version 4.10.1, for example). Pointers to available binary packages can be found on the download page.
If there is no binary package for your distribution, or the one existing is outdated, you can compile the sources. For that you will need to install the usual C-compiler (most likely called "gcc"), linker, and so on. Debian users can simply install the build-essential package:
# apt-get install build-essential
The daemon itself doesn't depend on any libraries, but the plugins that collect the actual values will. What libraries are needed for which plugins is documented in the README file. Install the necessary libraries:
# apt-get install librrd2-dev libsensors-dev libsnmp-dev ...
After installing the build dependencies, you need to get and unpack the sources:
# cd /tmp/
# wget <nowiki>http://collectd.org/files/collectd-x.y.z.tar.bz2</nowiki>
# tar jxf collectd-x.y.z.tar.bz2
# cd collectd-x.y.z
Now configure the sources with the usual:
# ./configure
After the configure script is done it will display a summary of the libraries it has found (and not found) and which plugins are enabled. Per default, all plugins whose dependencies are met are enabled. If a plugin you want to use is missing, install the required development package and run configure again.
Last but not least: Compile and install the program. Per default it will be installed to /opt/collectd. If you prefer another directory, call the configure script with the --prefix option.
# make all install
# cd /opt/collectd/
The configuration will lie in <prefix>/etc/collectd.conf. It's manual page is collectd.conf(5). Open the file and pay particular attention to the LoadPlugin lines.
# vim etc/collectd.conf
- This section assumes Version-4.7 or later.
If you built the daemon from source, the configure script tries hard to provide you with a small, working default configuration. The configuration can usually be found in etc/collectd.conf.
For each plugin, there is a LoadPlugin line in the configuration. Almost all of those lines are commented out in order to keep the default configuration lean. However, the number of comment characters used is significant:
- Lines commented out with two hash characters ("##") belong to plugins that have not been built. Commenting these lines in will result in an error, because the plugin does not exist.
- The
LoadPluginlines commented out using one hash character ("#") belong to plugins that have been built. You can comment them in / out as you wish. - By default the following plugins are enabled: CPU, Interface, Load, and Memory.
By default exactly one write plugin is enabled. The first plugin available will be taken in this order: RRDtool, Network, CSV.
Likewise only one log plugin is enabled. If available, the SysLog plugin will be enabled, otherwise the LogFile plugin is used.
If you installed a binary package, the package vendor has hopefully enabled only a small number of standard plugins. Please see the binary package's documentation to find out which other plugins are included and can be enabled. There's a wiki page containing a table of all plugins.
The following is a list of the very basic plugins and a short description:
|
Name |
Type |
Description |
|---|---|---|
|
logging |
Writes log messages to a file or standard output |
|
|
logging |
Writes debug and status information to syslog. |
|
|
output |
Writes data to RRD files |
|
|
output |
Writes data to CSV files |
|
|
input |
Collects CPU usage |
|
|
input |
Collects memory usage |
|
|
input |
Collects traffic of network interfaces |
The Interval setting controls how often values are read. You should set this once and then never touch it again. If you do, you will have to delete all your RRD files or know some serious RRDtool magic!
To have the daemon resolve the local fully qualified host-name (FQDN) and use this as the name of the current instance, set the FQDNLookup option to true. The system's host-name must be set correctly for this to work. Using this method is recommended.
Some plugins take an additional configuration. Of interest here are the LogFile and RRDtool plugins. Before setting anything explicitly, please read the relevant part of the collectd.conf(5) manpage. There are no undocumented options. The RRDtool plugin is especially prone of mis-configuration, please read the manual page especially careful when configuring this plugin.
If you're done configuring, you need to (re-)start the daemon. If you installed a binary package there should be an init-script somewhere. Under Debian, the command would be:
# /etc/init.d/collectd restart
If your system (Fedora, ArchLinux, OpenSUSE, etc.) is using systemd for managing services:
# systemctl start collectd.service
and to enable the service:
# systemctl enable collectd.service
Alternatively you can start the daemon "by hand". This is done by executing:
# /opt/collectd/sbin/collectd
or (if you are using a binary package):
# /usr/sbin/collectd
Some plugins require root privileges to work properly. If you're missing graphs and/or see error messages that indicate insufficient permissions, restart collectd as root.
The daemon should now collect values using the "input" plugins you've loaded and write them to files using the "output" plugin(s). Any problems or interesting behavior is reported using the "log" plugin(s).
Congratulations, as far as collectd is concerned, you're all set! :)
First off: It is not collectd's focus to generate graphs! Other projects offer this. The focus is to collect the values and write it to files or send it to another host over a network. But since we have to visualize the data somehow, too, we have been nice enough to throw a script that's good enough for us into the contrib/ directory. This script, however, is not part of collectd and not supported by us. It just happens to work sometimes.
That being said, here's how it's installed: In the contrib/ directory (or the directory /usr/share/doc/collectd/examples/ if you installed the Debian package) you will find a directory named collection3. This directory holds all the necessary files for the graph generation, grouped again in subdirectories. Copy the entire directory somewhere, where your web server expects to find something.
# cp -r contrib/collection3 /var/www/
# cd /var/www/collection3/
In the subdirectory bin/ are the CGI scripts, which must be executed by the web-server. In the share/ subdirectory, there are supplementary files, such as style-sheets, which must not be executed. Since execution of files can't be turned off in directories referenced via ScriptAlias, using the standard cgi-bin directory provided by most distributions is probably problematic.
In some of the subdirectories, you will find files named .htaccess. They (try to) configure the web server, so that the appropriate files are executed, others are denied to visitors and so on. Please make sure to set the Apache option AllowOverride to an appropriate value or move the configuration to the main Apache configuration.
The script is written in Perl and requires a number of Perl modules to be installed. Many of them are shipped with the standard Perl distributions, but some you will need to install yourself. Here's a (hopefully complete) list:
- RRDs
- Config::General
- HTML::Entities (Debian package
libhtml-parser-perl) - Regexp::Common
# sudo apt-get install librrds-perl libconfig-general-perl libhtml-parser-perl libregexp-common-perl
If everything worked out alright, you can now browse your graphs at http://localhost/collection3/bin/index.cgi or wherever you put the script. If you get an error, check Apache's error log. Common errors include wrong permissions on the files in bin/ (they need to be executable) and etc/ (needs to be readable by the web server). For web server specific problems, please refer to this how-to on CGI scripts.
There are also a couple of further, third-party front-ends available with a different focus each. Have a look at the list of front-ends for an overview.
The following steps are optional and depend on your infrastructure and the kind of setup you are about to build.
- Browse through the list of available plugins.
- Connect multiple instances of collectd using the network plugin: Introduction to Networking.
- In large setups, you will run into IO-problems when using RRDtool - learn how to escape from the IO-hell.
- Use the power of "generic plugins" to get arbitrary data from various sources (e.g. SNMP, SQL, ASCII files): see the Generic Plugins category.
Good luck and have fun ;)