Code

exec plugin: Updated the documentation and sample configfile.
[collectd.git] / src / collectd.pod
1 =head1 NAME
3 collectd - System statistics collection daemon
5 =head1 SYNOPSIS
7 collectd I<[options]>
9 =head1 DESCRIPTION
11 collectd is a daemon that collects various system statistics periodically and
12 stores them into RRD-files. Which data is collected depends on compile-time
13 settings. The following features may be available:
15 =over 4
17 =item
19 Apache and lighttpd server statistics (I<apache>)
21 =item
23 Apple hardware sensors (I<apple_sensors>, Darwin only)
25 =item
27 Battery status (I<battery>)
29 =item
31 CPU utilization (I<cpu>)
33 =item
35 Mountpoint usage (I<df>)
37 =item
39 Disk and partition usage/throughput (I<disk>)
41 =item
43 DNS traffic (I<dns>)
45 =item
47 Email usage (I<email>)
49 =item
51 Harddisk temperatures (I<hddtemp>)
53 =item
55 Irq (I<irq>)
57 =item
59 System load averages (I<load>)
61 =item
63 Motherboard monitor (I<mbmon>)
65 =item
67 Memory usage (I<memory>)
69 =item
71 MySQL statistics (I<mysql>)
73 =item
75 NFS utilization (I<nfs>, Linux only)
77 =item
79 Network latency (I<ping>)
81 =item
83 Number of processes (I<processes>, Linux only)
85 =item
87 lm_sensors information (I<sensors>, Linux only)
89 =item
91 Serial port traffic (I<serial>, Linux only)
93 =item
95 Swap usage (I<swap>)
97 =item
99 Tape drive usage (I<tape>, Solaris only)
101 =item
103 Network traffic (I<traffic>)
105 =item
107 Number of users logged into the system (I<users>)
109 =item
111 System ressources used by VServers (I<vserver>)
113 =item
115 Wireless network stats (I<wireless>)
117 =back
119 =head1 OPTIONS
121 =over 4
123 =item B<-C> I<E<lt>config-fileE<gt>>
125 Specify an alternative config file. This is the place to go when you wish to
126 change B<collectd>'s behavior. The path may be relative to the current working
127 directory.
129 =item B<-P> I<E<lt>pid-fileE<gt>>
131 Specify an alternative pid file. This overwrites any settings in the config 
132 file. This is thought for init-scripts that require the PID-file in a certain
133 directory to work correctly. For everyday-usage use the B<PIDFile>
134 config-option.
136 =item B<-f>
138 Don't fork to the background. I<collectd> will also B<not> close standard file
139 descriptors, detach from the session nor write a pid file. This is mainly
140 thought for 'supervisioning' init replacements such as I<runit>.
142 =item B<-h>
144 Output usage information and exit.
146 =back
148 =head1 MODES
150 collectd can operate in four different operating modes. The modes are described
151 below.
153 The simplest mode is the so called B<local mode>. Data is collected locally and
154 written in RRD files that reside in I<DataDir>. This is the default mode when
155 collectd is linked against C<librrd>.
157 The modes B<client mode> and B<server mode> are used to send data over a
158 network and receive it again.
160 In B<client mode> the daemon collects the data locally and sends its results
161 to one or more network addresses. No RRD files are written locally in this
162 case. If collectd is not linked against C<librrd> this is the default mode.
164 If started in B<server mode> the daemon will listen on one or more interfaces
165 and write the data it receives to RRD files. No data is collected locally.
167 In the last mode, B<log mode>, data is collected locally and written in
168 text files that reside in I<DataDir>.
170 Please refer to L<collectd.conf(5)> for the configuration options and default
171 values.
173 =head1 SPECIAL PLUGINS
175 =head2 apache
177 This module connects to an Apache or lighttpd webserver and expects the output
178 produced by B<mod_status.c>. If requires B<libcurl> to set up the HTTP
179 connection and issue the request(s). The following is a sample config for the
180 Apache webserver. Under Apache, the use of C<ExtendedStatus on> is mandatory.
182   ExtendedStatus on
183   <IfModule mod_status.c>
184     <Location /mod_status>
185       SetHandler server-status
186     </Location>
187   </IfModule>
189 This plugin requires further configuration. Please read L<collectd.conf(5)>.
191 =head2 cpufreq
193 This module reads F</sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq> (for
194 the first CPU installed) to get the current CPU frequency. If this file does
195 not exist make sure B<cpufreqd> (L<http://cpufreqd.sourceforge.net/>) or a
196 similar tool is installed and an "cpu governor" (that's kernel module) is
197 loaded.
199 =head2 email
201 This plugin collects data indirectly by providing a UNIX socket that external
202 programs can connect to. A simple line based protocol is used to communicate
203 with the plugin:
205 E-Mail type (e.g. "ham", "spam", "virus", ...) and size (bytes):
207   e:<type>:<size>
209 If C<size> is less than or equal to zero, C<size> is ignored.
211 Spam score:
213   s:<value>
215 Successful spam checks (e.g. "BAYES_99", "SUBJECT_DRUG_GAP_C", ...):
217   c:<type1>[,<type2>,...]
219 Each line is limited to 256 characters (including the newline character). 
220 Longer lines will be ignored.
222 =head2 exec
224 The C<exec> plugin forks of an executable and reads back values that it writes
225 to C<STDOUT>. The executable is forked kind of as L<init> does: It is forked
226 once and not again until it exits. If it exited, it will be forked again after
227 at most I<Interval> seconds. It is perfectly legal for the executable to run
228 for a long time and continuously write values to C<STDOUT>.
230 The forked executable is expected to print values to C<STDOUT>. The expected
231 format is as follows:
233 =over 4
235 =item
237 Each line beginning with a C<#> (hash mark) is ignored.
239 =item
241 Any other line must be of the form C<I<type>,I<type-instance>,I<value>>, where
242 I<type> is either B<counter> or B<gauge>, I<type-instance> may not contain
243 C<,> (comma), C</> (slash) and C<\0> (null byte) and I<value> is either an
244 integer (if I<type> is B<counter>) or a floating-point number (if I<type> is
245 B<gauge>).
247 =back
249 The values are always considered to be "fresh", i.E<nbsp>e. the time is set to
250 "now".
252 When collectd exits it sends a B<SIGTERM> to all still running
253 child-processes upon which they have to quit.
255 =head2 mysql
257 Requires B<mysqlclient> to be installed. It connects to the database when
258 started and keeps the connection up as long as possible. When the connection is
259 interrupted for whatever reason it will try to re-connect. The syslog will
260 contain loud complaints in case anything goes wrong.
262 This plugin issues C<SHOW STATUS> and evaluates C<Bytes_{received,sent}>,
263 C<Com_*> and C<Handler_*> which correspond to F<traffic-mysql.rrd>,
264 F<mysql_commands-*.rrd> and F<mysql_handler-*.rrd>. Also, the values of
265 C<Qcache_*> are put in F<mysql_qcache.rrd> and values of C<Threads_*> are put
266 in F<mysql_threads.rrd>. Please refer to the B<MySQL reference manual>,
267 I<5.2.4. Server Status Variables> for an explanation of these values.
269 =head2 sensors
271 The B<sensors> module uses lm_sensors to retrieve sensor-values. This means
272 that all the needed modules have to be loaded and lm_sensors has to be
273 configured (most likely by editing F</etc/sensors.conf>. Read
274 L<sensors.conf(5)> for details.
276 The B<lm_sensors> homepage can be found at
277 L<http://secure.netroedge.com/~lm78/>.
279 =head2 mbmon
281 The B<mbmon> module uses mbmon to retrieve temperature, voltage, etc.
283 collectd connects to B<localhost> (127.0.0.1), port B<411/tcp>.
284 The B<Host> and B<Port> options can be used to change these
285 default values. See L<collectd.conf(5)> for details. C<mbmon> has to be
286 running to work correctly. If C<mbmon> is not running timeouts may appear
287 which may interfere with other statistics..
289 C<mbmon> must be run with the -r option ("print TAG and Value format");
290 Debian's /etc/init.d/mbmon script already does this, other people
291 will need to ensure that this is the case.
293 =head2 hddtemp
295 To get values from B<hddtemp> collectd connects to B<localhost> (127.0.0.1),
296 port B<7634/tcp>. The B<Host> and B<Port> options can be used to change these
297 default values. See L<collectd.conf(5)> for details. C<hddtemp> has to be
298 running to work correctly. If C<hddtemp> is not running timeouts may appear
299 which may interfere with other statistics..
301 The B<hddtemp> homepage can be found at
302 L<http://www.guzu.net/linux/hddtemp.php>.
304 =head2 vserver
306 B<VServer> support is only available for Linux. It cannot yet be found in a 
307 vanilla kernel, though. To make use of this plugin you need a kernel that has 
308 B<VServer> support built in, i.e. you need to apply the patches and compile 
309 your own kernel, which will then provide the /proc/virtual filesystem that is
310 required by this plugin.
312 The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
314 =head1 RRD FILES
316 The RRD files are created automatically. The size of the RRAs depend on the
317 compile time settings of I<step> and I<width>. With the default values (I<step>
318 = B<10>, I<width> = B<1200>) the following RRAs are created:
320   RRA:AVERAGE:0.1:1:8640
321   RRA:AVERAGE:0.1:50:1210
322   RRA:AVERAGE:0.1:223:1202
323   RRA:AVERAGE:0.1:2635:1201
324   RRA:MIN:0.1:1:8640
325   RRA:MIN:0.1:50:1210
326   RRA:MIN:0.1:223:1202
327   RRA:MIN:0.1:2635:1201
328   RRA:MAX:0.1:1:8640
329   RRA:MAX:0.1:50:1210
330   RRA:MAX:0.1:223:1202
331   RRA:MAX:0.1:2635:1201
333 By default collectd uses a 10 second I<step>. Thus the RRAs contain the
334 following timespans. If you've changed the I<step> at compile time you will
335 have calculate resolution and timespan yourself.
337   PDP per CDP |  Resolution  | Data points | Timespan
338   ------------+--------------+-------------+---------
339             1 | 10.0 seconds !        8640 ! 1 day
340            50 |  8.3 minutes |        1210 | 1 week
341           223 | 37.2 minutes |        1202 | 1 month
342          2635 |  7.3 hours   |        1201 | 1 year
344 The DS'es depend on the module creating the RRD files:
346 =over 4
348 =item Apache traffic (F<apache/apache_bytes.rrd>)
350   DS:count:COUNTER:HEARTBEAT:0:134217728
352 =item Apache requests (F<apache/apache_requests.rrd>)
354   DS:count:COUNTER:HEARTBEAT:0:1048576
356 =item Apache scoreboard (F<apache/apache_scoreboard-I<E<lt>nameE<gt>>.rrd>)
358   DS:count:GAUGE:HEARTBEAT:0:U
360 =item Apple temperature sensor (F<apple_sensors/temperature-I<E<lt>nameE<gt>>.rrd>)
362   DS:value:GAUGE:HEARTBEAT:U:U
364 =item Apple fanspeed sensor (F<apple_sensors/fanspeed-I<E<lt>nameE<gt>>.rrd>)
366   DS:value:GAUGE:HEARTBEAT:U:U
368 =item Battery charge (F<battery-I<E<lt>nameE<gt>>/charge.rrd>)
370   DS:charge:GAUGE:HEARTBEAT:0:U
372 =item Battery current (F<battery-I<E<lt>nameE<gt>>/current.rrd>)
374   DS:current:GAUGE:HEARTBEAT:U:U
376 =item Battery voltage (F<battery-I<E<lt>nameE<gt>>/voltage.rrd>)
378   DS:voltage:GAUGE:HEARTBEAT:U:U
380 =item CPU (F<cpu-I<E<lt>numE<gt>>.rrd>)
382   DS:user:COUNTER:HEARTBEAT:0:100
383   DS:nice:COUNTER:HEARTBEAT:0:100
384   DS:syst:COUNTER:HEARTBEAT:0:100
385   DS:idle:COUNTER:HEARTBEAT:0:100
386   DS:wait:COUNTER:HEARTBEAT:0:100
388 =item CPU frequency (F<cpufreq-I<E<lt>numE<gt>>.rrd>)
390   DS:value:GAUGE:HEARTBEAT:0:U
392 =item Mountpoints (F<df-I<E<lt>pathE<gt>>.rrd>)
394   DS:used:GAUGE:HEARTBEAT:0:U
395   DS:free:GAUGE:HEARTBEAT:0:U
397 =item Diskstats (F<disk-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
399   DS:rcount:COUNTER:HEARTBEAT:0:U
400   DS:rmerged:COUNTER:HEARTBEAT:0:U
401   DS:rbytes:COUNTER:HEARTBEAT:0:U
402   DS:rtime:COUNTER:HEARTBEAT:0:U
403   DS:wcount:COUNTER:HEARTBEAT:0:U
404   DS:wmerged:COUNTER:HEARTBEAT:0:U
405   DS:wbytes:COUNTER:HEARTBEAT:0:U
406   DS:wtime:COUNTER:HEARTBEAT:0:U
408 =item Diskstats (F<partition-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
410   DS:rcount:COUNTER:HEARTBEAT:0:U
411   DS:rbytes:COUNTER:HEARTBEAT:0:U
412   DS:wcount:COUNTER:HEARTBEAT:0:U
413   DS:wbytes:COUNTER:HEARTBEAT:0:U
415 =item E-Mail count (F<email/email-I<E<lt>typeE<gt>>.rrd>)
417   DS:count:GAUGE:HEARTBEAT:0:U
419 =item E-Mail size (F<email/email_size-I<E<lt>typeE<gt>>.rrd>)
421   DS:size:GAUGE:HEARTBEAT:0:U
423 =item HDD Temperature (F<hddtemp-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
425   DS:value:GAUGE:HEARTBEAT:U:U
427 =item Irq (F<irq-I<E<lt>irqnumberE<gt>>.rrd>)
429   DS:value:COUNTER:HEARTBEAT:0:65535
431 =item System load (F<load.rrd>)
433   DS:shortterm:GAUGE:HEARTBEAT:0:100
434   DS:midterm:GAUGE:HEARTBEAT:0:100
435   DS:longterm:GAUGE:HEARTBEAT:0:100
437 =item Memory usage (F<memory.rrd>)
439   DS:used:GAUGE:HEARTBEAT:0:9223372036854775807
440   DS:free:GAUGE:HEARTBEAT:0:9223372036854775807
441   DS:buffers:GAUGE:HEARTBEAT:0:9223372036854775807
442   DS:cached:GAUGE:HEARTBEAT:0:9223372036854775807
444 =item MySQL commands and handlers (F<mysql_commands-I<E<lt>commandE<gt>>.rrd> and F<mysql_handler-I<E<lt>handlerE<gt>>.rrd>)
446   DS:value:COUNTER:HEARTBEAT:0:U
448 =item MySQL query cache (F<mysql_qcache.rrd>)
450   DS:hits:COUNTER:HEARTBEAT:0:U
451   DS:inserts:COUNTER:HEARTBEAT:0:U
452   DS:not_cached:COUNTER:HEARTBEAT:0:U
453   DS:lowmem_prunes:COUNTER:HEARTBEAT:0:U
454   DS:queries_in_cache:GAUGE:HEARTBEAT:0:U
456 =item MySQL threads (F<mysql_threads.rrd>)
458   DS:running:GAUGE:HEARTBEAT:0:U
459   DS:connected:GAUGE:HEARTBEAT:0:U
460   DS:cached:GAUGE:HEARTBEAT:0:U
461   DS:created:COUNTER:HEARTBEAT:0:U
463 =item NFSv2 Procedures (F<nfs2_procedures-I<(client|server)>.rrd>)
465   DS:null:COUNTER:HEARTBEAT:0:U
466   DS:getattr:COUNTER:HEARTBEAT:0:U
467   DS:setattr:COUNTER:HEARTBEAT:0:U
468   DS:root:COUNTER:HEARTBEAT:0:U
469   DS:lookup:COUNTER:HEARTBEAT:0:U
470   DS:readlink:COUNTER:HEARTBEAT:0:U
471   DS:read:COUNTER:HEARTBEAT:0:U
472   DS:wrcache:COUNTER:HEARTBEAT:0:U
473   DS:write:COUNTER:HEARTBEAT:0:U
474   DS:create:COUNTER:HEARTBEAT:0:U
475   DS:remove:COUNTER:HEARTBEAT:0:U
476   DS:rename:COUNTER:HEARTBEAT:0:U
477   DS:link:COUNTER:HEARTBEAT:0:U
478   DS:symlink:COUNTER:HEARTBEAT:0:U
479   DS:mkdir:COUNTER:HEARTBEAT:0:U
480   DS:rmdir:COUNTER:HEARTBEAT:0:U
481   DS:readdir:COUNTER:HEARTBEAT:0:U
482   DS:fsstat:COUNTER:HEARTBEAT:0:U
484 =item NFSv3 Procedures (F<nfs3_procedures-I<(client|server)>.rrd>)
486   DS:null:COUNTER:HEARTBEAT:0:U
487   DS:getattr:COUNTER:HEARTBEAT:0:U
488   DS:setattr:COUNTER:HEARTBEAT:0:U
489   DS:lookup:COUNTER:HEARTBEAT:0:U
490   DS:access:COUNTER:HEARTBEAT:0:U
491   DS:readlink:COUNTER:HEARTBEAT:0:U
492   DS:read:COUNTER:HEARTBEAT:0:U
493   DS:write:COUNTER:HEARTBEAT:0:U
494   DS:create:COUNTER:HEARTBEAT:0:U
495   DS:mkdir:COUNTER:HEARTBEAT:0:U
496   DS:symlink:COUNTER:HEARTBEAT:0:U
497   DS:mknod:COUNTER:HEARTBEAT:0:U
498   DS:remove:COUNTER:HEARTBEAT:0:U
499   DS:rmdir:COUNTER:HEARTBEAT:0:U
500   DS:rename:COUNTER:HEARTBEAT:0:U
501   DS:link:COUNTER:HEARTBEAT:0:U
502   DS:readdir:COUNTER:HEARTBEAT:0:U
503   DS:readdirplus:COUNTER:HEARTBEAT:0:U
504   DS:fsstat:COUNTER:HEARTBEAT:0:U
505   DS:fsinfo:COUNTER:HEARTBEAT:0:U
506   DS:pathconf:COUNTER:HEARTBEAT:0:U
507   DS:commit:COUNTER:HEARTBEAT:0:U
509 =item Network latency / Ping (F<ping-I<E<lt>hostnameE<gt>>.rrd>)
511   DS:ping:GAUGE:HEARTBEAT:0:65535
513 =item Processes (F<processes.rrd>)
515   DS:running:GAUGE:HEARTBEAT:0:65535
516   DS:sleeping:GAUGE:HEARTBEAT:0:65535
517   DS:zombies:GAUGE:HEARTBEAT:0:65535
518   DS:stopped:GAUGE:HEARTBEAT:0:65535
519   DS:paging:GAUGE:HEARTBEAT:0:65535
520   DS:blocked:GAUGE:HEARTBEAT:0:65535
522 =item lm_sensors fanspeed sensor (F<sensors-I<E<lt>instE<gt>>.rrd> or F<lm_sensors-I<E<lt>chipE<gt>>/fanspeed-I<E<lt>instE<gt>>.rrd>)
524   DS:value:GAUGE:HEARTBEAT:U:U
526 =item lm_sensors temperature sensor (F<sensors-I<E<lt>instE<gt>>.rrd> or F<lm_sensors-I<E<lt>chipE<gt>>/temperature-I<E<lt>instE<gt>>.rrd>)
528   DS:value:GAUGE:HEARTBEAT:U:U
530 =item lm_sensors voltage sensor (F<sensors-I<E<lt>instE<gt>>.rrd> or F<lm_sensors-I<E<lt>chipE<gt>>/voltage-I<E<lt>instE<gt>>.rrd>)
532   DS:voltage:GAUGE:HEARTBEAT:U:U
534 =item Serial port traffic (F<serial-I<E<lt>numE<gt>>.rrd>)
536   DS:incoming:COUNTER:HEARTBEAT:0:U
537   DS:outgoing:COUNTER:HEARTBEAT:0:U
539 =item Spam score (F<email/spam_score.rrd>)
541   DS:score:GAUGE:HEARTBEAT:0:U
543 =item Spam checks (F<email/spam_check-I<E<lt>typeE<gt>>.rrd>)
545   DS:hits:GAUGE:HEARTBEAT:0:U
547 =item Swap usage (F<swap.rrd>)
549   DS:used:GAUGE:HEARTBEAT:0:1099511627776
550   DS:free:GAUGE:HEARTBEAT:0:1099511627776
551   DS:cached:GAUGE:HEARTBEAT:0:1099511627776
552   DS:resv:GAUGE:HEARTBEAT:0:1099511627776
554 =item Tape drive usage (F<tape-I<E<lt>nameE<gt>>.rrd>)
556   DS:rcount:COUNTER:HEARTBEAT:0:
557   DS:rmerged:COUNTER:HEARTBEAT:0:U
558   DS:rbytes:COUNTER:HEARTBEAT:0:U
559   DS:rtime:COUNTER:HEARTBEAT:0:U
560   DS:wcount:COUNTER:HEARTBEAT:0:U
561   DS:wmerged:COUNTER:HEARTBEAT:0:U
562   DS:wbytes:COUNTER:HEARTBEAT:0:U
563   DS:wtime:COUNTER:HEARTBEAT:0:U
565 =item Network traffic (F<traffic-I<E<lt>interfaceE<gt>>.rrd>)
567   DS:incoming:COUNTER:HEARTBEAT:0:U
568   DS:outgoing:COUNTER:HEARTBEAT:0:U
570 =item Interface packets (F<if_packets-I<E<lt>interfaceE<gt>>.rrd>)
572   DS:rx:COUNTER:HEARTBEAT:0:U
573   DS:tx:COUNTER:HEARTBEAT:0:U
575 =item Interface errors (F<if_errors-I<E<lt>interfaceE<gt>>.rrd>)
577   DS:rx:COUNTER:HEARTBEAT:0:U
578   DS:tx:COUNTER:HEARTBEAT:0:U
580 =item Users (F<users.rrd>)
582   DS:users:GAUGE:HEARTBEAT:0:65535
584 =item VServer load (F<vserver-I<E<lt>xidE<gt>>/load.rrd>)
586   DS:shortterm:GAUGE:HEARTBEAT:0:100
587   DS:midterm:GAUGE:HEARTBEAT:0:100
588   DS:longterm:GAUGE:HEARTBEAT:0:100
590 =item VServer threads (F<vserver-I<E<lt>xidE<gt>>/threads.rrd>)
592   DS:total:GAUGE:HEARTBEAT:0:65535
593   DS:running:GAUGE:HEARTBEAT:0:65535
594   DS:uninterruptible:GAUGE:HEARTBEAT:0:65535
595   DS:onhold:GAUGE:HEARTBEAT:0:65535
597 =item VServer network traffic (F<vserver-I<E<lt>xidE<gt>>/traffic-I<E<lt>nameE<gt>>.rrd>)
599   DS:incoming:COUNTER:HEARTBEAT:0:9223372036854775807
600   DS:outgoing:COUNTER:HEARTBEAT:0:9223372036854775807
601   DS:failed:COUNTER:HEARTBEAT:0:9223372036854775807
603 =item VServer processes (F<vserver-I<E<lt>xidE<gt>>/vs_processes.rrd>)
605   DS:total:GAUGE:HEARTBEAT:0:65535
607 =item VServer memory usage (F<vserver-I<E<lt>xidE<gt>>/vs_memory.rrd>)
609   DS:vm:GAUGE:HEARTBEAT:0:9223372036854775807
610   DS:vml:GAUGE:HEARTBEAT:0:9223372036854775807
611   DS:rss:GAUGE:HEARTBEAT:0:9223372036854775807
612   DS:anon:GAUGE:HEARTBEAT:0:9223372036854775807
614 =item Wireless link quality (F<wireless-I<E<lt>interfaceE<gt>>.rrd>)
616   DS:quality:GAUGE:HEARTBEAT:0:U
617   DS:power:GAUGE:HEARTBEAT:U:0
618   DS:noise:GAUGE:HEARTBEAT:U:0
620 =back
622 =head1 SEE ALSO
624 L<collectd.conf(5)>, L<rrdtool(1)>, L<sensors(1)>, L<hddtemp(8)>,
625 L<mbmon(1)>,
626 L<kstat(3KSTAT)>
628 =head1 AUTHOR
630 Florian Forster E<lt>octo@verplant.orgE<gt>
632 =cut