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 Spam score:
207 s:<value>
209 Successful spam checks (e.g. "BAYES_99", "SUBJECT_DRUG_GAP_C", ...):
211 c:<type1>[,<type2>,...]
213 Each line is limited to 256 characters (including the newline character).
214 Longer lines will be ignored.
216 =head2 mysql
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.
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.
230 =head2 sensors
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.
237 The B<lm_sensors> homepage can be found at
238 L<http://secure.netroedge.com/~lm78/>.
240 =head2 mbmon
242 The B<mbmon> module uses mbmon to retrieve temperature, voltage, etc.
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..
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.
254 =head2 hddtemp
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..
262 The B<hddtemp> homepage can be found at
263 L<http://www.guzu.net/linux/hddtemp.php>.
265 =head2 vserver
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.
273 The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
275 =head1 RRD FILES
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:
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
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.
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
305 The DS'es depend on the module creating the RRD files:
307 =over 4
309 =item Apache traffic (F<apache/apache_bytes.rrd>)
311 DS:count:COUNTER:HEARTBEAT:0:134217728
313 =item Apache requests (F<apache/apache_requests.rrd>)
315 DS:count:COUNTER:HEARTBEAT:0:1048576
317 =item Apache scoreboard (F<apache/apache_scoreboard-I<E<lt>nameE<gt>>.rrd>)
319 DS:count:GAUGE:HEARTBEAT:0:U
321 =item Apple temperature sensor (F<apple_sensors/temperature-I<E<lt>nameE<gt>>.rrd>)
323 DS:value:GAUGE:HEARTBEAT:U:U
325 =item Apple fanspeed sensor (F<apple_sensors/fanspeed-I<E<lt>nameE<gt>>.rrd>)
327 DS:value:GAUGE:HEARTBEAT:U:U
329 =item Battery charge (F<battery-I<E<lt>nameE<gt>>/charge.rrd>)
331 DS:charge:GAUGE:HEARTBEAT:0:U
333 =item Battery current (F<battery-I<E<lt>nameE<gt>>/current.rrd>)
335 DS:current:GAUGE:HEARTBEAT:U:U
337 =item Battery voltage (F<battery-I<E<lt>nameE<gt>>/voltage.rrd>)
339 DS:voltage:GAUGE:HEARTBEAT:U:U
341 =item CPU (F<cpu-I<E<lt>numE<gt>>.rrd>)
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
349 =item CPU frequency (F<cpufreq-I<E<lt>numE<gt>>.rrd>)
351 DS:value:GAUGE:HEARTBEAT:0:U
353 =item Mountpoints (F<df-I<E<lt>pathE<gt>>.rrd>)
355 DS:used:GAUGE:HEARTBEAT:0:U
356 DS:free:GAUGE:HEARTBEAT:0:U
358 =item Diskstats (F<disk-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
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
369 =item Diskstats (F<partition-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
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
376 =item E-Mail count (F<email/email-I<E<lt>typeE<gt>>.rrd>)
378 DS:count:GAUGE:HEARTBEAT:0:U
380 =item E-Mail size (F<email/email_size-I<E<lt>typeE<gt>>.rrd>)
382 DS:size:GAUGE:HEARTBEAT:0:U
384 =item HDD Temperature (F<hddtemp-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
386 DS:value:GAUGE:HEARTBEAT:U:U
388 =item System load (F<load.rrd>)
390 DS:shortterm:GAUGE:HEARTBEAT:0:100
391 DS:midterm:GAUGE:HEARTBEAT:0:100
392 DS:longterm:GAUGE:HEARTBEAT:0:100
394 =item Memory usage (F<memory.rrd>)
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
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>)
403 DS:value:COUNTER:HEARTBEAT:0:U
405 =item MySQL query cache (F<mysql_qcache.rrd>)
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
413 =item MySQL threads (F<mysql_threads.rrd>)
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
420 =item NFSv2 Procedures (F<nfs2_procedures-I<(client|server)>.rrd>)
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
441 =item NFSv3 Procedures (F<nfs3_procedures-I<(client|server)>.rrd>)
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
466 =item Network latency / Ping (F<ping-I<E<lt>hostnameE<gt>>.rrd>)
468 DS:ping:GAUGE:HEARTBEAT:0:65535
470 =item Processes (F<processes.rrd>)
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
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>)
481 DS:value:GAUGE:HEARTBEAT:U:U
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>)
485 DS:value:GAUGE:HEARTBEAT:U:U
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>)
489 DS:voltage:GAUGE:HEARTBEAT:U:U
491 =item Serial port traffic (F<serial-I<E<lt>numE<gt>>.rrd>)
493 DS:incoming:COUNTER:HEARTBEAT:0:U
494 DS:outgoing:COUNTER:HEARTBEAT:0:U
496 =item Spam score (F<email/spam_score.rrd>)
498 DS:score:GAUGE:HEARTBEAT:0:U
500 =item Spam checks (F<email/spam_check-I<E<lt>typeE<gt>>.rrd>)
502 DS:hits:GAUGE:HEARTBEAT:0:U
504 =item Swap usage (F<swap.rrd>)
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
511 =item Tape drive usage (F<tape-I<E<lt>nameE<gt>>.rrd>)
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
522 =item Network traffic (F<traffic-I<E<lt>interfaceE<gt>>.rrd>)
524 DS:incoming:COUNTER:HEARTBEAT:0:U
525 DS:outgoing:COUNTER:HEARTBEAT:0:U
527 =item Interface packets (F<if_packets-I<E<lt>interfaceE<gt>>.rrd>)
529 DS:rx:COUNTER:HEARTBEAT:0:U
530 DS:tx:COUNTER:HEARTBEAT:0:U
532 =item Interface errors (F<if_errors-I<E<lt>interfaceE<gt>>.rrd>)
534 DS:rx:COUNTER:HEARTBEAT:0:U
535 DS:tx:COUNTER:HEARTBEAT:0:U
537 =item Users (F<users.rrd>)
539 DS:users:GAUGE:HEARTBEAT:0:65535
541 =item VServer load (F<vserver-I<E<lt>xidE<gt>>/load.rrd>)
543 DS:shortterm:GAUGE:HEARTBEAT:0:100
544 DS:midterm:GAUGE:HEARTBEAT:0:100
545 DS:longterm:GAUGE:HEARTBEAT:0:100
547 =item VServer threads (F<vserver-I<E<lt>xidE<gt>>/threads.rrd>)
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
554 =item VServer network traffic (F<vserver-I<E<lt>xidE<gt>>/traffic-I<E<lt>nameE<gt>>.rrd>)
556 DS:incoming:COUNTER:HEARTBEAT:0:9223372036854775807
557 DS:outgoing:COUNTER:HEARTBEAT:0:9223372036854775807
558 DS:failed:COUNTER:HEARTBEAT:0:9223372036854775807
560 =item VServer processes (F<vserver-I<E<lt>xidE<gt>>/vs_processes.rrd>)
562 DS:total:GAUGE:HEARTBEAT:0:65535
564 =item VServer memory usage (F<vserver-I<E<lt>xidE<gt>>/vs_memory.rrd>)
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
571 =item Wireless link quality (F<wireless-I<E<lt>interfaceE<gt>>.rrd>)
573 DS:quality:GAUGE:HEARTBEAT:0:U
574 DS:power:GAUGE:HEARTBEAT:U:0
575 DS:noise:GAUGE:HEARTBEAT:U:0
577 =back
579 =head1 SEE ALSO
581 L<collectd.conf(5)>, L<rrdtool(1)>, L<sensors(1)>, L<hddtemp(8)>,
582 L<mbmon(1)>,
583 L<kstat(3KSTAT)>
585 =head1 AUTHOR
587 Florian Forster E<lt>octo@verplant.orgE<gt>
589 =cut