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