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