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 system information periodically
   9   and provides mechanisms to store and monitor the values in a variety of
  10   ways.
  11
  12
  13 Features
  14 --------
  15
  16   * collectd is able to collect the following data:
  17
  18     - apache
  19       Apache server utilization: Number of bytes transfered, number of
  20       requests handled and detailed scoreboard statistics
  21
  22     - apcups
  23       APC UPS Daemon: UPS charge, load, input/output/battery voltage, etc.
  24
  25     - apple_sensors
  26       Sensors in Macs running Mac OS X / Darwin: Temperature, fanspeed and
  27       voltage sensors.
  28
  29     - ascent
  30       Statistics about Ascent, a free server for the game `World of Warcraft'.
  31
  32     - battery
  33       Batterycharge, -current and voltage of ACPI and PMU based laptop
  34       batteries.
  35
  36     - bind
  37       Name server and resolver statistics from the `statistics-channel'
  38       interface of BIND 9.5, 9,6 and later.
  39
  40     - cpu
  41       CPU utilization: Time spent in the system, user, nice, idle, and related
  42       states.
  43
  44     - cpufreq
  45       CPU frequency (For laptops with speed step or a similar technology)
  46
  47     - dbi
  48       Executes SQL statements on various databases and interprets the returned
  49       data.
  50
  51     - df
  52       Mountpoint usage (Basically the values `df(1)' delivers)
  53
  54     - disk
  55       Disk utilization: Sectors read/written, number of read/write actions,
  56       average time an IO-operation took to complete.
  57
  58     - dns
  59       DNS traffic: Query types, response codes, opcodes and traffic/octets
  60       transfered.
  61
  62     - email
  63       Email statistics: Count, traffic, spam scores and checks.
  64       See collectd-email(5).
  65
  66     - entropy
  67       Amount of entropy available to the system.
  68
  69     - exec
  70       Values gathered by a custom program or script.
  71       See collectd-exec(5).
  72
  73     - filecount
  74       Count the number of files in directories.
  75
  76     - hddtemp
  77       Harddisk temperatures using hddtempd.
  78
  79     - interface
  80       Interface traffic: Number of octets, packets and errors for each
  81       interface.
  82
  83     - iptables
  84       Iptables' counters: Number of bytes that were matched by a certain
  85       iptables rule.
  86
  87     - ipmi
  88       IPMI (Intelligent Platform Management Interface) sensors information.
  89
  90     - ipvs
  91       IPVS connection statistics (number of connections, octets and packets
  92       for each service and destination).
  93       See http://www.linuxvirtualserver.org/software/index.html.
  94
  95     - irq
  96       IRQ counters: Frequency in which certain interrupts occur.
  97
  98     - load
  99       System load average over the last 1, 5 and 15 minutes.
 100
 101     - libvirt
 102       CPU, disk and network I/O statistics from virtual machines.
 103
 104     - mbmon
 105       Motherboard sensors: temperature, fanspeed and voltage information,
 106       using mbmon(1).
 107
 108     - memcached
 109       Statistics of the memcached distributed caching system.
 110       <http://www.danga.com/memcached/>
 111
 112     - memory
 113       Memory utilization: Memory occupied by running processes, page cache,
 114       buffer cache and free.
 115
 116     - multimeter
 117       Information provided by serial multimeters, such as the `Metex
 118       M-4650CR'.
 119
 120     - mysql
 121       MySQL server statistics: Commands issued, handlers triggered, thread
 122       usage, query cache utilization and traffic/octets sent and received.
 123
 124     - netlink
 125       Very detailed Linux network interface and routing statistics. You can get
 126       (detailed) information on interfaces, qdiscs, classes, and, if you can
 127       make use of it, filters.
 128
 129     - network
 130       Receive values that were collected by other hosts. Large setups will
 131       want to collect the data on one dedicated machine, and this is the
 132       plugin of choice for that.
 133
 134     - nfs
 135       NFS Procedures: Which NFS command were called how often. Only NFSv2 and
 136       NFSv3 right now.
 137
 138     - nginx
 139       Collects statistics from `nginx' (speak: engine X), a HTTP and mail
 140       server/proxy.
 141
 142     - ntpd
 143       NTP daemon statistics: Local clock drift, offset to peers, etc.
 144
 145     - nut
 146       Network UPS tools: UPS current, voltage, power, charge, utilisation,
 147       temperature, etc. See upsd(8).
 148
 149     - onewire (EXPERIMENTAL!)
 150       Read onewire sensors using the owcapu library of the owfs project.
 151       Please read in collectd.conf(5) why this plugin is experimental.
 152
 153     - openvpn
 154       RX and TX of each client in openvpn-status.log (status-version 2).
 155       <http://openvpn.net/index.php/documentation/howto.html>
 156
 157     - perl
 158       The perl plugin implements a Perl-interpreter into collectd. You can
 159       write your own plugins in Perl and return arbitrary values using this
 160       API. See collectd-perl(5).
 161
 162     - ping
 163       Network latency: Time to reach the default gateway or another given
 164       host.
 165
 166     - postgresql
 167       PostgreSQL database statistics: active server connections, transaction
 168       numbers, block IO, table row manipulations.
 169
 170     - powerdns
 171       PowerDNS name server statistics.
 172
 173     - processes
 174       Process counts: Number of running, sleeping, zombie, ... processes.
 175
 176     - rrdcached
 177       RRDtool caching daemon (RRDcacheD) statistics.
 178
 179     - sensors
 180       System sensors, accessed using lm_sensors: Voltages, temperatures and
 181       fan rotation speeds.
 182
 183     - serial
 184       RX and TX of serial interfaces. Linux only; needs root privileges.
 185
 186     - snmp
 187       Read values from SNMP (Simple Network Management Protocol) enabled
 188       network devices such as switches, routers, thermometers, rack monitoring
 189       servers, etc. See collectd-snmp(5).
 190
 191     - swap
 192       Pages swapped out onto harddisk or whatever is called `swap' by the OS..
 193
 194     - tail
 195       Follows (tails) logfiles, parses them by lines and submits matched
 196       values.
 197
 198     - tape
 199       Bytes and operations read and written on tape devices. Solaris only.
 200
 201     - tcpconns
 202       Number of TCP connections to specific local and remote ports.
 203
 204     - teamspeak2
 205       TeamSpeak2 server statistics.
 206
 207     - thermal
 208       Linux ACPI thermal zone information.
 209
 210     - users
 211       Users currently logged in.
 212
 213     - vmem
 214       Virtual memory statistics, e. g. the number of page-ins/-outs or the
 215       number of pagefaults.
 216
 217     - vserver
 218       System resources used by Linux VServers.
 219       See <http://linux-vserver.org/>.
 220
 221     - wireless
 222       Link quality of wireless cards. Linux only.
 223
 224     - xmms
 225       Bitrate and frequency of music played with XMMS.
 226
 227   * Output can be written or send to various destinations by the following
 228     plugins:
 229
 230     - csv
 231       Write to comma separated values (CSV) files. This needs lots of
 232       diskspace but is extremely portable and can be analysed with almost
 233       every program that can analyse anything. Even Microsoft's Excel..
 234
 235     - network
 236       Send the data to a remote host to save the data somehow. This is useful
 237       for large setups where the data should be saved by a dedicated machine.
 238
 239     - perl
 240       Of course the values are propagated to plugins written in Perl, too, so
 241       you can easily do weird stuff with the plugins we didn't dare think of
 242       ;) See collectd-perl(5).
 243
 244     - rrdcached
 245       Output to round-robin-database (RRD) files using the RRDtool caching
 246       daemon (RRDcacheD) - see rrdcached(1). That daemon provides a general
 247       implementation of the caching done by the `rrdtool' plugin.
 248
 249     - rrdtool
 250       Output to round-robin-database (RRD) files using librrd. See rrdtool(1).
 251       This is likely the most popular destination for such values. Since
 252       updates to RRD-files are somewhat expensive this plugin can cache
 253       updates to the files and write a bunch of updates at once, which lessens
 254       system load a lot.
 255
 256     - unixsock
 257       One can query the values from the unixsock plugin whenever they're
 258       needed. Please read collectd-unixsock(5) for a description on how that's
 259       done.
 260
 261   * Filtering and rewriting values dispatched to collectd can be done by the
 262     following plugins:
 263
 264     - filter_pcre
 265       Filter and rewrite value lists based on Perl-compatible regular
 266       expressions.
 267
 268   * Logging is, as everything in collectd, provided by plugins. The following
 269     plugins keep up informed about what's going on:
 270
 271     - logfile
 272       Writes logmessages to a file or STDOUT/STDERR.
 273
 274     - perl
 275       Log messages are propagated to plugins written in Perl as well.
 276       See collectd-perl(5).
 277
 278     - syslog
 279       Logs to the standard UNIX logging mechanism, syslog.
 280
 281   * Notifications can be handled by the following plugins:
 282
 283     - notify_desktop
 284       Send a desktop notification to a notification daemon, as defined in
 285       the Desktop Notification Specification. To actually display the
 286       notifications, notification-daemon is required.
 287       See http://www.galago-project.org/specs/notification/.
 288
 289     - notify_email
 290       Send an E-mail with the notification message to the configured
 291       recipients.
 292
 293     - exec
 294       Execute a program or script to handle the notification.
 295       See collectd-exec(5).
 296
 297     - logfile
 298       Writes the notification message to a file or STDOUT/STDERR.
 299
 300     - network
 301       Send the notification to a remote host to handle it somehow.
 302
 303     - perl
 304       Notifications are propagated to plugins written in Perl as well.
 305       See collectd-perl(5).
 306
 307   * Miscellaneous plugins:
 308
 309     - uuid
 310       Sets the hostname to an unique identifier. This is meant for setups
 311       where each client may migrate to another physical host, possibly going
 312       through one or more name changes in the process.
 313
 314   * Performance: Since collectd is running as a daemon it doesn't spend much
 315     time starting up again and again. With the exception of the exec plugin no
 316     processes are forked. Caching in output plugins, such as the rrdtool and
 317     network plugins, makes sure your resources are used efficiently. Also,
 318     since collectd is programmed multithreaded it benefits from hyperthreading
 319     and multicore processors and makes sure that the daemon isn't idle if only
 320     one plugins waits for an IO-operation to complete.
 321
 322   * Once set up, hardly any maintenance is necessary. Setup is kept as easy
 323     as possible and the default values should be okay for most users.
 324
 325
 326 Operation
 327 ---------
 328
 329   * collectd's configuration file can be found at `sysconfdir'/collectd.conf.
 330     Run `collectd -h' for a list of builtin defaults. See `collectd.conf(5)'
 331     for a list of options and a syntax description.
 332
 333   * When the `csv' or `rrdtool' plugins are loaded they'll write the values to
 334     files. The usual place for these files is beneath `/var/lib/collectd'.
 335
 336   * When using some of the plugins, collectd needs to run as user root, since
 337     only root can do certain things, such as craft ICMP packages needed to ping
 338     other hosts. collectd should NOT be installed setuid root since it can be
 339     used to overwrite valuable files!
 340
 341   * Sample scripts to generate graphs reside in `contrib/' in the source
 342     package or somewhere near `/usr/share/doc/collectd' in most distributions.
 343     Please be aware that those script are meant as a starting point for your
 344     own experiments.. Some of them require the `RRDs' Perl module.
 345     (`librrds-perl' on Debian) If you have written a more sophisticated
 346     solution please share it with us.
 347
 348   * The RRAs of the automatically created RRD files depend on the `step'
 349     and `heartbeat' settings given. If change these settings you may need to
 350     re-create the files, losing all data. Please be aware of that when changing
 351     the values and read the rrdtool(1) manpage thoroughly.
 352
 353
 354 collectd and chkrootkit
 355 -----------------------
 356
 357   If you are using the `dns' plugin chkrootkit(1) will report collectd as a
 358   packet sniffer ("<iface>: PACKET SNIFFER(/usr/sbin/collectd[<pid>])"). The
 359   plugin captures all UDP packets on port 53 to analyze the DNS traffic. In
 360   this case, collectd is a legitimate sniffer and the report should be
 361   considered to be a false positive. However, you might want to check that
 362   this really is collectd and not some other, illegitimate sniffer.
 363
 364
 365 Prerequisites
 366 -------------
 367
 368   To compile collectd from source you will need:
 369
 370   * Usual suspects: C compiler, linker, preprocessor, make, ...
 371
 372   * A POSIX-threads (pthread) implementation.
 373     Since gathering some statistics is slow (network connections, slow devices,
 374     etc) the collectd is parallelized. The POSIX threads interface is being
 375     used and should be found in various implementations for hopefully all
 376     platforms.
 377
 378   * CoreFoundation.framework and IOKit.framework (optional)
 379     For compiling on Darwin in general and the `apple_sensors' plugin in
 380     particular.
 381     <http://developer.apple.com/corefoundation/>
 382
 383   * libcurl (optional)
 384     If you want to use the `apache', `ascent', or `nginx' plugin.
 385     <http://curl.haxx.se/>
 386
 387   * libdbi (optional)
 388     Used by the `dbi' plugin to connect to various databases.
 389     <http://libdbi.sourceforge.net/>
 390
 391   * libesmtp (optional)
 392     For the `notify_email' plugin.
 393     <http://www.stafford.uklinux.net/libesmtp/>
 394
 395   * libhal (optional)
 396     If present, the uuid plugin will check for UUID from HAL.
 397     <http://hal.freedesktop.org/>
 398
 399   * libiptc (optional, if not found a version shipped with this distribution
 400     can be used if the Linux kernel headers are available)
 401     For querying iptables counters.
 402     <http://netfilter.org/>
 403
 404   * libmysqlclient (optional)
 405     Unsurprisingly used by the `mysql' plugin.
 406     <http://dev.mysql.com/>
 407
 408   * libnetlink (optional)
 409     Used, obviously, for the `netlink' plugin.
 410     <http://www.linuxfoundation.org/en/Net:Iproute2>
 411
 412   * libnetsnmp (optional)
 413     For the `snmp' plugin.
 414     <http://www.net-snmp.org/>
 415
 416   * libnotify (optional)
 417     For the `notify_desktop' plugin.
 418     <http://www.galago-project.org/>
 419
 420   * liboping (optional, if not found a version shipped with this distribution
 421     can be used)
 422     Used by the `ping' plugin to send and receive ICMP packets.
 423     <http://verplant.org/liboping/>
 424
 425   * libowcapi (optional)
 426     Used by the `onewire' plugin to read values from onewire sensors (or the
 427     owserver(1) daemon).
 428     <http://www.owfs.org/>
 429
 430   * libpcap (optional)
 431     Used to capture packets by the `dns' plugin.
 432     <http://www.tcpdump.org/>
 433
 434   * libpcre (optional)
 435     Used by the `filter_pcre' plugin.
 436     <http://www.pcre.org/>
 437
 438   * libperl (optional)
 439     Obviously used by the `perl' plugin. The library has to be compiled with
 440     ithread support (introduced in Perl 5.6.0).
 441     <http://www.perl.org/>
 442
 443   * libpq (optional)
 444     The PostgreSQL C client library used by the `postgresql' plugin.
 445     <http://www.postgresql.org/>
 446
 447   * librrd (optional)
 448     Used by the `rrdtool' and `rrdcached' plugins. The latter requires RRDtool
 449     client support which was added after version 1.3 of RRDtool. Versions 1.0,
 450     1.2 and 1.3 are known to work with the `rrdtool' plugin.
 451     <http://oss.oetiker.ch/rrdtool/>
 452
 453   * librt, libsocket, libkstat, libdevinfo (optional)
 454     Various standard Solaris libraries which provide system functions.
 455     <http://developers.sun.com/solaris/>
 456
 457   * libsensors (optional)
 458     To read from `lm_sensors', see the `sensors' plugin.
 459     <http://www.lm-sensors.org/>
 460
 461   * libstatgrab (optional)
 462     Used by various plugins to collect statistics on systems other than Linux
 463     and/or Solaris.
 464     <http://www.i-scream.org/libstatgrab/>
 465
 466   * libupsclient/nut (optional)
 467     For the `nut' plugin which queries nut's `upsd'.
 468     <http://networkupstools.org/>
 469
 470   * libvirt (optional)
 471     Collect statistics from virtual machines.
 472     <http://libvirt.org/>
 473
 474   * libxml2 (optional)
 475     Parse XML data. This is needed for the `ascent' and `libvirt' plugins.
 476     <http://xmlsoft.org/>
 477
 478   * libxmms (optional)
 479     <http://www.xmms.org/>
 480
 481
 482 Configuring / Compiling / Installing
 483 ------------------------------------
 484
 485   To configure, build and install collectd with the default settings, run
 486   `./configure && make && make install'.  For detailed, generic instructions
 487   see INSTALL. For a complete list of configure options and their description,
 488   run `./configure --help'.
 489
 490   By default, the configure script will check for all build dependencies and
 491   disable all plugins whose requirements cannot be fulfilled (any other plugin
 492   will be enabled). To enable a plugin, install missing dependencies (see
 493   section `Prerequisites' above) and rerun `configure'. If you specify the
 494   `--enable-<plugin>' configure option, the script will fail if the depen-
 495   dencies for the specified plugin are not met. If you specify the
 496   `--disable-<plugin>' configure option, the plugin will not be built. Both
 497   options are meant for package maintainers and should not be used in everyday
 498   situations.
 499
 500   By default, collectd will be installed into `/opt/collectd'. You can adjust
 501   this setting by specifying the `--prefix' configure option - see INSTALL for
 502   details. If you pass DESTDIR=<path> to `make install', <path> will be
 503   prefixed to all installation directories. This might be useful when creating
 504   packages for collectd.
 505
 506
 507 Crosscompiling
 508 --------------
 509
 510   To compile correctly collectd needs to be able to initialize static
 511   variables to NAN (Not A Number). Some C libraries, especially the GNU
 512   libc, have a problem with that.
 513
 514   Luckily, with GCC it's possible to work around that problem: One can define
 515   NAN as being (0.0 / 0.0) and `isnan' as `f != f'. However, to test this
 516   ``implementation'' the configure script needs to compile and run a short
 517   test program. Obviously running a test program when doing a cross-
 518   compilation is, well, challenging.
 519
 520   If you run into this problem, you can use the `--with-nan-emulation'
 521   configure option to force the use of this implementation. We can't promise
 522   that the compiled binary actually behaves as it should, but since NANs
 523   are likely never passed to the libm you have a good chance to be lucky.
 524
 525
 526 Contact
 527 -------
 528
 529   For questions, bugreports, development information and basically all other
 530   concerns please send an email to collectd's mailinglist at
 531   <collectd at verplant.org>.
 532
 533   For live discussion and more personal contact visit us in IRC, we're in
 534   channel #collectd on freenode.
 535
 536
 537 Author
 538 ------
 539
 540   Florian octo Forster <octo at verplant.org>,
 541   Sebastian tokkee Harl <sh at tokkee.org>,
 542   and many contributors (see `AUTHORS').
 543
 544   Please send bugreports and patches to the mailinglist, see `Contact' above.
 545