X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=README;h=37eee3eaeb2f51004ec9791532edda1fc9347564;hb=3e5c93f05cbea0639b8401b7a6e6f382ca6aad1f;hp=4d6f677e2ef73f85d466e493ef56ba73068906f5;hpb=326b642e0739c9fe9c4de43d72cb260fdefa60b0;p=collectd.git
diff --git a/README b/README
index 4d6f677e..37eee3ea 100644
--- a/README
+++ b/README
@@ -1,6 +1,6 @@
collectd - System information collection daemon
=================================================
-http://verplant.org/collectd/
+http://collectd.org/
About
-----
@@ -14,81 +14,198 @@ 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
- - Apple Sensors
- (Temperature, fanspeed and voltage sensors of apple computers)
+ - apcups
+ APC UPS Daemon: UPS charge, load, input/output/battery voltage, etc.
- - Battery
- (Charge, current and charge of ACPI and PMU based batteries)
+ - apple_sensors
+ Sensors in Macs running Mac OS X / Darwin: Temperature, fanspeed and
+ voltage sensors.
- - CPU utilization
- (Time spent in system, user, nice and idle)
+ - battery
+ Batterycharge, -current and voltage of ACPI and PMU based laptop
+ batteries.
- - CPU frequency
- (For laptops with speed step or a similar technology)
+ - cpu
+ CPU utilization: Time spent in the system, user, nice, idle, and related
+ states.
- - Mountpoint usage
- (Basically the values `df(1)' delivers)
+ - cpufreq
+ CPU frequency (For laptops with speed step or a similar technology)
- - Disk utilization
- (Sectors read/written, number of read/write actions, time spent doing IO)
+ - df
+ Mountpoint usage (Basically the values `df(1)' delivers)
- - Harddisk temperatures
- (Uhm, yeah, temperature of harddisks that is ;)
+ - disk
+ Disk utilization: Sectors read/written, number of read/write actions,
+ average time an IO-operation took to complete.
- - System load
- (Load average over the last 1, 5 and 15 minutes)
+ - dns
+ DNS traffic: Query types, response codes, opcodes and traffic/octets
+ transfered.
- - Memory utilization
- (Memory occupied by running processes, page cache, buffer cache and free)
+ - email
+ Email statistics: Count, traffic, spam scores and checks.
+ See collectd-email(5).
- - MySQL server statistics
- (Commands issued, handlers triggered, thread usage, query cache
- utilization and traffic sent/received)
+ - entropy
+ Amount of entropy available to the system.
- - NFS Procedures
- (Which NFS command were called how often. Only NFSv2 and NFSv3 right now)
+ - exec
+ Values gathered by a custom program or script.
+ See collectd-exec(5).
- - Ping latency
- (Time to reach the default gateway or another given host)
+ - hddtemp
+ Harddisk temperatures using hddtempd.
- - Process counts
- (Number of running, sleeping, zombie, ... processes)
+ - interface
+ Interface traffic: Number of octets, packets and errors for each
+ interface.
- - Sensors
- (System temperatured and fan rotation speeds)
+ - iptables
+ Iptables' counters: Number of bytes that were matched by a certain
+ iptables rule.
- - Serial
- (RX and TX of serial interfaces)
+ - irq
+ IRQ counters: Frequency in which certain interrupts occur.
- - Swap
- (Pages swapped out onto harddisk or whatever is called `swap' by the OS..)
+ - load
+ System load average over the last 1, 5 and 15 minutes.
- - Tape
- (Read and write bytes and operations on tape devices)
+ - mbmon
+ Motherboard sensors: temperature, fanspeed and voltage information,
+ using mbmon(1).
- - Traffic
- (In/Outbound traffic on the interfaces)
+ - memory
+ Memory utilization: Memory occupied by running processes, page cache,
+ buffer cache and free.
- - Users
- (Currently logged in users)
+ - multimeter
+ Information provided by serial multimeters, such as the `Metex
+ M-4650CR'.
- - VServer
- (System ressources used by vservers)
+ - mysql
+ MySQL server statistics: Commands issued, handlers triggered, thread
+ usage, query cache utilization and traffic/octets sent and received.
- - Wireless
- (Link quality of wireless cards)
+ - 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.
- * 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.
+ - 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.
- * Hardly any maintenance neccessary and setup is trivial.
+ - nfs
+ NFS Procedures: Which NFS command were called how often. Only NFSv2 and
+ NFSv3 right now.
- * Extremely easy and failsafe network operation possible.
+ - ntp
+ NTP daemon statistics: Local clock drift, offset to peers, etc.
+
+ - nut
+ Network UPS tools: UPS current, voltage, power, charge, utilisation,
+ temperature, etc. See upsd(8).
+
+ - 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).
+
+ 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.
+
+ - 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
@@ -98,28 +215,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 RRD-files that collectd creates hold the following data. Use ``rrdtool
- resize'' if you want to cover longer/shorter periods of time.
+ * The RRAs of the automatically created RRD files depend on the `step'
+ 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.
- Resolution | Data points | Timespan
- -----------+-------------+----------
- 60 seconds | 1500 | 25 hours
- 30 minutes | 1680 | 35 days
- 6 hours | 1520 | 380 days
+
+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
@@ -129,21 +254,117 @@ Prerequisites
* Usual suspects: C compiler, linker, preprocessor, make, ...
- * rrdtool (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.
+ * 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' plugin
+
+ * libiptc (optional)
+ For querying iptables counters.
* libmysqlclient (optional)
- * lm-sensors (optional)
+ * libnetlink (optional)
+
+ * libnetsnmp (optional)
+
+ * 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.
+
+ * libsensors (optional)
+ To read from `lm_sensors'.
* 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..
+ and/or Solaris. Note that CPU- and disk-statistics, while being provided
+ by this library, are not supported in collectd right now..
+ * 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.
+
+ * CoreFoundation.framework and IOKit.framework
+ 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.