collectd-python(5): Some more formatting and typo fixes.
[collectd.git] / 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     - curl
37       Parse statistics from websites using regular expressions.
38
39     - bind
40       Name server and resolver statistics from the `statistics-channel'
41       interface of BIND 9.5, 9,6 and later.
42
43     - conntrack
44       Number of nf_conntrack entries.
45
46     - curl_json
47       Retrieves JSON data via cURL and parses it according to user
48       configuration.
49
50     - cpu
51       CPU utilization: Time spent in the system, user, nice, idle, and related
52       states.
53
54     - cpufreq
55       CPU frequency (For laptops with speed step or a similar technology)
56
57     - dbi
58       Executes SQL statements on various databases and interprets the returned
59       data.
60
61     - df
62       Mountpoint usage (Basically the values `df(1)' delivers)
63
64     - disk
65       Disk utilization: Sectors read/written, number of read/write actions,
66       average time an IO-operation took to complete.
67
68     - dns
69       DNS traffic: Query types, response codes, opcodes and traffic/octets
70       transfered.
71
72     - email
73       Email statistics: Count, traffic, spam scores and checks.
74       See collectd-email(5).
75
76     - entropy
77       Amount of entropy available to the system.
78
79     - exec
80       Values gathered by a custom program or script.
81       See collectd-exec(5).
82
83     - filecount
84       Count the number of files in directories.
85
86     - fscache
87       Linux file-system based caching framework statistics.
88
89     - gmond
90       Receive multicast traffic from Ganglia instances.
91
92     - hddtemp
93       Harddisk temperatures using hddtempd.
94
95     - interface
96       Interface traffic: Number of octets, packets and errors for each
97       interface.
98
99     - iptables
100       Iptables' counters: Number of bytes that were matched by a certain
101       iptables rule.
102
103     - ipmi
104       IPMI (Intelligent Platform Management Interface) sensors information.
105
106     - ipvs
107       IPVS connection statistics (number of connections, octets and packets
108       for each service and destination).
109       See http://www.linuxvirtualserver.org/software/index.html.
110
111     - irq
112       IRQ counters: Frequency in which certain interrupts occur.
113
114     - java
115       Integrates a `Java Virtual Machine' (JVM) to execute plugins in Java
116       bytecode. See “Configuring with libjvm” below.
117
118     - load
119       System load average over the last 1, 5 and 15 minutes.
120
121     - libvirt
122       CPU, disk and network I/O statistics from virtual machines.
123
124     - madwifi
125       Queries very detailed usage statistics from wireless LAN adapters and
126       interfaces that use the Atheros chipset and the MadWifi driver.
127
128     - mbmon
129       Motherboard sensors: temperature, fanspeed and voltage information,
130       using mbmon(1).
131
132     - memcachec
133       Query and parse data from a memcache daemon (memcached).
134
135     - memcached
136       Statistics of the memcached distributed caching system.
137       <http://www.danga.com/memcached/>
138
139     - memory
140       Memory utilization: Memory occupied by running processes, page cache,
141       buffer cache and free.
142
143     - multimeter
144       Information provided by serial multimeters, such as the `Metex
145       M-4650CR'.
146
147     - mysql
148       MySQL server statistics: Commands issued, handlers triggered, thread
149       usage, query cache utilization and traffic/octets sent and received.
150
151     - netapp
152       Plugin to query performance values from a NetApp storage system using the
153       “Manage ONTAP” SDK provided by NetApp.
154
155     - netlink
156       Very detailed Linux network interface and routing statistics. You can get
157       (detailed) information on interfaces, qdiscs, classes, and, if you can
158       make use of it, filters.
159
160     - network
161       Receive values that were collected by other hosts. Large setups will
162       want to collect the data on one dedicated machine, and this is the
163       plugin of choice for that.
164
165     - nfs
166       NFS Procedures: Which NFS command were called how often. Only NFSv2 and
167       NFSv3 right now.
168
169     - nginx
170       Collects statistics from `nginx' (speak: engine X), a HTTP and mail
171       server/proxy.
172
173     - ntpd
174       NTP daemon statistics: Local clock drift, offset to peers, etc.
175
176     - nut
177       Network UPS tools: UPS current, voltage, power, charge, utilisation,
178       temperature, etc. See upsd(8).
179
180     - olsr
181       Queries routing information from the “Optimized Link State Routing”
182       daemon.
183
184     - onewire (EXPERIMENTAL!)
185       Read onewire sensors using the owcapu library of the owfs project.
186       Please read in collectd.conf(5) why this plugin is experimental.
187
188     - openvpn
189       RX and TX of each client in openvpn-status.log (status-version 2).
190       <http://openvpn.net/index.php/documentation/howto.html>
191
192     - oracle
193       Query data from an Oracle database.
194
195     - perl
196       The perl plugin implements a Perl-interpreter into collectd. You can
197       write your own plugins in Perl and return arbitrary values using this
198       API. See collectd-perl(5).
199
200     - ping
201       Network latency: Time to reach the default gateway or another given
202       host.
203
204     - postgresql
205       PostgreSQL database statistics: active server connections, transaction
206       numbers, block IO, table row manipulations.
207
208     - powerdns
209       PowerDNS name server statistics.
210
211     - processes
212       Process counts: Number of running, sleeping, zombie, ... processes.
213
214     - protocols
215       Counts various aspects of network protocols such as IP, TCP, UDP, etc.
216
217     - python
218       The python plugin implements a Python interpreter into collectd. This
219       makes it possible to write plugins in Python which are executed by
220       collectd without the need to start a heavy interpreter every interval.
221       See collectd-python(5) for details.
222
223     - rrdcached
224       RRDtool caching daemon (RRDcacheD) statistics.
225
226     - sensors
227       System sensors, accessed using lm_sensors: Voltages, temperatures and
228       fan rotation speeds.
229
230     - serial
231       RX and TX of serial interfaces. Linux only; needs root privileges.
232
233     - snmp
234       Read values from SNMP (Simple Network Management Protocol) enabled
235       network devices such as switches, routers, thermometers, rack monitoring
236       servers, etc. See collectd-snmp(5).
237
238     - swap
239       Pages swapped out onto harddisk or whatever is called `swap' by the OS..
240
241     - table
242       Parse table-like structured files.
243
244     - tail
245       Follows (tails) logfiles, parses them by lines and submits matched
246       values.
247
248     - tape
249       Bytes and operations read and written on tape devices. Solaris only.
250
251     - tcpconns
252       Number of TCP connections to specific local and remote ports.
253
254     - teamspeak2
255       TeamSpeak2 server statistics.
256
257     - ted
258       Plugin to read values from `The Energy Detective' (TED).
259
260     - thermal
261       Linux ACPI thermal zone information.
262
263     - tokyotyrant
264       Reads the number of records and file size from a running Tokyo Tyrant
265       server.
266
267     - uptime
268       System uptime statistics.
269
270     - users
271       Users currently logged in.
272
273     - vmem
274       Virtual memory statistics, e. g. the number of page-ins/-outs or the
275       number of pagefaults.
276
277     - vserver
278       System resources used by Linux VServers.
279       See <http://linux-vserver.org/>.
280
281     - wireless
282       Link quality of wireless cards. Linux only.
283
284     - xmms
285       Bitrate and frequency of music played with XMMS.
286
287     - zfs_arc
288       Statistics for ZFS' “Adaptive Replacement Cache” (ARC).
289
290   * Output can be written or send to various destinations by the following
291     plugins:
292
293     - csv
294       Write to comma separated values (CSV) files. This needs lots of
295       diskspace but is extremely portable and can be analysed with almost
296       every program that can analyse anything. Even Microsoft's Excel..
297
298     - network
299       Send the data to a remote host to save the data somehow. This is useful
300       for large setups where the data should be saved by a dedicated machine.
301
302     - perl
303       Of course the values are propagated to plugins written in Perl, too, so
304       you can easily do weird stuff with the plugins we didn't dare think of
305       ;) See collectd-perl(5).
306
307     - python
308       It's possible to implement write plugins in Python using the python
309       plugin. See collectd-python(5) for details.
310
311     - rrdcached
312       Output to round-robin-database (RRD) files using the RRDtool caching
313       daemon (RRDcacheD) - see rrdcached(1). That daemon provides a general
314       implementation of the caching done by the `rrdtool' plugin.
315
316     - rrdtool
317       Output to round-robin-database (RRD) files using librrd. See rrdtool(1).
318       This is likely the most popular destination for such values. Since
319       updates to RRD-files are somewhat expensive this plugin can cache
320       updates to the files and write a bunch of updates at once, which lessens
321       system load a lot.
322
323     - unixsock
324       One can query the values from the unixsock plugin whenever they're
325       needed. Please read collectd-unixsock(5) for a description on how that's
326       done.
327
328     - write_http
329       Sends the values collected by collectd to a web-server using HTTP POST
330       requests. The transmitted data is either in a form understood by the
331       Exec plugin or formatted in JSON.
332
333   * Logging is, as everything in collectd, provided by plugins. The following
334     plugins keep up informed about what's going on:
335
336     - logfile
337       Writes logmessages to a file or STDOUT/STDERR.
338
339     - perl
340       Log messages are propagated to plugins written in Perl as well.
341       See collectd-perl(5).
342
343     - python
344       It's possible to implement log plugins in Python using the python plugin.
345       See collectd-python(5) for details.
346
347     - syslog
348       Logs to the standard UNIX logging mechanism, syslog.
349
350   * Notifications can be handled by the following plugins:
351
352     - notify_desktop
353       Send a desktop notification to a notification daemon, as defined in
354       the Desktop Notification Specification. To actually display the
355       notifications, notification-daemon is required.
356       See http://www.galago-project.org/specs/notification/.
357
358     - notify_email
359       Send an E-mail with the notification message to the configured
360       recipients.
361
362     - exec
363       Execute a program or script to handle the notification.
364       See collectd-exec(5).
365
366     - logfile
367       Writes the notification message to a file or STDOUT/STDERR.
368
369     - network
370       Send the notification to a remote host to handle it somehow.
371
372     - perl
373       Notifications are propagated to plugins written in Perl as well.
374       See collectd-perl(5).
375
376     - python
377       It's possible to implement notification plugins in Python using the
378       python plugin. See collectd-python(5) for details.
379
380   * Value processing can be controlled using the "filter chain" infrastructure
381     and "matches" and "targets". The following plugins are available:
382
383     - match_empty_counter
384       Match counter values which are currently zero.
385
386     - match_regex
387       Match values by their identifier based on regular expressions.
388
389     - match_timediff
390       Match values with an invalid timestamp.
391
392     - match_value
393       Select values by their data sources' values.
394
395     - target_notification
396       Create and dispatch a notification.
397
398     - target_replace
399       Replace parts of an identifier using regular expressions.
400
401     - target_set
402       Set (overwrite) entire parts of an identifier.
403
404   * Miscellaneous plugins:
405
406     - uuid
407       Sets the hostname to an unique identifier. This is meant for setups
408       where each client may migrate to another physical host, possibly going
409       through one or more name changes in the process.
410
411   * Performance: Since collectd is running as a daemon it doesn't spend much
412     time starting up again and again. With the exception of the exec plugin no
413     processes are forked. Caching in output plugins, such as the rrdtool and
414     network plugins, makes sure your resources are used efficiently. Also,
415     since collectd is programmed multithreaded it benefits from hyperthreading
416     and multicore processors and makes sure that the daemon isn't idle if only
417     one plugins waits for an IO-operation to complete.
418
419   * Once set up, hardly any maintenance is necessary. Setup is kept as easy
420     as possible and the default values should be okay for most users.
421
422
423 Operation
424 ---------
425
426   * collectd's configuration file can be found at `sysconfdir'/collectd.conf.
427     Run `collectd -h' for a list of builtin defaults. See `collectd.conf(5)'
428     for a list of options and a syntax description.
429
430   * When the `csv' or `rrdtool' plugins are loaded they'll write the values to
431     files. The usual place for these files is beneath `/var/lib/collectd'.
432
433   * When using some of the plugins, collectd needs to run as user root, since
434     only root can do certain things, such as craft ICMP packages needed to ping
435     other hosts. collectd should NOT be installed setuid root since it can be
436     used to overwrite valuable files!
437
438   * Sample scripts to generate graphs reside in `contrib/' in the source
439     package or somewhere near `/usr/share/doc/collectd' in most distributions.
440     Please be aware that those script are meant as a starting point for your
441     own experiments.. Some of them require the `RRDs' Perl module.
442     (`librrds-perl' on Debian) If you have written a more sophisticated
443     solution please share it with us.
444
445   * The RRAs of the automatically created RRD files depend on the `step'
446     and `heartbeat' settings given. If change these settings you may need to
447     re-create the files, losing all data. Please be aware of that when changing
448     the values and read the rrdtool(1) manpage thoroughly.
449
450
451 collectd and chkrootkit
452 -----------------------
453
454   If you are using the `dns' plugin chkrootkit(1) will report collectd as a
455   packet sniffer ("<iface>: PACKET SNIFFER(/usr/sbin/collectd[<pid>])"). The
456   plugin captures all UDP packets on port 53 to analyze the DNS traffic. In
457   this case, collectd is a legitimate sniffer and the report should be
458   considered to be a false positive. However, you might want to check that
459   this really is collectd and not some other, illegitimate sniffer.
460
461
462 Prerequisites
463 -------------
464
465   To compile collectd from source you will need:
466
467   * Usual suspects: C compiler, linker, preprocessor, make, ...
468
469   * A POSIX-threads (pthread) implementation.
470     Since gathering some statistics is slow (network connections, slow devices,
471     etc) the collectd is parallelized. The POSIX threads interface is being
472     used and should be found in various implementations for hopefully all
473     platforms.
474
475   * CoreFoundation.framework and IOKit.framework (optional)
476     For compiling on Darwin in general and the `apple_sensors' plugin in
477     particular.
478     <http://developer.apple.com/corefoundation/>
479
480   * libclntsh (optional)
481     Used by the `oracle' plugin.
482
483   * libcurl (optional)
484     If you want to use the `apache', `ascent', `curl', `nginx', or `write_http'
485     plugin.
486     <http://curl.haxx.se/>
487
488   * libdbi (optional)
489     Used by the `dbi' plugin to connect to various databases.
490     <http://libdbi.sourceforge.net/>
491
492   * libesmtp (optional)
493     For the `notify_email' plugin.
494     <http://www.stafford.uklinux.net/libesmtp/>
495
496   * libganglia (optional)
497     Used by the `gmond' plugin to process data received from Ganglia.
498
499   * libgcrypt (optional)
500     Used by the `network' plugin for encryption and authentication.
501
502   * libhal (optional)
503     If present, the uuid plugin will check for UUID from HAL.
504     <http://hal.freedesktop.org/>
505
506   * libiptc (optional)
507     For querying iptables counters.
508     <http://netfilter.org/>
509
510     If not found on the system, a version shipped with this distribution can
511     be used. It requires some Linux headers in /usr/include/linux. You can
512     force the build system to use the shipped version by specifying
513       --with-libiptc=shipped
514     when running the configure script.
515
516   * libjvm (optional)
517     Library that encapsulates the `Java Virtual Machine' (JVM). This library is
518     used by the Java plugin to execute Java bytecode. See “Configuring with
519     libjvm” below.
520
521   * libmemcached (optional)
522     Used by the `memcachec' plugin to connect to a memcache daemon.
523
524   * libmysqlclient (optional)
525     Unsurprisingly used by the `mysql' plugin.
526     <http://dev.mysql.com/>
527
528   * libnatapp (optional)
529     Required for the “netapp” plugin.
530     This library is part of the “Manage ONTAP SDK” published by NetApp.
531
532   * libnetlink (optional)
533     Used, obviously, for the `netlink' plugin.
534     <http://www.linuxfoundation.org/en/Net:Iproute2>
535
536   * libnetsnmp (optional)
537     For the `snmp' plugin.
538     <http://www.net-snmp.org/>
539
540   * libnotify (optional)
541     For the `notify_desktop' plugin.
542     <http://www.galago-project.org/>
543
544   * liboping (optional)
545     Used by the `ping' plugin to send and receive ICMP packets.
546     <http://verplant.org/liboping/>
547
548   * libowcapi (optional)
549     Used by the `onewire' plugin to read values from onewire sensors (or the
550     owserver(1) daemon).
551     <http://www.owfs.org/>
552
553   * libpcap (optional)
554     Used to capture packets by the `dns' plugin.
555     <http://www.tcpdump.org/>
556
557   * libperl (optional)
558     Obviously used by the `perl' plugin. The library has to be compiled with
559     ithread support (introduced in Perl 5.6.0).
560     <http://www.perl.org/>
561
562   * libpq (optional)
563     The PostgreSQL C client library used by the `postgresql' plugin.
564     <http://www.postgresql.org/>
565
566   * libpython (optional)
567     Used by the `python' plugin. Currently, only 2.3 ≦ Python < 3 is supported.
568     <http://www.python.org/>
569
570   * librrd (optional)
571     Used by the `rrdtool' and `rrdcached' plugins. The latter requires RRDtool
572     client support which was added after version 1.3 of RRDtool. Versions 1.0,
573     1.2 and 1.3 are known to work with the `rrdtool' plugin.
574     <http://oss.oetiker.ch/rrdtool/>
575
576   * librt, libsocket, libkstat, libdevinfo (optional)
577     Various standard Solaris libraries which provide system functions.
578     <http://developers.sun.com/solaris/>
579
580   * libsensors (optional)
581     To read from `lm_sensors', see the `sensors' plugin.
582     <http://www.lm-sensors.org/>
583
584   * libstatgrab (optional)
585     Used by various plugins to collect statistics on systems other than Linux
586     and/or Solaris.
587     <http://www.i-scream.org/libstatgrab/>
588
589   * libupsclient/nut (optional)
590     For the `nut' plugin which queries nut's `upsd'.
591     <http://networkupstools.org/>
592
593   * libvirt (optional)
594     Collect statistics from virtual machines.
595     <http://libvirt.org/>
596
597   * libxml2 (optional)
598     Parse XML data. This is needed for the `ascent' and `libvirt' plugins.
599     <http://xmlsoft.org/>
600
601   * libxmms (optional)
602     <http://www.xmms.org/>
603
604   * libyajl (optional)
605     Parse JSON data. This is needed for the `curl_json' plugin.
606     <http://www.lloydforge.org/projects/yajl/>
607
608 Configuring / Compiling / Installing
609 ------------------------------------
610
611   To configure, build and install collectd with the default settings, run
612   `./configure && make && make install'.  For detailed, generic instructions
613   see INSTALL. For a complete list of configure options and their description,
614   run `./configure --help'.
615
616   By default, the configure script will check for all build dependencies and
617   disable all plugins whose requirements cannot be fulfilled (any other plugin
618   will be enabled). To enable a plugin, install missing dependencies (see
619   section `Prerequisites' above) and rerun `configure'. If you specify the
620   `--enable-<plugin>' configure option, the script will fail if the depen-
621   dencies for the specified plugin are not met. In that case you can force the
622   plugin to be built using the `--enable-<plugin>=force' configure option.
623   This will most likely fail though unless you're working in a very unusual
624   setup and you really know what you're doing. If you specify the
625   `--disable-<plugin>' configure option, the plugin will not be built. If you
626   specify the `--enable-all-plugins' or `--disable-all-plugins' configure
627   options, all plugins will be enabled or disabled respectively by default.
628   Explicitly enabling or disabling a plugin overwrites the default for the
629   specified plugin. These options are meant for package maintainers and should
630   not be used in everyday situations.
631
632   By default, collectd will be installed into `/opt/collectd'. You can adjust
633   this setting by specifying the `--prefix' configure option - see INSTALL for
634   details. If you pass DESTDIR=<path> to `make install', <path> will be
635   prefixed to all installation directories. This might be useful when creating
636   packages for collectd.
637
638 Configuring with libjvm
639 -----------------------
640
641   To determine the location of the required files of a Java installation is not
642   an easy task, because the locations vary with your kernel (Linux, SunOS, …)
643   and with your architecture (x86, SPARC, …) and there is no ‘java-config’
644   script we could use. Configuration of the JVM library is therefore a bit
645   tricky.
646
647   The easiest way to use the `--with-java=$JAVA_HOME' option, where
648   `$JAVA_HOME' is usually something like:
649     /usr/lib/jvm/java-1.5.0-sun-1.5.0.14
650
651   The configure script will then use find(1) to look for the following files:
652
653     - jni.h
654     - jni_md.h
655     - libjvm.so
656
657   If found, appropriate CPP-flags and LD-flags are set and the following
658   library checks succeed.
659
660   If this doesn't work for you, you have the possibility to specify CPP-flags,
661   C-flags and LD-flags for the ‘Java’ plugin by hand, using the following three
662   (environment) variables:
663
664     - JAVA_CPPFLAGS
665     - JAVA_CFLAGS
666     - JAVA_LDFLAGS
667
668   For example (shortened for demonstration purposes):
669
670     ./configure JAVA_CPPFLAGS="-I$JAVA_HOME/include -I$JAVA_HOME/include/linux"
671
672   Adding "-ljvm" to the JAVA_LDFLAGS is done automatically, you don't have to
673   do that.
674
675 Crosscompiling
676 --------------
677
678   To compile correctly collectd needs to be able to initialize static
679   variables to NAN (Not A Number). Some C libraries, especially the GNU
680   libc, have a problem with that.
681
682   Luckily, with GCC it's possible to work around that problem: One can define
683   NAN as being (0.0 / 0.0) and `isnan' as `f != f'. However, to test this
684   ``implementation'' the configure script needs to compile and run a short
685   test program. Obviously running a test program when doing a cross-
686   compilation is, well, challenging.
687
688   If you run into this problem, you can use the `--with-nan-emulation'
689   configure option to force the use of this implementation. We can't promise
690   that the compiled binary actually behaves as it should, but since NANs
691   are likely never passed to the libm you have a good chance to be lucky.
692
693   Likewise, collectd needs to know the layout of doubles in memory, in order
694   to craft uniform network packets over different architectures. For this, it
695   needs to know how to convert doubles into the memory layout used by x86. The
696   configure script tries to figure this out by compiling and running a few
697   small test programs. This is of course not possible when cross-compiling.
698   You can use the `--with-fp-layout' option to tell the configure script which
699   conversion method to assume. Valid arguments are:
700
701     * `nothing'    (12345678 -> 12345678)
702     * `endianflip' (12345678 -> 87654321)
703     * `intswap'    (12345678 -> 56781234)
704
705
706 Contact
707 -------
708
709   For questions, bug reports, development information and basically all other
710   concerns please send an email to collectd's mailing list at
711   <collectd at verplant.org>.
712
713   For live discussion and more personal contact visit us in IRC, we're in
714   channel #collectd on freenode.
715
716
717 Author
718 ------
719
720   Florian octo Forster <octo at verplant.org>,
721   Sebastian tokkee Harl <sh at tokkee.org>,
722   and many contributors (see `AUTHORS').
723
724   Please send bug reports and patches to the mailing list, see `Contact'
725   above.
726