Code

email plugin: Ignore size if it less than or equal to zero.
[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 server stats (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 System load averages (I<load>)
57 =item
59 Motherboard monitor (I<mbmon>)
61 =item
63 Memory usage (I<memory>)
65 =item
67 MySQL statistics (I<mysql>)
69 =item
71 NFS utilization (I<nfs>, Linux only)
73 =item
75 Network latency (I<ping>)
77 =item
79 Number of processes (I<processes>, Linux only)
81 =item
83 lm_sensors information (I<sensors>, Linux only)
85 =item
87 Serial port traffic (I<serial>, Linux only)
89 =item
91 Swap usage (I<swap>)
93 =item
95 Tape drive usage (I<tape>, Solaris only)
97 =item
99 Network traffic (I<traffic>)
101 =item
103 Number of users logged into the system (I<users>)
105 =item
107 System ressources used by VServers (I<vserver>)
109 =item
111 Wireless network stats (I<wireless>)
113 =back
115 =head1 OPTIONS
117 =over 4
119 =item B<-C> I<E<lt>config-fileE<gt>>
121 Specify an alternative config file. This is the place to go when you wish to
122 change B<collectd>'s behavior. The path may be relative to the current working
123 directory.
125 =item B<-P> I<E<lt>pid-fileE<gt>>
127 Specify an alternative pid file. This overwrites any settings in the config 
128 file. This is thought for init-scripts that require the PID-file in a certain
129 directory to work correctly. For everyday-usage use the B<PIDFile>
130 config-option.
132 =item B<-f>
134 Don't fork to the background. I<collectd> will also B<not> close standard file
135 descriptors, detach from the session nor write a pid file. This is mainly
136 thought for 'supervisioning' init replacements such as I<runit>.
138 =item B<-h>
140 Output usage information and exit.
142 =back
144 =head1 MODES
146 collectd can operate in four different operating modes. The modes are described
147 below.
149 The simplest mode is the so called B<local mode>. Data is collected locally and
150 written in RRD files that reside in I<DataDir>. This is the default mode when
151 collectd is linked against C<librrd>.
153 The modes B<client mode> and B<server mode> are used to send data over a
154 network and receive it again.
156 In B<client mode> the daemon collects the data locally and sends its results
157 to one or more network addresses. No RRD files are written locally in this
158 case. If collectd is not linked against C<librrd> this is the default mode.
160 If started in B<server mode> the daemon will listen on one or more interfaces
161 and write the data it receives to RRD files. No data is collected locally.
163 In the last mode, B<log mode>, data is collected locally and written in
164 text files that reside in I<DataDir>.
166 Please refer to L<collectd.conf(5)> for the configuration options and default
167 values.
169 =head1 SPECIAL PLUGINS
171 =head2 apache
173 This module connects to an Apache webserver and expects the output produced by
174 B<mod_status.c>. If requires B<libcurl> to set up the HTTP connection and issue
175 the request(s). The following is a sample config for the Apache webserver. The
176 use of C<ExtendedStatus on> is mandatory.
178   ExtendedStatus on
179   <IfModule mod_status.c>
180     <Location /mod_status>
181       SetHandler server-status
182     </Location>
183   </IfModule>
185 This plugin requires further configuration. Please read L<collectd.conf(5)>.
187 =head2 cpufreq
189 This module reads F</sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq> (for
190 the first CPU installed) to get the current CPU frequency. If this file does
191 not exist make sure B<cpufreqd> (L<http://cpufreqd.sourceforge.net/>) or a
192 similar tool is installed and an "cpu governor" (that's kernel module) is
193 loaded.
195 =head2 email
197 This plugin collects data indirectly by providing a UNIX socket that external
198 programs can connect to. A simple line based protocol is used to communicate
199 with the plugin:
201 E-Mail type (e.g. "ham", "spam", "virus", ...) and size (bytes):
203   e:<type>:<size>
205 If C<size> is less than or equal to zero, C<size> is ignored.
207 Spam score:
209   s:<value>
211 Successful spam checks (e.g. "BAYES_99", "SUBJECT_DRUG_GAP_C", ...):
213   c:<type1>[,<type2>,...]
215 Each line is limited to 256 characters (including the newline character). 
216 Longer lines will be ignored.
218 =head2 mysql
220 Requires B<mysqlclient> to be installed. It connects to the database when
221 started and keeps the connection up as long as possible. When the connection is
222 interrupted for whatever reason it will try to re-connect. The syslog will
223 contain loud complaints in case anything goes wrong.
225 This plugin issues C<SHOW STATUS> and evaluates C<Bytes_{received,sent}>,
226 C<Com_*> and C<Handler_*> which correspond to F<traffic-mysql.rrd>,
227 F<mysql_commands-*.rrd> and F<mysql_handler-*.rrd>. Also, the values of
228 C<Qcache_*> are put in F<mysql_qcache.rrd> and values of C<Threads_*> are put
229 in F<mysql_threads.rrd>. Please refer to the B<MySQL reference manual>,
230 I<5.2.4. Server Status Variables> for an explanation of these values.
232 =head2 sensors
234 The B<sensors> module uses lm_sensors to retrieve sensor-values. This means
235 that all the needed modules have to be loaded and lm_sensors has to be
236 configured (most likely by editing F</etc/sensors.conf>. Read
237 L<sensors.conf(5)> for details.
239 The B<lm_sensors> homepage can be found at
240 L<http://secure.netroedge.com/~lm78/>.
242 =head2 mbmon
244 The B<mbmon> module uses mbmon to retrieve temperature, voltage, etc.
246 collectd connects to B<localhost> (127.0.0.1), port B<411/tcp>.
247 The B<Host> and B<Port> options can be used to change these
248 default values. See L<collectd.conf(5)> for details. C<mbmon> has to be
249 running to work correctly. If C<mbmon> is not running timeouts may appear
250 which may interfere with other statistics..
252 C<mbmon> must be run with the -r option ("print TAG and Value format");
253 Debian's /etc/init.d/mbmon script already does this, other people
254 will need to ensure that this is the case.
256 =head2 hddtemp
258 To get values from B<hddtemp> collectd connects to B<localhost> (127.0.0.1),
259 port B<7634/tcp>. The B<Host> and B<Port> options can be used to change these
260 default values. See L<collectd.conf(5)> for details. C<hddtemp> has to be
261 running to work correctly. If C<hddtemp> is not running timeouts may appear
262 which may interfere with other statistics..
264 The B<hddtemp> homepage can be found at
265 L<http://www.guzu.net/linux/hddtemp.php>.
267 =head2 vserver
269 B<VServer> support is only available for Linux. It cannot yet be found in a 
270 vanilla kernel, though. To make use of this plugin you need a kernel that has 
271 B<VServer> support built in, i.e. you need to apply the patches and compile 
272 your own kernel, which will then provide the /proc/virtual filesystem that is
273 required by this plugin.
275 The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
277 =head1 RRD FILES
279 The RRD files are created automatically. The size of the RRAs depend on the
280 compile time settings of I<step> and I<width>. With the default values (I<step>
281 = B<10>, I<width> = B<1200>) the following RRAs are created:
283   RRA:AVERAGE:0.1:1:8640
284   RRA:AVERAGE:0.1:50:1210
285   RRA:AVERAGE:0.1:223:1202
286   RRA:AVERAGE:0.1:2635:1201
287   RRA:MIN:0.1:1:8640
288   RRA:MIN:0.1:50:1210
289   RRA:MIN:0.1:223:1202
290   RRA:MIN:0.1:2635:1201
291   RRA:MAX:0.1:1:8640
292   RRA:MAX:0.1:50:1210
293   RRA:MAX:0.1:223:1202
294   RRA:MAX:0.1:2635:1201
296 By default collectd uses a 10 second I<step>. Thus the RRAs contain the
297 following timespans. If you've changed the I<step> at compile time you will
298 have calculate resolution and timespan yourself.
300   PDP per CDP |  Resolution  | Data points | Timespan
301   ------------+--------------+-------------+---------
302             1 | 10.0 seconds !        8640 ! 1 day
303            50 |  8.3 minutes |        1210 | 1 week
304           223 | 37.2 minutes |        1202 | 1 month
305          2635 |  7.3 hours   |        1201 | 1 year
307 The DS'es depend on the module creating the RRD files:
309 =over 4
311 =item Apache traffic (F<apache/apache_bytes.rrd>)
313   DS:count:COUNTER:HEARTBEAT:0:134217728
315 =item Apache requests (F<apache/apache_requests.rrd>)
317   DS:count:COUNTER:HEARTBEAT:0:1048576
319 =item Apache scoreboard (F<apache/apache_scoreboard-I<E<lt>nameE<gt>>.rrd>)
321   DS:count:GAUGE:HEARTBEAT:0:U
323 =item Apple temperature sensor (F<apple_sensors/temperature-I<E<lt>nameE<gt>>.rrd>)
325   DS:value:GAUGE:HEARTBEAT:U:U
327 =item Apple fanspeed sensor (F<apple_sensors/fanspeed-I<E<lt>nameE<gt>>.rrd>)
329   DS:value:GAUGE:HEARTBEAT:U:U
331 =item Battery charge (F<battery-I<E<lt>nameE<gt>>/charge.rrd>)
333   DS:charge:GAUGE:HEARTBEAT:0:U
335 =item Battery current (F<battery-I<E<lt>nameE<gt>>/current.rrd>)
337   DS:current:GAUGE:HEARTBEAT:U:U
339 =item Battery voltage (F<battery-I<E<lt>nameE<gt>>/voltage.rrd>)
341   DS:voltage:GAUGE:HEARTBEAT:U:U
343 =item CPU (F<cpu-I<E<lt>numE<gt>>.rrd>)
345   DS:user:COUNTER:HEARTBEAT:0:100
346   DS:nice:COUNTER:HEARTBEAT:0:100
347   DS:syst:COUNTER:HEARTBEAT:0:100
348   DS:idle:COUNTER:HEARTBEAT:0:100
349   DS:wait:COUNTER:HEARTBEAT:0:100
351 =item CPU frequency (F<cpufreq-I<E<lt>numE<gt>>.rrd>)
353   DS:value:GAUGE:HEARTBEAT:0:U
355 =item Mountpoints (F<df-I<E<lt>pathE<gt>>.rrd>)
357   DS:used:GAUGE:HEARTBEAT:0:U
358   DS:free:GAUGE:HEARTBEAT:0:U
360 =item Diskstats (F<disk-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
362   DS:rcount:COUNTER:HEARTBEAT:0:U
363   DS:rmerged:COUNTER:HEARTBEAT:0:U
364   DS:rbytes:COUNTER:HEARTBEAT:0:U
365   DS:rtime:COUNTER:HEARTBEAT:0:U
366   DS:wcount:COUNTER:HEARTBEAT:0:U
367   DS:wmerged:COUNTER:HEARTBEAT:0:U
368   DS:wbytes:COUNTER:HEARTBEAT:0:U
369   DS:wtime:COUNTER:HEARTBEAT:0:U
371 =item Diskstats (F<partition-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
373   DS:rcount:COUNTER:HEARTBEAT:0:U
374   DS:rbytes:COUNTER:HEARTBEAT:0:U
375   DS:wcount:COUNTER:HEARTBEAT:0:U
376   DS:wbytes:COUNTER:HEARTBEAT:0:U
378 =item E-Mail count (F<email/email-I<E<lt>typeE<gt>>.rrd>)
380   DS:count:GAUGE:HEARTBEAT:0:U
382 =item E-Mail size (F<email/email_size-I<E<lt>typeE<gt>>.rrd>)
384   DS:size:GAUGE:HEARTBEAT:0:U
386 =item HDD Temperature (F<hddtemp-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
388   DS:value:GAUGE:HEARTBEAT:U:U
390 =item System load (F<load.rrd>)
392   DS:shortterm:GAUGE:HEARTBEAT:0:100
393   DS:midterm:GAUGE:HEARTBEAT:0:100
394   DS:longterm:GAUGE:HEARTBEAT:0:100
396 =item Memory usage (F<memory.rrd>)
398   DS:used:GAUGE:HEARTBEAT:0:9223372036854775807
399   DS:free:GAUGE:HEARTBEAT:0:9223372036854775807
400   DS:buffers:GAUGE:HEARTBEAT:0:9223372036854775807
401   DS:cached:GAUGE:HEARTBEAT:0:9223372036854775807
403 =item MySQL commands and handlers (F<mysql_commands-I<E<lt>commandE<gt>>.rrd> and F<mysql_handler-I<E<lt>handlerE<gt>>.rrd>)
405   DS:value:COUNTER:HEARTBEAT:0:U
407 =item MySQL query cache (F<mysql_qcache.rrd>)
409   DS:hits:COUNTER:HEARTBEAT:0:U
410   DS:inserts:COUNTER:HEARTBEAT:0:U
411   DS:not_cached:COUNTER:HEARTBEAT:0:U
412   DS:lowmem_prunes:COUNTER:HEARTBEAT:0:U
413   DS:queries_in_cache:GAUGE:HEARTBEAT:0:U
415 =item MySQL threads (F<mysql_threads.rrd>)
417   DS:running:GAUGE:HEARTBEAT:0:U
418   DS:connected:GAUGE:HEARTBEAT:0:U
419   DS:cached:GAUGE:HEARTBEAT:0:U
420   DS:created:COUNTER:HEARTBEAT:0:U
422 =item NFSv2 Procedures (F<nfs2_procedures-I<(client|server)>.rrd>)
424   DS:null:COUNTER:HEARTBEAT:0:U
425   DS:getattr:COUNTER:HEARTBEAT:0:U
426   DS:setattr:COUNTER:HEARTBEAT:0:U
427   DS:root:COUNTER:HEARTBEAT:0:U
428   DS:lookup:COUNTER:HEARTBEAT:0:U
429   DS:readlink:COUNTER:HEARTBEAT:0:U
430   DS:read:COUNTER:HEARTBEAT:0:U
431   DS:wrcache:COUNTER:HEARTBEAT:0:U
432   DS:write:COUNTER:HEARTBEAT:0:U
433   DS:create:COUNTER:HEARTBEAT:0:U
434   DS:remove:COUNTER:HEARTBEAT:0:U
435   DS:rename:COUNTER:HEARTBEAT:0:U
436   DS:link:COUNTER:HEARTBEAT:0:U
437   DS:symlink:COUNTER:HEARTBEAT:0:U
438   DS:mkdir:COUNTER:HEARTBEAT:0:U
439   DS:rmdir:COUNTER:HEARTBEAT:0:U
440   DS:readdir:COUNTER:HEARTBEAT:0:U
441   DS:fsstat:COUNTER:HEARTBEAT:0:U
443 =item NFSv3 Procedures (F<nfs3_procedures-I<(client|server)>.rrd>)
445   DS:null:COUNTER:HEARTBEAT:0:U
446   DS:getattr:COUNTER:HEARTBEAT:0:U
447   DS:setattr:COUNTER:HEARTBEAT:0:U
448   DS:lookup:COUNTER:HEARTBEAT:0:U
449   DS:access:COUNTER:HEARTBEAT:0:U
450   DS:readlink:COUNTER:HEARTBEAT:0:U
451   DS:read:COUNTER:HEARTBEAT:0:U
452   DS:write:COUNTER:HEARTBEAT:0:U
453   DS:create:COUNTER:HEARTBEAT:0:U
454   DS:mkdir:COUNTER:HEARTBEAT:0:U
455   DS:symlink:COUNTER:HEARTBEAT:0:U
456   DS:mknod:COUNTER:HEARTBEAT:0:U
457   DS:remove:COUNTER:HEARTBEAT:0:U
458   DS:rmdir:COUNTER:HEARTBEAT:0:U
459   DS:rename:COUNTER:HEARTBEAT:0:U
460   DS:link:COUNTER:HEARTBEAT:0:U
461   DS:readdir:COUNTER:HEARTBEAT:0:U
462   DS:readdirplus:COUNTER:HEARTBEAT:0:U
463   DS:fsstat:COUNTER:HEARTBEAT:0:U
464   DS:fsinfo:COUNTER:HEARTBEAT:0:U
465   DS:pathconf:COUNTER:HEARTBEAT:0:U
466   DS:commit:COUNTER:HEARTBEAT:0:U
468 =item Network latency / Ping (F<ping-I<E<lt>hostnameE<gt>>.rrd>)
470   DS:ping:GAUGE:HEARTBEAT:0:65535
472 =item Processes (F<processes.rrd>)
474   DS:running:GAUGE:HEARTBEAT:0:65535
475   DS:sleeping:GAUGE:HEARTBEAT:0:65535
476   DS:zombies:GAUGE:HEARTBEAT:0:65535
477   DS:stopped:GAUGE:HEARTBEAT:0:65535
478   DS:paging:GAUGE:HEARTBEAT:0:65535
479   DS:blocked:GAUGE:HEARTBEAT:0:65535
481 =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>)
483   DS:value:GAUGE:HEARTBEAT:U:U
485 =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>)
487   DS:value:GAUGE:HEARTBEAT:U:U
489 =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>)
491   DS:voltage:GAUGE:HEARTBEAT:U:U
493 =item Serial port traffic (F<serial-I<E<lt>numE<gt>>.rrd>)
495   DS:incoming:COUNTER:HEARTBEAT:0:U
496   DS:outgoing:COUNTER:HEARTBEAT:0:U
498 =item Spam score (F<email/spam_score.rrd>)
500   DS:score:GAUGE:HEARTBEAT:0:U
502 =item Spam checks (F<email/spam_check-I<E<lt>typeE<gt>>.rrd>)
504   DS:hits:GAUGE:HEARTBEAT:0:U
506 =item Swap usage (F<swap.rrd>)
508   DS:used:GAUGE:HEARTBEAT:0:1099511627776
509   DS:free:GAUGE:HEARTBEAT:0:1099511627776
510   DS:cached:GAUGE:HEARTBEAT:0:1099511627776
511   DS:resv:GAUGE:HEARTBEAT:0:1099511627776
513 =item Tape drive usage (F<tape-I<E<lt>nameE<gt>>.rrd>)
515   DS:rcount:COUNTER:HEARTBEAT:0:
516   DS:rmerged:COUNTER:HEARTBEAT:0:U
517   DS:rbytes:COUNTER:HEARTBEAT:0:U
518   DS:rtime:COUNTER:HEARTBEAT:0:U
519   DS:wcount:COUNTER:HEARTBEAT:0:U
520   DS:wmerged:COUNTER:HEARTBEAT:0:U
521   DS:wbytes:COUNTER:HEARTBEAT:0:U
522   DS:wtime:COUNTER:HEARTBEAT:0:U
524 =item Network traffic (F<traffic-I<E<lt>interfaceE<gt>>.rrd>)
526   DS:incoming:COUNTER:HEARTBEAT:0:U
527   DS:outgoing:COUNTER:HEARTBEAT:0:U
529 =item Interface packets (F<if_packets-I<E<lt>interfaceE<gt>>.rrd>)
531   DS:rx:COUNTER:HEARTBEAT:0:U
532   DS:tx:COUNTER:HEARTBEAT:0:U
534 =item Interface errors (F<if_errors-I<E<lt>interfaceE<gt>>.rrd>)
536   DS:rx:COUNTER:HEARTBEAT:0:U
537   DS:tx:COUNTER:HEARTBEAT:0:U
539 =item Users (F<users.rrd>)
541   DS:users:GAUGE:HEARTBEAT:0:65535
543 =item VServer load (F<vserver-I<E<lt>xidE<gt>>/load.rrd>)
545   DS:shortterm:GAUGE:HEARTBEAT:0:100
546   DS:midterm:GAUGE:HEARTBEAT:0:100
547   DS:longterm:GAUGE:HEARTBEAT:0:100
549 =item VServer threads (F<vserver-I<E<lt>xidE<gt>>/threads.rrd>)
551   DS:total:GAUGE:HEARTBEAT:0:65535
552   DS:running:GAUGE:HEARTBEAT:0:65535
553   DS:uninterruptible:GAUGE:HEARTBEAT:0:65535
554   DS:onhold:GAUGE:HEARTBEAT:0:65535
556 =item VServer network traffic (F<vserver-I<E<lt>xidE<gt>>/traffic-I<E<lt>nameE<gt>>.rrd>)
558   DS:incoming:COUNTER:HEARTBEAT:0:9223372036854775807
559   DS:outgoing:COUNTER:HEARTBEAT:0:9223372036854775807
560   DS:failed:COUNTER:HEARTBEAT:0:9223372036854775807
562 =item VServer processes (F<vserver-I<E<lt>xidE<gt>>/vs_processes.rrd>)
564   DS:total:GAUGE:HEARTBEAT:0:65535
566 =item VServer memory usage (F<vserver-I<E<lt>xidE<gt>>/vs_memory.rrd>)
568   DS:vm:GAUGE:HEARTBEAT:0:9223372036854775807
569   DS:vml:GAUGE:HEARTBEAT:0:9223372036854775807
570   DS:rss:GAUGE:HEARTBEAT:0:9223372036854775807
571   DS:anon:GAUGE:HEARTBEAT:0:9223372036854775807
573 =item Wireless link quality (F<wireless-I<E<lt>interfaceE<gt>>.rrd>)
575   DS:quality:GAUGE:HEARTBEAT:0:U
576   DS:power:GAUGE:HEARTBEAT:U:0
577   DS:noise:GAUGE:HEARTBEAT:U:0
579 =back
581 =head1 SEE ALSO
583 L<collectd.conf(5)>, L<rrdtool(1)>, L<sensors(1)>, L<hddtemp(8)>,
584 L<mbmon(1)>,
585 L<kstat(3KSTAT)>
587 =head1 AUTHOR
589 Florian Forster E<lt>octo@verplant.orgE<gt>
591 =cut