Bumped version to 3.11.7; Updated ChangeLog.
[collectd.git] / src / collectd.pod
1 =head1 NAME
2
3 collectd - System statistics collection daemon
4
5 =head1 SYNOPSIS
6
7 collectd I<[options]>
8
9 =head1 DESCRIPTION
10
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:
14
15 =over 4
16
17 =item
18
19 Apache server stats (I<apache>)
20
21 =item
22
23 Apple hardware sensors (I<apple_sensors>, Darwin only)
24
25 =item
26
27 Battery status (I<battery>)
28
29 =item
30
31 CPU utilization (I<cpu>)
32
33 =item
34
35 Mountpoint usage (I<df>)
36
37 =item
38
39 Disk and partition usage/throughput (I<disk>)
40
41 =item
42
43 DNS traffic (I<dns>)
44
45 =item
46
47 Email usage (I<email>)
48
49 =item
50
51 Harddisk temperatures (I<hddtemp>)
52
53 =item
54
55 System load averages (I<load>)
56
57 =item
58
59 Motherboard monitor (I<mbmon>)
60
61 =item
62
63 Memory usage (I<memory>)
64
65 =item
66
67 MySQL statistics (I<mysql>)
68
69 =item
70
71 NFS utilization (I<nfs>, Linux only)
72
73 =item
74
75 Network latency (I<ping>)
76
77 =item
78
79 Number of processes (I<processes>, Linux only)
80
81 =item
82
83 lm_sensors information (I<sensors>, Linux only)
84
85 =item
86
87 Serial port traffic (I<serial>, Linux only)
88
89 =item
90
91 Swap usage (I<swap>)
92
93 =item
94
95 Tape drive usage (I<tape>, Solaris only)
96
97 =item
98
99 Network traffic (I<traffic>)
100
101 =item
102
103 Number of users logged into the system (I<users>)
104
105 =item
106
107 System ressources used by VServers (I<vserver>)
108
109 =item
110
111 Wireless network stats (I<wireless>)
112
113 =back
114
115 =head1 OPTIONS
116
117 =over 4
118
119 =item B<-C> I<E<lt>config-fileE<gt>>
120
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.
124
125 =item B<-P> I<E<lt>pid-fileE<gt>>
126
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.
131
132 =item B<-f>
133
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>.
137
138 =item B<-h>
139
140 Output usage information and exit.
141
142 =back
143
144 =head1 MODES
145
146 collectd can operate in four different operating modes. The modes are described
147 below.
148
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>.
152
153 The modes B<client mode> and B<server mode> are used to send data over a
154 network and receive it again.
155
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.
159
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.
162
163 In the last mode, B<log mode>, data is collected locally and written in
164 text files that reside in I<DataDir>.
165
166 Please refer to L<collectd.conf(5)> for the configuration options and default
167 values.
168
169 =head1 SPECIAL PLUGINS
170
171 =head2 apache
172
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.
177
178   ExtendedStatus on
179   <IfModule mod_status.c>
180     <Location /mod_status>
181       SetHandler server-status
182     </Location>
183   </IfModule>
184
185 This plugin requires further configuration. Please read L<collectd.conf(5)>.
186
187 =head2 cpufreq
188
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.
194
195 =head2 email
196
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:
200
201 E-Mail type (e.g. "ham", "spam", "virus", ...) and size (bytes):
202
203   e:<type>:<size>
204
205 If C<size> is less than or equal to zero, C<size> is ignored.
206
207 Spam score:
208
209   s:<value>
210
211 Successful spam checks (e.g. "BAYES_99", "SUBJECT_DRUG_GAP_C", ...):
212
213   c:<type1>[,<type2>,...]
214
215 Each line is limited to 256 characters (including the newline character). 
216 Longer lines will be ignored.
217
218 =head2 mysql
219
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.
224
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.
231
232 =head2 sensors
233
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.
238
239 The B<lm_sensors> homepage can be found at
240 L<http://secure.netroedge.com/~lm78/>.
241
242 =head2 mbmon
243
244 The B<mbmon> module uses mbmon to retrieve temperature, voltage, etc.
245
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..
251
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.
255
256 =head2 hddtemp
257
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..
263
264 The B<hddtemp> homepage can be found at
265 L<http://www.guzu.net/linux/hddtemp.php>.
266
267 =head2 vserver
268
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.
274
275 The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
276
277 =head1 RRD FILES
278
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:
282
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
295
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.
299
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
306
307 The DS'es depend on the module creating the RRD files:
308
309 =over 4
310
311 =item Apache traffic (F<apache/apache_bytes.rrd>)
312
313   DS:count:COUNTER:HEARTBEAT:0:134217728
314
315 =item Apache requests (F<apache/apache_requests.rrd>)
316
317   DS:count:COUNTER:HEARTBEAT:0:1048576
318
319 =item Apache scoreboard (F<apache/apache_scoreboard-I<E<lt>nameE<gt>>.rrd>)
320
321   DS:count:GAUGE:HEARTBEAT:0:U
322
323 =item Apple temperature sensor (F<apple_sensors/temperature-I<E<lt>nameE<gt>>.rrd>)
324
325   DS:value:GAUGE:HEARTBEAT:U:U
326
327 =item Apple fanspeed sensor (F<apple_sensors/fanspeed-I<E<lt>nameE<gt>>.rrd>)
328
329   DS:value:GAUGE:HEARTBEAT:U:U
330
331 =item Battery charge (F<battery-I<E<lt>nameE<gt>>/charge.rrd>)
332
333   DS:charge:GAUGE:HEARTBEAT:0:U
334
335 =item Battery current (F<battery-I<E<lt>nameE<gt>>/current.rrd>)
336
337   DS:current:GAUGE:HEARTBEAT:U:U
338
339 =item Battery voltage (F<battery-I<E<lt>nameE<gt>>/voltage.rrd>)
340
341   DS:voltage:GAUGE:HEARTBEAT:U:U
342
343 =item CPU (F<cpu-I<E<lt>numE<gt>>.rrd>)
344
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
350
351 =item CPU frequency (F<cpufreq-I<E<lt>numE<gt>>.rrd>)
352
353   DS:value:GAUGE:HEARTBEAT:0:U
354
355 =item Mountpoints (F<df-I<E<lt>pathE<gt>>.rrd>)
356
357   DS:used:GAUGE:HEARTBEAT:0:U
358   DS:free:GAUGE:HEARTBEAT:0:U
359
360 =item Diskstats (F<disk-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
361
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
370
371 =item Diskstats (F<partition-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
372
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
377
378 =item E-Mail count (F<email/email-I<E<lt>typeE<gt>>.rrd>)
379
380   DS:count:GAUGE:HEARTBEAT:0:U
381
382 =item E-Mail size (F<email/email_size-I<E<lt>typeE<gt>>.rrd>)
383
384   DS:size:GAUGE:HEARTBEAT:0:U
385
386 =item HDD Temperature (F<hddtemp-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
387
388   DS:value:GAUGE:HEARTBEAT:U:U
389
390 =item System load (F<load.rrd>)
391
392   DS:shortterm:GAUGE:HEARTBEAT:0:100
393   DS:midterm:GAUGE:HEARTBEAT:0:100
394   DS:longterm:GAUGE:HEARTBEAT:0:100
395
396 =item Memory usage (F<memory.rrd>)
397
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
402
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>)
404
405   DS:value:COUNTER:HEARTBEAT:0:U
406
407 =item MySQL query cache (F<mysql_qcache.rrd>)
408
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
414
415 =item MySQL threads (F<mysql_threads.rrd>)
416
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
421
422 =item NFSv2 Procedures (F<nfs2_procedures-I<(client|server)>.rrd>)
423
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
442
443 =item NFSv3 Procedures (F<nfs3_procedures-I<(client|server)>.rrd>)
444
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
467
468 =item Network latency / Ping (F<ping-I<E<lt>hostnameE<gt>>.rrd>)
469
470   DS:ping:GAUGE:HEARTBEAT:0:65535
471
472 =item Processes (F<processes.rrd>)
473
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
480
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>)
482
483   DS:value:GAUGE:HEARTBEAT:U:U
484
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>)
486
487   DS:value:GAUGE:HEARTBEAT:U:U
488
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>)
490
491   DS:voltage:GAUGE:HEARTBEAT:U:U
492
493 =item Serial port traffic (F<serial-I<E<lt>numE<gt>>.rrd>)
494
495   DS:incoming:COUNTER:HEARTBEAT:0:U
496   DS:outgoing:COUNTER:HEARTBEAT:0:U
497
498 =item Spam score (F<email/spam_score.rrd>)
499
500   DS:score:GAUGE:HEARTBEAT:0:U
501
502 =item Spam checks (F<email/spam_check-I<E<lt>typeE<gt>>.rrd>)
503
504   DS:hits:GAUGE:HEARTBEAT:0:U
505
506 =item Swap usage (F<swap.rrd>)
507
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
512
513 =item Tape drive usage (F<tape-I<E<lt>nameE<gt>>.rrd>)
514
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
523
524 =item Network traffic (F<traffic-I<E<lt>interfaceE<gt>>.rrd>)
525
526   DS:incoming:COUNTER:HEARTBEAT:0:U
527   DS:outgoing:COUNTER:HEARTBEAT:0:U
528
529 =item Interface packets (F<if_packets-I<E<lt>interfaceE<gt>>.rrd>)
530
531   DS:rx:COUNTER:HEARTBEAT:0:U
532   DS:tx:COUNTER:HEARTBEAT:0:U
533
534 =item Interface errors (F<if_errors-I<E<lt>interfaceE<gt>>.rrd>)
535
536   DS:rx:COUNTER:HEARTBEAT:0:U
537   DS:tx:COUNTER:HEARTBEAT:0:U
538
539 =item Users (F<users.rrd>)
540
541   DS:users:GAUGE:HEARTBEAT:0:65535
542
543 =item VServer load (F<vserver-I<E<lt>xidE<gt>>/load.rrd>)
544
545   DS:shortterm:GAUGE:HEARTBEAT:0:100
546   DS:midterm:GAUGE:HEARTBEAT:0:100
547   DS:longterm:GAUGE:HEARTBEAT:0:100
548
549 =item VServer threads (F<vserver-I<E<lt>xidE<gt>>/threads.rrd>)
550
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
555
556 =item VServer network traffic (F<vserver-I<E<lt>xidE<gt>>/traffic-I<E<lt>nameE<gt>>.rrd>)
557
558   DS:incoming:COUNTER:HEARTBEAT:0:9223372036854775807
559   DS:outgoing:COUNTER:HEARTBEAT:0:9223372036854775807
560   DS:failed:COUNTER:HEARTBEAT:0:9223372036854775807
561
562 =item VServer processes (F<vserver-I<E<lt>xidE<gt>>/vs_processes.rrd>)
563
564   DS:total:GAUGE:HEARTBEAT:0:65535
565
566 =item VServer memory usage (F<vserver-I<E<lt>xidE<gt>>/vs_memory.rrd>)
567
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
572
573 =item Wireless link quality (F<wireless-I<E<lt>interfaceE<gt>>.rrd>)
574
575   DS:quality:GAUGE:HEARTBEAT:0:U
576   DS:power:GAUGE:HEARTBEAT:U:0
577   DS:noise:GAUGE:HEARTBEAT:U:0
578
579 =back
580
581 =head1 SEE ALSO
582
583 L<collectd.conf(5)>, L<rrdtool(1)>, L<sensors(1)>, L<hddtemp(8)>,
584 L<mbmon(1)>,
585 L<kstat(3KSTAT)>
586
587 =head1 AUTHOR
588
589 Florian Forster E<lt>octo@verplant.orgE<gt>
590
591 =cut