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 value lists based on Perl-compatible regular expressions.
 258
 259   * Logging is, as everything in collectd, provided by plugins. The following
 260     plugins keep up informed about what's going on:
 261
 262     - logfile
 263       Writes logmessages to a file or STDOUT/STDERR.
 264
 265     - perl
 266       Log messages are propagated to plugins written in Perl as well.
 267       See collectd-perl(5).
 268
 269     - syslog
 270       Logs to the standard UNIX logging mechanism, syslog.
 271
 272   * Notifications can be handled by the following plugins:
 273
 274     - notify_desktop
 275       Send a desktop notification to a notification daemon, as defined in
 276       the Desktop Notification Specification. To actually display the
 277       notifications, notification-daemon is required.
 278       See http://www.galago-project.org/specs/notification/.
 279
 280     - notify_email
 281       Send an E-mail with the notification message to the configured
 282       recipients.
 283
 284     - exec
 285       Execute a program or script to handle the notification.
 286       See collectd-exec(5).
 287
 288     - logfile
 289       Writes the notification message to a file or STDOUT/STDERR.
 290
 291     - network
 292       Send the notification to a remote host to handle it somehow.
 293
 294     - perl
 295       Notifications are propagated to plugins written in Perl as well.
 296       See collectd-perl(5).
 297
 298   * Miscellaneous plugins:
 299
 300     - uuid
 301       Sets the hostname to an unique identifier. This is meant for setups
 302       where each client may migrate to another physical host, possibly going
 303       through one or more name changes in the process.
 304
 305   * Performance: Since collectd is running as a daemon it doesn't spend much
 306     time starting up again and again. With the exception of the exec plugin no
 307     processes are forked. Caching in output plugins, such as the rrdtool and
 308     network plugins, makes sure your resources are used efficiently. Also,
 309     since collectd is programmed multithreaded it benefits from hyperthreading
 310     and multicore processors and makes sure that the daemon isn't idle if only
 311     one plugins waits for an IO-operation to complete.
 312
 313   * Once set up, hardly any maintenance is necessary. Setup is kept as easy
 314     as possible and the default values should be okay for most users.
 315
 316
 317 Operation
 318 ---------
 319
 320   * collectd's configuration file can be found at `sysconfdir'/collectd.conf.
 321     Run `collectd -h' for a list of builtin defaults. See `collectd.conf(5)'
 322     for a list of options and a syntax description.
 323
 324   * When the `csv' or `rrdtool' plugins are loaded they'll write the values to
 325     files. The usual place for these files is beneath `/var/lib/collectd'.
 326
 327   * When using some of the plugins, collectd needs to run as user root, since
 328     only root can do certain things, such as craft ICMP packages needed to ping
 329     other hosts. collectd should NOT be installed setuid root since it can be
 330     used to overwrite valuable files!
 331
 332   * Sample scripts to generate graphs reside in `contrib/' in the source
 333     package or somewhere near `/usr/share/doc/collectd' in most distributions.
 334     Please be aware that those script are meant as a starting point for your
 335     own experiments.. Some of them require the `RRDs' Perl module.
 336     (`librrds-perl' on Debian) If you have written a more sophisticated
 337     solution please share it with us.
 338
 339   * The RRAs of the automatically created RRD files depend on the `step'
 340     and `heartbeat' settings given. If change these settings you may need to
 341     re-create the files, losing all data. Please be aware of that when changing
 342     the values and read the rrdtool(1) manpage thoroughly.
 343
 344
 345 collectd and chkrootkit
 346 -----------------------
 347
 348   If you are using the `dns' plugin chkrootkit(1) will report collectd as a
 349   packet sniffer ("<iface>: PACKET SNIFFER(/usr/sbin/collectd[<pid>])"). The
 350   plugin captures all UDP packets on port 53 to analyze the DNS traffic. In
 351   this case, collectd is a legitimate sniffer and the report should be
 352   considered to be a false positive. However, you might want to check that
 353   this really is collectd and not some other, illegitimate sniffer.
 354
 355
 356 Prerequisites
 357 -------------
 358
 359   To compile collectd from source you will need:
 360
 361   * Usual suspects: C compiler, linker, preprocessor, make, ...
 362
 363   * A POSIX-threads (pthread) implementation.
 364     Since gathering some statistics is slow (network connections, slow devices,
 365     etc) the collectd is parallelized. The POSIX threads interface is being
 366     used and should be found in various implementations for hopefully all
 367     platforms.
 368
 369   * CoreFoundation.framework and IOKit.framework (optional)
 370     For compiling on Darwin in general and the `apple_sensors' plugin in
 371     particular.
 372     <http://developer.apple.com/corefoundation/>
 373
 374   * libcurl (optional)
 375     If you want to use the `apache', `ascent', or `nginx' plugin.
 376     <http://curl.haxx.se/>
 377
 378   * libdbi (optional)
 379     Used by the `dbi' plugin to connect to various databases.
 380     <http://libdbi.sourceforge.net/>
 381
 382   * libesmtp (optional)
 383     For the `notify_email' plugin.
 384     <http://www.stafford.uklinux.net/libesmtp/>
 385
 386   * libhal (optional)
 387     If present, the uuid plugin will check for UUID from HAL.
 388     <http://hal.freedesktop.org/>
 389
 390   * libiptc (optional, if not found a version shipped with this distribution
 391     can be used if the Linux kernel headers are available)
 392     For querying iptables counters.
 393     <http://netfilter.org/>
 394
 395   * libmysqlclient (optional)
 396     Unsurprisingly used by the `mysql' plugin.
 397     <http://dev.mysql.com/>
 398
 399   * libnetlink (optional)
 400     Used, obviously, for the `netlink' plugin.
 401     <http://www.linuxfoundation.org/en/Net:Iproute2>
 402
 403   * libnetsnmp (optional)
 404     For the `snmp' plugin.
 405     <http://www.net-snmp.org/>
 406
 407   * libnotify (optional)
 408     For the `notify_desktop' plugin.
 409     <http://www.galago-project.org/>
 410
 411   * liboping (optional, if not found a version shipped with this distribution
 412     can be used)
 413     Used by the `ping' plugin to send and receive ICMP packets.
 414     <http://verplant.org/liboping/>
 415
 416   * libowcapi (optional)
 417     Used by the `onewire' plugin to read values from onewire sensors (or the
 418     owserver(1) daemon).
 419     <http://www.owfs.org/>
 420
 421   * libpcap (optional)
 422     Used to capture packets by the `dns' plugin.
 423     <http://www.tcpdump.org/>
 424
 425   * libpcre (optional)
 426     Used by the `filter_pcre' plugin.
 427     <http://www.pcre.org/>
 428
 429   * libperl (optional)
 430     Obviously used by the `perl' plugin. The library has to be compiled with
 431     ithread support (introduced in Perl 5.6.0).
 432     <http://www.perl.org/>
 433
 434   * libpq (optional)
 435     The PostgreSQL C client library used by the `postgresql' plugin.
 436     <http://www.postgresql.org/>
 437
 438   * librrd (optional)
 439     Used by the `rrdtool' and `rrdcached' plugins. The latter requires RRDtool
 440     client support which was added after version 1.3 of RRDtool. Versions 1.0,
 441     1.2 and 1.3 are known to work with the `rrdtool' plugin.
 442     <http://oss.oetiker.ch/rrdtool/>
 443
 444   * librt, libsocket, libkstat, libdevinfo (optional)
 445     Various standard Solaris libraries which provide system functions.
 446     <http://developers.sun.com/solaris/>
 447
 448   * libsensors (optional)
 449     To read from `lm_sensors', see the `sensors' plugin.
 450     <http://www.lm-sensors.org/>
 451
 452   * libstatgrab (optional)
 453     Used by various plugins to collect statistics on systems other than Linux
 454     and/or Solaris.
 455     <http://www.i-scream.org/libstatgrab/>
 456
 457   * libupsclient/nut (optional)
 458     For the `nut' plugin which queries nut's `upsd'.
 459     <http://networkupstools.org/>
 460
 461   * libvirt (optional)
 462     Collect statistics from virtual machines.
 463     <http://libvirt.org/>
 464
 465   * libxml2 (optional)
 466     Parse XML data. This is needed for the `ascent' and `libvirt' plugins.
 467     <http://xmlsoft.org/>
 468
 469   * libxmms (optional)
 470     <http://www.xmms.org/>
 471
 472
 473 Configuring / Compiling / Installing
 474 ------------------------------------
 475
 476   To configure, build and install collectd with the default settings, run
 477   `./configure && make && make install'.  For detailed, generic instructions
 478   see INSTALL. For a complete list of configure options and their description,
 479   run `./configure --help'.
 480
 481   By default, the configure script will check for all build dependencies and
 482   disable all plugins whose requirements cannot be fulfilled (any other plugin
 483   will be enabled). To enable a plugin, install missing dependencies (see
 484   section `Prerequisites' above) and rerun `configure'. If you specify the
 485   `--enable-<plugin>' configure option, the script will fail if the depen-
 486   dencies for the specified plugin are not met. If you specify the
 487   `--disable-<plugin>' configure option, the plugin will not be built. Both
 488   options are meant for package maintainers and should not be used in everyday
 489   situations.
 490
 491   By default, collectd will be installed into `/opt/collectd'. You can adjust
 492   this setting by specifying the `--prefix' configure option - see INSTALL for
 493   details. If you pass DESTDIR=<path> to `make install', <path> will be
 494   prefixed to all installation directories. This might be useful when creating
 495   packages for collectd.
 496
 497
 498 Crosscompiling
 499 --------------
 500
 501   To compile correctly collectd needs to be able to initialize static
 502   variables to NAN (Not A Number). Some C libraries, especially the GNU
 503   libc, have a problem with that.
 504
 505   Luckily, with GCC it's possible to work around that problem: One can define
 506   NAN as being (0.0 / 0.0) and `isnan' as `f != f'. However, to test this
 507   ``implementation'' the configure script needs to compile and run a short
 508   test program. Obviously running a test program when doing a cross-
 509   compilation is, well, challenging.
 510
 511   If you run into this problem, you can use the `--with-nan-emulation'
 512   configure option to force the use of this implementation. We can't promise
 513   that the compiled binary actually behaves as it should, but since NANs
 514   are likely never passed to the libm you have a good chance to be lucky.
 515
 516
 517 Contact
 518 -------
 519
 520   For questions, bugreports, development information and basically all other
 521   concerns please send an email to collectd's mailinglist at
 522   <collectd at verplant.org>.
 523
 524   For live discussion and more personal contact visit us in IRC, we're in
 525   channel #collectd on freenode.
 526
 527
 528 Author
 529 ------
 530
 531   Florian octo Forster <octo at verplant.org>,
 532   Sebastian tokkee Harl <sh at tokkee.org>,
 533   and many contributors (see `AUTHORS').
 534
 535   Please send bugreports and patches to the mailinglist, see `Contact' above.
 536