X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=README;h=24061549c8a201b5b2af50b3be59a3bf9189b125;hb=bee56140f39a62b454ea0eab0c0f9af48aa29e63;hp=4a09fee565581e9a26e96d8208200c18897c7939;hpb=a099e23e239df5b8c5e4ba69594f5d53c9841c82;p=collectd.git diff --git a/README b/README index 4a09fee5..24061549 100644 --- a/README +++ b/README @@ -14,99 +14,214 @@ Features * collectd is able to collect the following data: - - Apache server utilization - (Number of bytes transfered, number of requests handled and detailed - scoreboard statistics) + - apache + Apache server utilization: Number of bytes transfered, number of + requests handled and detailed scoreboard statistics - - APC UPS Daemon - (UPS charge, load, input/output/battery voltage, etc) + - apcups + APC UPS Daemon: UPS charge, load, input/output/battery voltage, etc. - - Apple Sensors - (Temperature, fanspeed and voltage sensors of apple computers) + - apple_sensors + Sensors in Macs running Mac OS X / Darwin: Temperature, fanspeed and + voltage sensors. - - Battery - (Charge, current and charge of ACPI and PMU based batteries) + - battery + Batterycharge, -current and voltage of ACPI and PMU based laptop + batteries. - - CPU utilization - (Time spent in system, user, nice and idle) + - cpu + CPU utilization: Time spent in the system, user, nice, idle, and related + states. - - CPU frequency - (For laptops with speed step or a similar technology) + - cpufreq + CPU frequency (For laptops with speed step or a similar technology) - - Mountpoint usage - (Basically the values `df(1)' delivers) + - df + Mountpoint usage (Basically the values `df(1)' delivers) - - Disk utilization - (Sectors read/written, number of read/write actions, time spent doing IO) + - disk + Disk utilization: Sectors read/written, number of read/write actions, + average time an IO-operation took to complete. - - DNS traffic - (query types, response codes, opcodes and traffic) + - dns + DNS traffic: Query types, response codes, opcodes and traffic/octets + transfered. - - Email statistics - (count, traffic, spam scores and checks) + - email + Email statistics: Count, traffic, spam scores and checks. + See collectd-email(5). - - Harddisk temperatures - (Uhm, yeah, temperature of harddisks that is ;) + - entropy + Amount of entropy available to the system. - - System load - (Load average over the last 1, 5 and 15 minutes) + - exec + Values gathered by a custom program or script. + See collectd-exec(5). - - mbmon - motherboard monitoring - (temperature, fanspeed and voltage information) + - hddtemp + Harddisk temperatures using hddtempd. - - Memory utilization - (Memory occupied by running processes, page cache, buffer cache and free) + - interface + Interface traffic: Number of octets, packets and errors for each + interface. - - Multimeter - (Information provided by serial multimeters, such as the «Metex M-4650CR») + - iptables + Iptables' counters: Number of bytes that were matched by a certain + iptables rule. - - MySQL server statistics - (Commands issued, handlers triggered, thread usage, query cache - utilization and traffic sent/received) + - ipvs + IPVS connection statistics (number of connections, octets and packets + for each service and destination). + See http://www.linuxvirtualserver.org/software/index.html. - - NFS Procedures - (Which NFS command were called how often. Only NFSv2 and NFSv3 right now) + - irq + IRQ counters: Frequency in which certain interrupts occur. - - NTP Daemon - (Local clock drift, offset to peers, etc) + - load + System load average over the last 1, 5 and 15 minutes. - - Ping latency - (Time to reach the default gateway or another given host) + - mbmon + Motherboard sensors: temperature, fanspeed and voltage information, + using mbmon(1). - - Process counts - (Number of running, sleeping, zombie, ... processes) + - memcached + Statistics of the memcached distributed caching system. + - - Sensors - (lm_sensors voltages, temperatures and fan rotation speeds) + - memory + Memory utilization: Memory occupied by running processes, page cache, + buffer cache and free. - - Serial - (RX and TX of serial interfaces) + - multimeter + Information provided by serial multimeters, such as the `Metex + M-4650CR'. - - Swap - (Pages swapped out onto harddisk or whatever is called `swap' by the OS..) + - mysql + MySQL server statistics: Commands issued, handlers triggered, thread + usage, query cache utilization and traffic/octets sent and received. - - Tape - (Read and write bytes and operations on tape devices) + - netlink + Very detailed Linux network interface and routing statistics. You can get + (detailed) information on interfaces, qdiscs, classes, and, if you can + make use of it, filters. - - Traffic - (In/Outbound traffic on the interfaces) + - network + Receive values that were collected by other hosts. Large setups will + want to collect the data on one dedicated machine, and this is the + plugin of choice for that. - - Users - (Currently logged in users) + - nfs + NFS Procedures: Which NFS command were called how often. Only NFSv2 and + NFSv3 right now. - - VServer - (System ressources used by vservers) + - nginx + Collects statistics from `nginx' (speak: engine X), a HTTP and mail + server/proxy. - - Wireless - (Link quality of wireless cards) + - ntp + NTP daemon statistics: Local clock drift, offset to peers, etc. - * Performance: Running as a daemon collectd doesn't spend much time in - startup. Since collectd links against libping, librrd and libsensors it - doesn't need to start any other processes. + - nut + Network UPS tools: UPS current, voltage, power, charge, utilisation, + temperature, etc. See upsd(8). - * Hardly any maintenance neccessary and setup is trivial. + - perl + The perl plugin implements a Perl-interpreter into collectd. You can + write your own plugins in Perl and return arbitrary values using this + API. See collectd-perl(5). - * Extremely easy and failsafe network operation possible. + This plugin is still considered to be experimental and subject to change + between minor releases. + + - ping + Network latency: Time to reach the default gateway or another given + host. + + - processes + Process counts: Number of running, sleeping, zombie, ... processes. + + - sensors + System sensors, accessed using lm_sensors: Voltages, temperatures and + fan rotation speeds. + + - serial + RX and TX of serial interfaces. Linux only; needs root privileges. + + - snmp + Read values from SNMP (Simple Network Management Protocol) enabled + network devices such as switches, routers, thermometers, rack monitoring + servers, etc. See collectd-snmp(5). + + - swap + Pages swapped out onto harddisk or whatever is called `swap' by the OS.. + + - tape + Bytes and operations read and written on tape devices. Solaris only. + + - tcpconns + Number of TCP connections to specific local and remote ports. + + - users + Users currently logged in. + + - vserver + System resources used by Linux VServers. + See . + + - wireless + Link quality of wireless cards. Linux only. + + - xmms + Bitrate and frequency of music played with XMMS. + + * Output can be written or send to various destinations by the following + plugins: + + - csv + Write to comma separated values (CSV) files. This needs lots of + diskspace but is extremely portable and can be analysed with almost + every program that can analyse anything. Even Microsoft's Excel.. + + - network + Send the data to a remote host to save the data somehow. This is useful + for large setups where the data should be saved by a dedicated machine. + + - perl + Of course the values are propagated to plugins written in Perl, too, so + you can easily do weird stuff with the plugins we didn't dare think of + ;) See collectd-perl(5). + + - rrdtool + Output to round-robin-database (RRD) files using librrd. See rrdtool(1). + This is likely the most popular destination for such values. Since + updates to RRD-files are somewhat expensive this plugin can cache + updates to the files and write a bunch of updates at once, which lessens + system load a lot. + + - unixsock + One can query the values from the unixsock plugin whenever they're + needed. Please read collectd-unixsock(5) for a description on how that's + done. + + * Logging is, as everything in collectd, provided by plugins. The following + plugins keep up informed about what's going on: + + - logfile + Writes logmessages to a file or STDOUT/STDERR. + + - syslog + Logs to the standard UNIX logging mechanism, syslog. + + * Performance: Since collectd is running as a daemon it doesn't spend much + time starting up again and again. With the exception of the exec plugin no + processes are forked. Caching in output plugins, such as the rrdtool and + network plugins, makes sure your resources are used efficiently. Also, + since collectd is programmed multithreaded it benefits from hyperthreading + and multicore processors and makes sure that the daemon isn't idle if only + one plugins waits for an IO-operation to complete. + + * Once set up, hardly any maintenance is necessary. Setup is kept as easy + as possible and the default values should be okay for most users. Operation @@ -116,23 +231,36 @@ Operation Run `collectd -h' for a list of builtin defaults. See `collectd.conf(5)' for a list of options and a syntax description. - * When running collectd writes system statistics in RRD-files. Per default - they reside in `/var/lib/collectd'. + * When the `csv' or `rrdtool' plugins are loaded they'll write the values to + files. The usual place for these files is beneath `/var/lib/collectd'. - * When using the `ping' plugin collectd needs to run as user root, since only - root can craft ICMP packages needed to ping other hosts. collectd should - NOT be installed setuid root since it can be used to overwrite valuable - files.. + * When using some of the plugins, collectd needs to run as user root, since + only root can do certain things, such as craft ICMP packages needed to ping + other hosts. collectd should NOT be installed setuid root since it can be + used to overwrite valuable files! * Sample scripts to generate graphs reside in `contrib/' in the source package or somewhere near `/usr/share/doc/collectd' in most distributions. Please be aware that those script are meant as a starting point for your own experiments.. Some of them require the `RRDs' Perl module. - (`librrds-perl' on Debian) + (`librrds-perl' on Debian) If you have written a more sophisticated + solution please share it with us. * The RRAs of the automatically created RRD files depend on the `step' - and `heartbeat' settings given on compile time. For a list of the - default RRAs take a look in the collectd(1) manpage. + and `heartbeat' settings given. If change these settings you may need to + re-create the files, losing all data. Please be aware of that when changing + the values and read the rrdtool(1) manpage thoroughly. + + +collectd and chkrootkit +----------------------- + + If you are using the `dns' plugin chkrootkit(1) will report collectd as a + packet sniffer (": PACKET SNIFFER(/usr/sbin/collectd[])"). The + plugin captures all UDP packets on port 53 to analyze the DNS traffic. In + this case, collectd is a legitimate sniffer and the report should be + considered to be a false positive. However, you might want to check that + this really is collectd and not some other, illegitimate sniffer. Prerequisites @@ -142,37 +270,120 @@ Prerequisites * Usual suspects: C compiler, linker, preprocessor, make, ... - * rrdtool (optional; headers and library; rrdtool 1.0 and 1.2 both work fine) - If built without `librrd' the resulting binary will be `client only', i.e. - will send it's values via multicast and not create any RRD files itself. - Alternatively you can chose to write CSV-files (Comma Seperated Values) - instead. + * A POSIX-threads (pthread) implementation. + Since gathering some statistics is slow (network connections, slow devices, + etc) the collectd is parallelized. The POSIX threads interface is being + used and should be found in various implementations for hopefully all + platforms. + + * libcurl (optional) + If you want to use the `apache' and/or `nginx' plugins. + + * libiptc (optional) + For querying iptables counters. * libmysqlclient (optional) + Unsurprisingly used by the `mysql' plugin. + + * libnetlink (optional) + Used, obviously, for the `netlink' plugin. + + * libnetsnmp (optional) + For the `snmp' plugin. + + * liboping (optional, if not found a version shipped with this distribution + can be used) + Used by the `ping' plugin to send and receive ICMP packets. + + * libpcap (optional) + Used to capture packets by the `dns' plugin. + + * librrd (optional; headers and library; rrdtool 1.0 and 1.2 both work fine) + If built without `librrd' the resulting binary will be `client only', i.e. + will send its values via multicast and not create any RRD files itself. + Alternatively you can chose to write CSV-files (Comma Separated Values) + instead. - * lm-sensors (optional) + * libsensors (optional) + To read from `lm_sensors', see the `sensors' plugin. * libstatgrab may be used to collect statistics on systems other than Linux and/or Solaris. Note that CPU- and disk-statistics, while being provided by this library, are not supported in collectd right now.. - * libcurl (optional) - If you want to use the `apache' plugin + * libupsclient/nut (optional) + For the `nut' plugin which queries nut's `upsd'. + + * libxmms (optional) * librt, libsocket, libkstat, libdevinfo Various standard Solaris libraries which provide system functions. - * libpthread (optional) - For parallelization, especially for plugins that communicate with the - outside, e. g. with a socket. - * CoreFoundation.framework and IOKit.framework - For copiling on darwin in general and the `apple_sensors' plugin in + For compiling on Darwin in general and the `apple_sensors' plugin in particular. + +Configuring / Compiling / Installing +------------------------------------ + + To configure, build and install collectd with the default settings, run + `./configure && make && make install'. For detailed, generic instructions + see INSTALL. For a complete list of configure options and their description, + run `./configure --help'. + + By default, the configure script will check for all build dependencies and + disable all plugins whose requirements cannot be fulfilled (any other plugin + will be enabled). To enable a plugin, install missing dependencies (see + section `Prerequisites' above) and rerun `configure'. If you specify the + `--enable-' configure option, you can force the plugin to be built. + This will most likely fail though unless you're working in a very unusual + setup and you really know what you're doing. + + By default, collectd will be installed into `/opt/collectd'. You can adjust + this setting by specifying the `--prefix' configure option - see INSTALL for + details. If you pass DESTDIR= to `make install', will be + prefixed to all installation directories. This might be useful when creating + packages for collectd. + + +Crosscompiling +-------------- + + To compile correctly collectd needs to be able to initialize static + variables to NAN (Not A Number). Some C libraries, especially the GNU + libc, have a problem with that. + + Luckily, with GCC it's possible to work around that problem: One can define + NAN as being (0.0 / 0.0) and `isnan' as `f != f'. However, to test this + ``implementation'' the configure script needs to compile and run a short + test program. Obviously running a test program when doing a cross- + compilation is, well, challenging. + + If you run into this problem, you can use the `--with-nan-emulation' + configure option to force the use of this implementation. We can't promise + that the compiled binary actually behaves as it should, but since NANs + are likely never passed to the libm you have a good chance to be lucky. + + +Contact +------- + + For questions, bugreports, development information and basically all other + concerns please send an email to collectd's mailinglist at + . + + For live discussion and more personal contact visit us in IRC, we're in + channel #collectd on freenode. + + Author ------ - Florian octo Forster + Florian octo Forster , + Sebastian tokkee Harl , + and many contributors (see `AUTHORS'). + + Please send bugreports and patches to the mailinglist, see `Contact' above.