README

   1  collectd - System information collection daemon
   2 =================================================
   3 http://collectd.org/
   4
   5 About
   6 -----
   7
   8   collectd is a small daemon which collects statistics about a computer's
   9   usage and writes then into RRD files.
  10
  11
  12 Features
  13 --------
  14
  15   * collectd is able to collect the following data:
  16
  17     - apache
  18       Apache server utilization: Number of bytes transfered, number of
  19       requests handled and detailed scoreboard statistics
  20
  21     - apcups
  22       APC UPS Daemon: UPS charge, load, input/output/battery voltage, etc.
  23
  24     - apple_sensors
  25       Sensors in Macs running Mac OS X / Darwin: Temperature, fanspeed and
  26       voltage sensors.
  27
  28     - battery
  29       Batterycharge, -current and volatage of ACPI and PMU based laptop
  30       batteries.
  31
  32     - cpu
  33       CPU utilization: Time spent in the system, user, nice, idle, and related
  34       states.
  35
  36     - cpufreq
  37       CPU frequency (For laptops with speed step or a similar technology)
  38
  39     - df
  40       Mountpoint usage (Basically the values `df(1)' delivers)
  41
  42     - disk
  43       Disk utilization: Sectors read/written, number of read/write actions,
  44       average time an IO-operation took to complete.
  45
  46     - dns
  47       DNS traffic: Query types, response codes, opcodes and traffic/octets
  48       transfered.
  49
  50     - email
  51       Email statistics: Count, traffic, spam scores and checks.
  52       See collectd-email(5).
  53
  54     - entropy
  55       Amount of entropy available to the system.
  56
  57     - exec
  58       Values gathered by a custom program or script.
  59       See collectd-exec(5).
  60
  61     - hddtemp
  62       Harddisk temperatures using hddtempd.
  63
  64     - interface
  65       Interface traffic: Number of octets, packets and errors for each
  66       interface.
  67
  68     - iptables
  69       Iptables' counters: Number of bytes that were matched by a certain
  70       iptables rule.
  71
  72     - irq
  73       IRQ counters: Frequency in which certain interrupts occur.
  74
  75     - load
  76       System load average over the last 1, 5 and 15 minutes.
  77
  78     - mbmon
  79       Motherboard sensors: temperature, fanspeed and voltage information,
  80       using mbmon(1).
  81
  82     - memory
  83       Memory utilization: Memory occupied by running processes, page cache,
  84       buffer cache and free.
  85
  86     - multimeter
  87       Information provided by serial multimeters, such as the `Metex
  88       M-4650CR'.
  89
  90     - mysql
  91       MySQL server statistics: Commands issued, handlers triggered, thread
  92       usage, query cache utilization and traffic/octets sent and received.
  93
  94     - network
  95       Receive values that were collected by other hosts. Large setups will
  96       want to collect the data on one dedicated machine, and this is the
  97       plugin of choice for that.
  98
  99     - nfs
 100       NFS Procedures: Which NFS command were called how often. Only NFSv2 and
 101       NFSv3 right now.
 102
 103     - ntp
 104       NTP daemon statistics: Local clock drift, offset to peers, etc.
 105
 106     - nut
 107       Network UPS tools: UPS current, voltage, power, charge, utilisation,
 108       temperature, etc. See upsd(8).
 109
 110     - perl
 111       The perl plugin implements a Perl-interpreter into collectd. You can
 112       write your own plugins in Perl and return arbitary values using this
 113       API. See collectd-perl(5).
 114
 115     - ping
 116       Network latency: Time to reach the default gateway or another given
 117       host.
 118
 119     - processes
 120       Process counts: Number of running, sleeping, zombie, ... processes.
 121
 122     - sensors
 123       System sensors, accessed using lm_sensors: Voltages, temperatures and
 124       fan rotation speeds.
 125
 126     - serial
 127       RX and TX of serial interfaces. Linux only; needs root privileges.
 128
 129     - swap
 130       Pages swapped out onto harddisk or whatever is called `swap' by the OS..
 131
 132     - tape
 133       Bytes and operations read and written on tape devices. Solaris only.
 134
 135     - users
 136       Users currently logged in.
 137
 138     - vserver
 139       System ressources used by Linux VServers.
 140       See <http://linux-vserver.org/>.
 141
 142     - wireless
 143       Link quality of wireless cards. Linux only.
 144
 145   * Output can be written or send to various destinations by the following
 146     plugins:
 147
 148     - csv
 149       Write to comma seperated values (CSV) files. This needs lots of
 150       diskspace but is extremely portable and can be analysed with almost
 151       every program that can analyse anything. Even Microsoft's Excel..
 152
 153     - network
 154       Send the data to a remote host to save the data somehow. This is useful
 155       for large setups where the data should be saved by a dedicated machine.
 156
 157     - perl
 158       Of course the values are propagated to plugins written in Perl, too, so
 159       you can easily do weird stuff with the plugins we didn't dare think of
 160       ;) See collectd-perl(5).
 161
 162     - rrdtool
 163       Output to round-robin-database (RRD) files using librrd. See rrdtool(1).
 164       This is likely the most popular destination for such values. Since
 165       updates to RRD-files are somewhat expensive this plugin can cache
 166       updates to the files and write a bunch of updates at once, which lessens
 167       system load a lot.
 168
 169     - unixsock
 170       One can query the values from the unixsock plugin whenever they're
 171       needed. Please read collectd-unixsock(5) for a description on how that's
 172       done.
 173
 174   * Logging is, as everything in collectd, provided by plugins. The following
 175     plugins keep up informed about what's going on:
 176
 177     - logfile
 178       Writes logmessages to a file or STDOUT/STDERR.
 179
 180     - syslog
 181       Logs to the standard UNIX logging mechanismn, syslog.
 182
 183   * Performance: Since collectd is running as a daemon it doesn't spend much
 184     time starting up again and again. With the exception of the exec plugin no
 185     processes are forked. Caching in output plugins, such as the rrdtool and
 186     network plugins, makes sure your resources are used efficiently. Also,
 187     since collectd is programmed multithreaded it benefits from hyperthreading
 188     and multicore processors and makes sure that the daemon isn't idle if only
 189     one plugins waits for an IO-operation to complete.
 190
 191   * Once set up, hardly any maintenence is neccessary. Setup is kept as easy
 192     as possible and the default values should be okay for most users.
 193
 194
 195 Operation
 196 ---------
 197
 198   * collectd's configuration file can be found at `sysconfdir'/collectd.conf.
 199     Run `collectd -h' for a list of builtin defaults. See `collectd.conf(5)'
 200     for a list of options and a syntax description.
 201
 202   * When the `csv' or `rrdtool' plugins are loaded they'll write the values to
 203     files. The usual place for these files is beneath `/var/lib/collectd'.
 204
 205   * When using some of the plugins, collectd needs to run as user root, since only
 206     root can do certain things, such as craft ICMP packages needed to ping
 207     other hosts. collectd should NOT be installed setuid root since it can be
 208     used to overwrite valuable files!
 209
 210   * Sample scripts to generate graphs reside in `contrib/' in the source
 211     package or somewhere near `/usr/share/doc/collectd' in most distributions.
 212     Please be aware that those script are meant as a starting point for your
 213     own experiments.. Some of them require the `RRDs' Perl module.
 214     (`librrds-perl' on Debian) If you have written a more sophisticated
 215     solution please share it with us.
 216
 217   * The RRAs of the automatically created RRD files depend on the `step'
 218     and `heartbeat' settings given. If change these settings you may need to
 219     re-create the files, losing all data. Please be aware of that when changing
 220     the values and read the rrdtool(1) manpage thoroughly.
 221
 222
 223 Prerequisites
 224 -------------
 225
 226   To compile collectd from source you will need:
 227
 228   * Usual suspects: C compiler, linker, preprocessor, make, ...
 229
 230   * A POSIX-threads (pthread) implementation.
 231     Since gathering some statistics is slow (network connections, slow devices,
 232     etc) the collectd is parellelized. The POSIX threads interface is being
 233     used and should be found in various implementations for hopefully all
 234     platforms.
 235
 236   * libcurl (optional)
 237     If you want to use the `apache' plugin
 238
 239   * libiptc (optional)
 240     For querying iptables counters.
 241
 242   * libmysqlclient (optional)
 243
 244   * liboping (optional, if not found a version shipped with this distribution
 245     can be used)
 246     Used by the `ping' plugin to send and receive ICMP packets.
 247
 248   * libpcap (optional)
 249     Used to capture packets by the `dns' plugin.
 250
 251   * librrd (optional; headers and library; rrdtool 1.0 and 1.2 both work fine)
 252     If built without `librrd' the resulting binary will be `client only', i.e.
 253     will send it's values via multicast and not create any RRD files itself.
 254     Alternatively you can chose to write CSV-files (Comma Seperated Values)
 255     instead.
 256
 257   * libsensors (optional)
 258     To read from `lm_sensors'.
 259
 260   * libstatgrab may be used to collect statistics on systems other than Linux
 261     and/or Solaris. Note that CPU- and disk-statistics, while being provided
 262     by this library, are not supported in collectd right now..
 263     <http://www.i-scream.org/libstatgrab/>
 264
 265   * libupsclient/nut (optional)
 266     For the `nut' plugin which queries nut's `upsd'.
 267
 268   * librt, libsocket, libkstat, libdevinfo
 269     Various standard Solaris libraries which provide system functions.
 270
 271   * CoreFoundation.framework and IOKit.framework
 272     For compiling on Darwin in general and the `apple_sensors' plugin in
 273     particular.
 274
 275 Author
 276 ------
 277
 278   Florian octo Forster <octo at verplant.org>,
 279   Sebastian tokkee Hard <sh at tokkee.org>,
 280   and many contributors (see `AUTHORS').
 281