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