bf76055f0cac9e29041e3e9b1de974937b180cf6
[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 Spam score:
206
207   s:<value>
208
209 Successful spam checks (e.g. "BAYES_99", "SUBJECT_DRUG_GAP_C", ...):
210
211   c:<type1>[,<type2>,...]
212
213 Each line is limited to 256 characters (including the newline character). 
214 Longer lines will be ignored.
215
216 =head2 mysql
217
218 Requires B<mysqlclient> to be installed. It connects to the database when
219 started and keeps the connection up as long as possible. When the connection is
220 interrupted for whatever reason it will try to re-connect. The syslog will
221 contain loud complaints in case anything goes wrong.
222
223 This plugin issues C<SHOW STATUS> and evaluates C<Bytes_{received,sent}>,
224 C<Com_*> and C<Handler_*> which correspond to F<traffic-mysql.rrd>,
225 F<mysql_commands-*.rrd> and F<mysql_handler-*.rrd>. Also, the values of
226 C<Qcache_*> are put in F<mysql_qcache.rrd> and values of C<Threads_*> are put
227 in F<mysql_threads.rrd>. Please refer to the B<MySQL reference manual>,
228 I<5.2.4. Server Status Variables> for an explanation of these values.
229
230 =head2 sensors
231
232 The B<sensors> module uses lm_sensors to retrieve sensor-values. This means
233 that all the needed modules have to be loaded and lm_sensors has to be
234 configured (most likely by editing F</etc/sensors.conf>. Read
235 L<sensors.conf(5)> for details.
236
237 The B<lm_sensors> homepage can be found at
238 L<http://secure.netroedge.com/~lm78/>.
239
240 =head2 mbmon
241
242 The B<mbmon> module uses mbmon to retrieve temperature, voltage, etc.
243
244 collectd connects to B<localhost> (127.0.0.1), port B<411/tcp>.
245 The B<Host> and B<Port> options can be used to change these
246 default values. See L<collectd.conf(5)> for details. C<mbmon> has to be
247 running to work correctly. If C<mbmon> is not running timeouts may appear
248 which may interfere with other statistics..
249
250 C<mbmon> must be run with the -r option ("print TAG and Value format");
251 Debian's /etc/init.d/mbmon script already does this, other people
252 will need to ensure that this is the case.
253
254 =head2 hddtemp
255
256 To get values from B<hddtemp> collectd connects to B<localhost> (127.0.0.1),
257 port B<7634/tcp>. The B<Host> and B<Port> options can be used to change these
258 default values. See L<collectd.conf(5)> for details. C<hddtemp> has to be
259 running to work correctly. If C<hddtemp> is not running timeouts may appear
260 which may interfere with other statistics..
261
262 The B<hddtemp> homepage can be found at
263 L<http://www.guzu.net/linux/hddtemp.php>.
264
265 =head2 vserver
266
267 B<VServer> support is only available for Linux. It cannot yet be found in a 
268 vanilla kernel, though. To make use of this plugin you need a kernel that has 
269 B<VServer> support built in, i.e. you need to apply the patches and compile 
270 your own kernel, which will then provide the /proc/virtual filesystem that is
271 required by this plugin.
272
273 The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
274
275 =head1 RRD FILES
276
277 The RRD files are created automatically. The size of the RRAs depend on the
278 compile time settings of I<step> and I<width>. With the default values (I<step>
279 = B<10>, I<width> = B<1200>) the following RRAs are created:
280
281   RRA:AVERAGE:0.1:1:8640
282   RRA:AVERAGE:0.1:50:1210
283   RRA:AVERAGE:0.1:223:1202
284   RRA:AVERAGE:0.1:2635:1201
285   RRA:MIN:0.1:1:8640
286   RRA:MIN:0.1:50:1210
287   RRA:MIN:0.1:223:1202
288   RRA:MIN:0.1:2635:1201
289   RRA:MAX:0.1:1:8640
290   RRA:MAX:0.1:50:1210
291   RRA:MAX:0.1:223:1202
292   RRA:MAX:0.1:2635:1201
293
294 By default collectd uses a 10 second I<step>. Thus the RRAs contain the
295 following timespans. If you've changed the I<step> at compile time you will
296 have calculate resolution and timespan yourself.
297
298   PDP per CDP |  Resolution  | Data points | Timespan
299   ------------+--------------+-------------+---------
300             1 | 10.0 seconds !        8640 ! 1 day
301            50 |  8.3 minutes |        1210 | 1 week
302           223 | 37.2 minutes |        1202 | 1 month
303          2635 |  7.3 hours   |        1201 | 1 year
304
305 The DS'es depend on the module creating the RRD files:
306
307 =over 4
308
309 =item Apache traffic (F<apache/apache_bytes.rrd>)
310
311   DS:count:COUNTER:HEARTBEAT:0:134217728
312
313 =item Apache requests (F<apache/apache_requests.rrd>)
314
315   DS:count:COUNTER:HEARTBEAT:0:1048576
316
317 =item Apache scoreboard (F<apache/apache_scoreboard-I<E<lt>nameE<gt>>.rrd>)
318
319   DS:count:GAUGE:HEARTBEAT:0:U
320
321 =item Apple temperature sensor (F<apple_sensors/temperature-I<E<lt>nameE<gt>>.rrd>)
322
323   DS:value:GAUGE:HEARTBEAT:U:U
324
325 =item Apple fanspeed sensor (F<apple_sensors/fanspeed-I<E<lt>nameE<gt>>.rrd>)
326
327   DS:value:GAUGE:HEARTBEAT:U:U
328
329 =item Battery charge (F<battery-I<E<lt>nameE<gt>>/charge.rrd>)
330
331   DS:charge:GAUGE:HEARTBEAT:0:U
332
333 =item Battery current (F<battery-I<E<lt>nameE<gt>>/current.rrd>)
334
335   DS:current:GAUGE:HEARTBEAT:U:U
336
337 =item Battery voltage (F<battery-I<E<lt>nameE<gt>>/voltage.rrd>)
338
339   DS:voltage:GAUGE:HEARTBEAT:U:U
340
341 =item CPU (F<cpu-I<E<lt>numE<gt>>.rrd>)
342
343   DS:user:COUNTER:HEARTBEAT:0:100
344   DS:nice:COUNTER:HEARTBEAT:0:100
345   DS:syst:COUNTER:HEARTBEAT:0:100
346   DS:idle:COUNTER:HEARTBEAT:0:100
347   DS:wait:COUNTER:HEARTBEAT:0:100
348
349 =item CPU frequency (F<cpufreq-I<E<lt>numE<gt>>.rrd>)
350
351   DS:value:GAUGE:HEARTBEAT:0:U
352
353 =item Mountpoints (F<df-I<E<lt>pathE<gt>>.rrd>)
354
355   DS:used:GAUGE:HEARTBEAT:0:U
356   DS:free:GAUGE:HEARTBEAT:0:U
357
358 =item Diskstats (F<disk-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
359
360   DS:rcount:COUNTER:HEARTBEAT:0:U
361   DS:rmerged:COUNTER:HEARTBEAT:0:U
362   DS:rbytes:COUNTER:HEARTBEAT:0:U
363   DS:rtime:COUNTER:HEARTBEAT:0:U
364   DS:wcount:COUNTER:HEARTBEAT:0:U
365   DS:wmerged:COUNTER:HEARTBEAT:0:U
366   DS:wbytes:COUNTER:HEARTBEAT:0:U
367   DS:wtime:COUNTER:HEARTBEAT:0:U
368
369 =item Diskstats (F<partition-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
370
371   DS:rcount:COUNTER:HEARTBEAT:0:U
372   DS:rbytes:COUNTER:HEARTBEAT:0:U
373   DS:wcount:COUNTER:HEARTBEAT:0:U
374   DS:wbytes:COUNTER:HEARTBEAT:0:U
375
376 =item E-Mail count (F<email/email-I<E<lt>typeE<gt>>.rrd>)
377
378   DS:count:GAUGE:HEARTBEAT:0:U
379
380 =item E-Mail size (F<email/email_size-I<E<lt>typeE<gt>>.rrd>)
381
382   DS:size:GAUGE:HEARTBEAT:0:U
383
384 =item HDD Temperature (F<hddtemp-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
385
386   DS:value:GAUGE:HEARTBEAT:U:U
387
388 =item System load (F<load.rrd>)
389
390   DS:shortterm:GAUGE:HEARTBEAT:0:100
391   DS:midterm:GAUGE:HEARTBEAT:0:100
392   DS:longterm:GAUGE:HEARTBEAT:0:100
393
394 =item Memory usage (F<memory.rrd>)
395
396   DS:used:GAUGE:HEARTBEAT:0:9223372036854775807
397   DS:free:GAUGE:HEARTBEAT:0:9223372036854775807
398   DS:buffers:GAUGE:HEARTBEAT:0:9223372036854775807
399   DS:cached:GAUGE:HEARTBEAT:0:9223372036854775807
400
401 =item MySQL commands and handlers (F<mysql_commands-I<E<lt>commandE<gt>>.rrd> and F<mysql_handler-I<E<lt>handlerE<gt>>.rrd>)
402
403   DS:value:COUNTER:HEARTBEAT:0:U
404
405 =item MySQL query cache (F<mysql_qcache.rrd>)
406
407   DS:hits:COUNTER:HEARTBEAT:0:U
408   DS:inserts:COUNTER:HEARTBEAT:0:U
409   DS:not_cached:COUNTER:HEARTBEAT:0:U
410   DS:lowmem_prunes:COUNTER:HEARTBEAT:0:U
411   DS:queries_in_cache:GAUGE:HEARTBEAT:0:U
412
413 =item MySQL threads (F<mysql_threads.rrd>)
414
415   DS:running:GAUGE:HEARTBEAT:0:U
416   DS:connected:GAUGE:HEARTBEAT:0:U
417   DS:cached:GAUGE:HEARTBEAT:0:U
418   DS:created:COUNTER:HEARTBEAT:0:U
419
420 =item NFSv2 Procedures (F<nfs2_procedures-I<(client|server)>.rrd>)
421
422   DS:null:COUNTER:HEARTBEAT:0:U
423   DS:getattr:COUNTER:HEARTBEAT:0:U
424   DS:setattr:COUNTER:HEARTBEAT:0:U
425   DS:root:COUNTER:HEARTBEAT:0:U
426   DS:lookup:COUNTER:HEARTBEAT:0:U
427   DS:readlink:COUNTER:HEARTBEAT:0:U
428   DS:read:COUNTER:HEARTBEAT:0:U
429   DS:wrcache:COUNTER:HEARTBEAT:0:U
430   DS:write:COUNTER:HEARTBEAT:0:U
431   DS:create:COUNTER:HEARTBEAT:0:U
432   DS:remove:COUNTER:HEARTBEAT:0:U
433   DS:rename:COUNTER:HEARTBEAT:0:U
434   DS:link:COUNTER:HEARTBEAT:0:U
435   DS:symlink:COUNTER:HEARTBEAT:0:U
436   DS:mkdir:COUNTER:HEARTBEAT:0:U
437   DS:rmdir:COUNTER:HEARTBEAT:0:U
438   DS:readdir:COUNTER:HEARTBEAT:0:U
439   DS:fsstat:COUNTER:HEARTBEAT:0:U
440
441 =item NFSv3 Procedures (F<nfs3_procedures-I<(client|server)>.rrd>)
442
443   DS:null:COUNTER:HEARTBEAT:0:U
444   DS:getattr:COUNTER:HEARTBEAT:0:U
445   DS:setattr:COUNTER:HEARTBEAT:0:U
446   DS:lookup:COUNTER:HEARTBEAT:0:U
447   DS:access:COUNTER:HEARTBEAT:0:U
448   DS:readlink:COUNTER:HEARTBEAT:0:U
449   DS:read:COUNTER:HEARTBEAT:0:U
450   DS:write:COUNTER:HEARTBEAT:0:U
451   DS:create:COUNTER:HEARTBEAT:0:U
452   DS:mkdir:COUNTER:HEARTBEAT:0:U
453   DS:symlink:COUNTER:HEARTBEAT:0:U
454   DS:mknod:COUNTER:HEARTBEAT:0:U
455   DS:remove:COUNTER:HEARTBEAT:0:U
456   DS:rmdir:COUNTER:HEARTBEAT:0:U
457   DS:rename:COUNTER:HEARTBEAT:0:U
458   DS:link:COUNTER:HEARTBEAT:0:U
459   DS:readdir:COUNTER:HEARTBEAT:0:U
460   DS:readdirplus:COUNTER:HEARTBEAT:0:U
461   DS:fsstat:COUNTER:HEARTBEAT:0:U
462   DS:fsinfo:COUNTER:HEARTBEAT:0:U
463   DS:pathconf:COUNTER:HEARTBEAT:0:U
464   DS:commit:COUNTER:HEARTBEAT:0:U
465
466 =item Network latency / Ping (F<ping-I<E<lt>hostnameE<gt>>.rrd>)
467
468   DS:ping:GAUGE:HEARTBEAT:0:65535
469
470 =item Processes (F<processes.rrd>)
471
472   DS:running:GAUGE:HEARTBEAT:0:65535
473   DS:sleeping:GAUGE:HEARTBEAT:0:65535
474   DS:zombies:GAUGE:HEARTBEAT:0:65535
475   DS:stopped:GAUGE:HEARTBEAT:0:65535
476   DS:paging:GAUGE:HEARTBEAT:0:65535
477   DS:blocked:GAUGE:HEARTBEAT:0:65535
478
479 =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>)
480
481   DS:value:GAUGE:HEARTBEAT:U:U
482
483 =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>)
484
485   DS:value:GAUGE:HEARTBEAT:U:U
486
487 =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>)
488
489   DS:voltage:GAUGE:HEARTBEAT:U:U
490
491 =item Serial port traffic (F<serial-I<E<lt>numE<gt>>.rrd>)
492
493   DS:incoming:COUNTER:HEARTBEAT:0:U
494   DS:outgoing:COUNTER:HEARTBEAT:0:U
495
496 =item Spam score (F<email/spam_score.rrd>)
497
498   DS:score:GAUGE:HEARTBEAT:0:U
499
500 =item Spam checks (F<email/spam_check-I<E<lt>typeE<gt>>.rrd>)
501
502   DS:hits:GAUGE:HEARTBEAT:0:U
503
504 =item Swap usage (F<swap.rrd>)
505
506   DS:used:GAUGE:HEARTBEAT:0:1099511627776
507   DS:free:GAUGE:HEARTBEAT:0:1099511627776
508   DS:cached:GAUGE:HEARTBEAT:0:1099511627776
509   DS:resv:GAUGE:HEARTBEAT:0:1099511627776
510
511 =item Tape drive usage (F<tape-I<E<lt>nameE<gt>>.rrd>)
512
513   DS:rcount:COUNTER:HEARTBEAT:0:
514   DS:rmerged:COUNTER:HEARTBEAT:0:U
515   DS:rbytes:COUNTER:HEARTBEAT:0:U
516   DS:rtime:COUNTER:HEARTBEAT:0:U
517   DS:wcount:COUNTER:HEARTBEAT:0:U
518   DS:wmerged:COUNTER:HEARTBEAT:0:U
519   DS:wbytes:COUNTER:HEARTBEAT:0:U
520   DS:wtime:COUNTER:HEARTBEAT:0:U
521
522 =item Network traffic (F<traffic-I<E<lt>interfaceE<gt>>.rrd>)
523
524   DS:incoming:COUNTER:HEARTBEAT:0:U
525   DS:outgoing:COUNTER:HEARTBEAT:0:U
526
527 =item Interface packets (F<if_packets-I<E<lt>interfaceE<gt>>.rrd>)
528
529   DS:rx:COUNTER:HEARTBEAT:0:U
530   DS:tx:COUNTER:HEARTBEAT:0:U
531
532 =item Interface errors (F<if_errors-I<E<lt>interfaceE<gt>>.rrd>)
533
534   DS:rx:COUNTER:HEARTBEAT:0:U
535   DS:tx:COUNTER:HEARTBEAT:0:U
536
537 =item Users (F<users.rrd>)
538
539   DS:users:GAUGE:HEARTBEAT:0:65535
540
541 =item VServer load (F<vserver-I<E<lt>xidE<gt>>/load.rrd>)
542
543   DS:shortterm:GAUGE:HEARTBEAT:0:100
544   DS:midterm:GAUGE:HEARTBEAT:0:100
545   DS:longterm:GAUGE:HEARTBEAT:0:100
546
547 =item VServer threads (F<vserver-I<E<lt>xidE<gt>>/threads.rrd>)
548
549   DS:total:GAUGE:HEARTBEAT:0:65535
550   DS:running:GAUGE:HEARTBEAT:0:65535
551   DS:uninterruptible:GAUGE:HEARTBEAT:0:65535
552   DS:onhold:GAUGE:HEARTBEAT:0:65535
553
554 =item VServer network traffic (F<vserver-I<E<lt>xidE<gt>>/traffic-I<E<lt>nameE<gt>>.rrd>)
555
556   DS:incoming:COUNTER:HEARTBEAT:0:9223372036854775807
557   DS:outgoing:COUNTER:HEARTBEAT:0:9223372036854775807
558   DS:failed:COUNTER:HEARTBEAT:0:9223372036854775807
559
560 =item VServer processes (F<vserver-I<E<lt>xidE<gt>>/vs_processes.rrd>)
561
562   DS:total:GAUGE:HEARTBEAT:0:65535
563
564 =item VServer memory usage (F<vserver-I<E<lt>xidE<gt>>/vs_memory.rrd>)
565
566   DS:vm:GAUGE:HEARTBEAT:0:9223372036854775807
567   DS:vml:GAUGE:HEARTBEAT:0:9223372036854775807
568   DS:rss:GAUGE:HEARTBEAT:0:9223372036854775807
569   DS:anon:GAUGE:HEARTBEAT:0:9223372036854775807
570
571 =item Wireless link quality (F<wireless-I<E<lt>interfaceE<gt>>.rrd>)
572
573   DS:quality:GAUGE:HEARTBEAT:0:U
574   DS:power:GAUGE:HEARTBEAT:U:0
575   DS:noise:GAUGE:HEARTBEAT:U:0
576
577 =back
578
579 =head1 SEE ALSO
580
581 L<collectd.conf(5)>, L<rrdtool(1)>, L<sensors(1)>, L<hddtemp(8)>,
582 L<mbmon(1)>,
583 L<kstat(3KSTAT)>
584
585 =head1 AUTHOR
586
587 Florian Forster E<lt>octo@verplant.orgE<gt>
588
589 =cut