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 Memory usage (I<memory>)
61 =item
63 MySQL statistics (I<mysql>)
65 =item
67 NFS utilization (I<nfs>, Linux only)
69 =item
71 Network latency (I<ping>)
73 =item
75 Number of processes (I<processes>, Linux only)
77 =item
79 lm_sensors information (I<sensors>, Linux only)
81 =item
83 Serial port traffic (I<serial>, Linux only)
85 =item
87 Swap usage (I<swap>)
89 =item
91 Tape drive usage (I<tape>, Solaris only)
93 =item
95 Network traffic (I<traffic>)
97 =item
99 Number of users logged into the system (I<users>)
101 =item
103 System ressources used by VServers (I<vserver>)
105 =item
107 Wireless network stats (I<wireless>)
109 =back
111 =head1 OPTIONS
113 =over 4
115 =item B<-C> I<E<lt>config-fileE<gt>>
117 Specify an alternative config file. This is the place to go when you wish to
118 change B<collectd>'s behavior. The path may be relative to the current working
119 directory.
121 =item B<-P> I<E<lt>pid-fileE<gt>>
123 Specify an alternative pid file. This overwrites any settings in the config
124 file. This is thought for init-scripts that require the PID-file in a certain
125 directory to work correctly. For everyday-usage use the B<PIDFile>
126 config-option.
128 =item B<-f>
130 Don't fork to the background. I<collectd> will also B<not> close standard file
131 descriptors, detach from the session nor write a pid file. This is mainly
132 thought for 'supervisioning' init replacements such as I<runit>.
134 =item B<-h>
136 Output usage information and exit.
138 =back
140 =head1 MODES
142 collectd can operate in four different operating modes. The modes are described
143 below.
145 The simplest mode is the so called B<local mode>. Data is collected locally and
146 written in RRD files that reside in I<DataDir>. This is the default mode when
147 collectd is linked against C<librrd>.
149 The modes B<client mode> and B<server mode> are used to send data over a
150 network and receive it again.
152 In B<client mode> the daemon collects the data locally and sends its results
153 to one or more network addresses. No RRD files are written locally in this
154 case. If collectd is not linked against C<librrd> this is the default mode.
156 If started in B<server mode> the daemon will listen on one or more interfaces
157 and write the data it receives to RRD files. No data is collected locally.
159 In the last mode, B<log mode>, data is collected locally and written in
160 text files that reside in I<DataDir>.
162 Please refer to L<collectd.conf(5)> for the configuration options and default
163 values.
165 =head1 SPECIAL PLUGINS
167 =head2 apache
169 This module connects to an Apache webserver and expects the output produced by
170 B<mod_status.c>. If requires B<libcurl> to set up the HTTP connection and issue
171 the request(s). The following is a sample config for the Apache webserver. The
172 use of C<ExtendedStatus on> is mandatory.
174 ExtendedStatus on
175 <IfModule mod_status.c>
176 <Location /mod_status>
177 SetHandler server-status
178 </Location>
179 </IfModule>
181 This plugin requires further configuration. Please read L<collectd.conf(5)>.
183 =head2 cpufreq
185 This module reads F</sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq> (for
186 the first CPU installed) to get the current CPU frequency. If this file does
187 not exist make sure B<cpufreqd> (L<http://cpufreqd.sourceforge.net/>) or a
188 similar tool is installed and an "cpu governor" (that's kernel module) is
189 loaded.
191 =head2 email
193 This plugin collects data indirectly by providing a UNIX socket that external
194 programs can connect to. A simple line based protocol is used to communicate
195 with the plugin:
197 E-Mail type (e.g. "ham", "spam", "virus", ...) and size (bytes):
199 e:<type>:<size>
201 Spam score:
203 s:<value>
205 Successful spam checks (e.g. "BAYES_99", "SUBJECT_DRUG_GAP_C", ...):
207 c:<type1>[,<type2>,...]
209 Each line is limited to 256 characters (including the newline character).
210 Longer lines will be ignored.
212 =head2 mysql
214 Requires B<mysqlclient> to be installed. It connects to the database when
215 started and keeps the connection up as long as possible. When the connection is
216 interrupted for whatever reason it will try to re-connect. The syslog will
217 contain loud complaints in case anything goes wrong.
219 This plugin issues C<SHOW STATUS> and evaluates C<Bytes_{received,sent}>,
220 C<Com_*> and C<Handler_*> which correspond to F<traffic-mysql.rrd>,
221 F<mysql_commands-*.rrd> and F<mysql_handler-*.rrd>. Also, the values of
222 C<Qcache_*> are put in F<mysql_qcache.rrd> and values of C<Threads_*> are put
223 in F<mysql_threads.rrd>. Please refer to the B<MySQL reference manual>,
224 I<5.2.4. Server Status Variables> for an explanation of these values.
226 =head2 sensors
228 The B<sensors> module uses lm_sensors to retrieve sensor-values. This means
229 that all the needed modules have to be loaded and lm_sensors has to be
230 configured (most likely by editing F</etc/sensors.conf>. Read
231 L<sensors.conf(5)> for details.
233 The B<lm_sensors> homepage can be found at
234 L<http://secure.netroedge.com/~lm78/>.
236 =head2 hddtemp
238 To get values from B<hddtemp> collectd connects to B<localhost> (127.0.0.1),
239 port B<7634/tcp>. The B<Host> and B<Port> options can be used to change these
240 default values. See L<collectd.conf(5)> for details. C<hddtemp> has to be
241 running to work correctly. If C<hddtemp> is not running timeouts may appear
242 which may interfere with other statistics..
244 The B<hddtemp> homepage can be found at
245 L<http://www.guzu.net/linux/hddtemp.php>.
247 =head2 vserver
249 B<VServer> support is only available for Linux. It cannot yet be found in a
250 vanilla kernel, though. To make use of this plugin you need a kernel that has
251 B<VServer> support built in, i.e. you need to apply the patches and compile
252 your own kernel, which will then provide the /proc/virtual filesystem that is
253 required by this plugin.
255 The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
257 =head1 RRD FILES
259 The RRD files are created automatically. The size of the RRAs depend on the
260 compile time settings of I<step> and I<width>. With the default values (I<step>
261 = B<10>, I<width> = B<1200>) the following RRAs are created:
263 RRA:AVERAGE:0.1:1:8640
264 RRA:AVERAGE:0.1:50:1210
265 RRA:AVERAGE:0.1:223:1202
266 RRA:AVERAGE:0.1:2635:1201
267 RRA:MIN:0.1:1:8640
268 RRA:MIN:0.1:50:1210
269 RRA:MIN:0.1:223:1202
270 RRA:MIN:0.1:2635:1201
271 RRA:MAX:0.1:1:8640
272 RRA:MAX:0.1:50:1210
273 RRA:MAX:0.1:223:1202
274 RRA:MAX:0.1:2635:1201
276 By default collectd uses a 10 second I<step>. Thus the RRAs contain the
277 following timespans. If you've changed the I<step> at compile time you will
278 have calculate resolution and timespan yourself.
280 PDP per CDP | Resolution | Data points | Timespan
281 ------------+--------------+-------------+---------
282 1 | 10.0 seconds ! 8640 ! 1 day
283 50 | 8.3 minutes | 1210 | 1 week
284 223 | 37.2 minutes | 1202 | 1 month
285 2635 | 7.3 hours | 1201 | 1 year
287 The DS'es depend on the module creating the RRD files:
289 =over 4
291 =item Apache traffic (F<apache/apache_bytes.rrd>)
293 DS:count:COUNTER:HEARTBEAT:0:134217728
295 =item Apache requests (F<apache/apache_requests.rrd>)
297 DS:count:COUNTER:HEARTBEAT:0:1048576
299 =item Apache scoreboard (F<apache/apache_scoreboard-I<E<lt>nameE<gt>>.rrd>)
301 DS:count:GAUGE:HEARTBEAT:0:U
303 =item Apple temperature sensor (F<apple_sensors/temperature-I<E<lt>nameE<gt>>.rrd>)
305 DS:value:GAUGE:HEARTBEAT:U:U
307 =item Apple fanspeed sensor (F<apple_sensors/fanspeed-I<E<lt>nameE<gt>>.rrd>)
309 DS:value:GAUGE:HEARTBEAT:U:U
311 =item Battery charge (F<battery-I<E<lt>nameE<gt>>/charge.rrd>)
313 DS:charge:GAUGE:HEARTBEAT:0:U
315 =item Battery current (F<battery-I<E<lt>nameE<gt>>/current.rrd>)
317 DS:current:GAUGE:HEARTBEAT:U:U
319 =item Battery voltage (F<battery-I<E<lt>nameE<gt>>/voltage.rrd>)
321 DS:voltage:GAUGE:HEARTBEAT:U:U
323 =item CPU (F<cpu-I<E<lt>numE<gt>>.rrd>)
325 DS:user:COUNTER:HEARTBEAT:0:100
326 DS:nice:COUNTER:HEARTBEAT:0:100
327 DS:syst:COUNTER:HEARTBEAT:0:100
328 DS:idle:COUNTER:HEARTBEAT:0:100
329 DS:wait:COUNTER:HEARTBEAT:0:100
331 =item CPU frequency (F<cpufreq-I<E<lt>numE<gt>>.rrd>)
333 DS:value:GAUGE:HEARTBEAT:0:U
335 =item Mountpoints (F<df-I<E<lt>pathE<gt>>.rrd>)
337 DS:used:GAUGE:HEARTBEAT:0:U
338 DS:free:GAUGE:HEARTBEAT:0:U
340 =item Diskstats (F<disk-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
342 DS:rcount:COUNTER:HEARTBEAT:0:U
343 DS:rmerged:COUNTER:HEARTBEAT:0:U
344 DS:rbytes:COUNTER:HEARTBEAT:0:U
345 DS:rtime:COUNTER:HEARTBEAT:0:U
346 DS:wcount:COUNTER:HEARTBEAT:0:U
347 DS:wmerged:COUNTER:HEARTBEAT:0:U
348 DS:wbytes:COUNTER:HEARTBEAT:0:U
349 DS:wtime:COUNTER:HEARTBEAT:0:U
351 =item Diskstats (F<partition-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
353 DS:rcount:COUNTER:HEARTBEAT:0:U
354 DS:rbytes:COUNTER:HEARTBEAT:0:U
355 DS:wcount:COUNTER:HEARTBEAT:0:U
356 DS:wbytes:COUNTER:HEARTBEAT:0:U
358 =item E-Mail count (F<email/email-I<E<lt>typeE<gt>>.rrd>)
360 DS:count:GAUGE:HEARTBEAT:0:U
362 =item E-Mail size (F<email/email_size-I<E<lt>typeE<gt>>.rrd>)
364 DS:size:GAUGE:HEARTBEAT:0:U
366 =item HDD Temperature (F<hddtemp-I<E<lt>majorE<gt>>-I<E<lt>minorE<gt>>.rrd>)
368 DS:value:GAUGE:HEARTBEAT:U:U
370 =item System load (F<load.rrd>)
372 DS:shortterm:GAUGE:HEARTBEAT:0:100
373 DS:midterm:GAUGE:HEARTBEAT:0:100
374 DS:longterm:GAUGE:HEARTBEAT:0:100
376 =item Memory usage (F<memory.rrd>)
378 DS:used:GAUGE:HEARTBEAT:0:9223372036854775807
379 DS:free:GAUGE:HEARTBEAT:0:9223372036854775807
380 DS:buffers:GAUGE:HEARTBEAT:0:9223372036854775807
381 DS:cached:GAUGE:HEARTBEAT:0:9223372036854775807
383 =item MySQL commands and handlers (F<mysql_commands-I<E<lt>commandE<gt>>.rrd> and F<mysql_handler-I<E<lt>handlerE<gt>>.rrd>)
385 DS:value:COUNTER:HEARTBEAT:0:U
387 =item MySQL query cache (F<mysql_qcache.rrd>)
389 DS:hits:COUNTER:HEARTBEAT:0:U
390 DS:inserts:COUNTER:HEARTBEAT:0:U
391 DS:not_cached:COUNTER:HEARTBEAT:0:U
392 DS:lowmem_prunes:COUNTER:HEARTBEAT:0:U
393 DS:queries_in_cache:GAUGE:HEARTBEAT:0:U
395 =item MySQL threads (F<mysql_threads.rrd>)
397 DS:running:GAUGE:HEARTBEAT:0:U
398 DS:connected:GAUGE:HEARTBEAT:0:U
399 DS:cached:GAUGE:HEARTBEAT:0:U
400 DS:created:COUNTER:HEARTBEAT:0:U
402 =item NFSv2 Procedures (F<nfs2_procedures-I<(client|server)>.rrd>)
404 DS:null:COUNTER:HEARTBEAT:0:U
405 DS:getattr:COUNTER:HEARTBEAT:0:U
406 DS:setattr:COUNTER:HEARTBEAT:0:U
407 DS:root:COUNTER:HEARTBEAT:0:U
408 DS:lookup:COUNTER:HEARTBEAT:0:U
409 DS:readlink:COUNTER:HEARTBEAT:0:U
410 DS:read:COUNTER:HEARTBEAT:0:U
411 DS:wrcache:COUNTER:HEARTBEAT:0:U
412 DS:write:COUNTER:HEARTBEAT:0:U
413 DS:create:COUNTER:HEARTBEAT:0:U
414 DS:remove:COUNTER:HEARTBEAT:0:U
415 DS:rename:COUNTER:HEARTBEAT:0:U
416 DS:link:COUNTER:HEARTBEAT:0:U
417 DS:symlink:COUNTER:HEARTBEAT:0:U
418 DS:mkdir:COUNTER:HEARTBEAT:0:U
419 DS:rmdir:COUNTER:HEARTBEAT:0:U
420 DS:readdir:COUNTER:HEARTBEAT:0:U
421 DS:fsstat:COUNTER:HEARTBEAT:0:U
423 =item NFSv3 Procedures (F<nfs3_procedures-I<(client|server)>.rrd>)
425 DS:null:COUNTER:HEARTBEAT:0:U
426 DS:getattr:COUNTER:HEARTBEAT:0:U
427 DS:setattr:COUNTER:HEARTBEAT:0:U
428 DS:lookup:COUNTER:HEARTBEAT:0:U
429 DS:access:COUNTER:HEARTBEAT:0:U
430 DS:readlink:COUNTER:HEARTBEAT:0:U
431 DS:read:COUNTER:HEARTBEAT:0:U
432 DS:write:COUNTER:HEARTBEAT:0:U
433 DS:create:COUNTER:HEARTBEAT:0:U
434 DS:mkdir:COUNTER:HEARTBEAT:0:U
435 DS:symlink:COUNTER:HEARTBEAT:0:U
436 DS:mknod:COUNTER:HEARTBEAT:0:U
437 DS:remove:COUNTER:HEARTBEAT:0:U
438 DS:rmdir:COUNTER:HEARTBEAT:0:U
439 DS:rename:COUNTER:HEARTBEAT:0:U
440 DS:link:COUNTER:HEARTBEAT:0:U
441 DS:readdir:COUNTER:HEARTBEAT:0:U
442 DS:readdirplus:COUNTER:HEARTBEAT:0:U
443 DS:fsstat:COUNTER:HEARTBEAT:0:U
444 DS:fsinfo:COUNTER:HEARTBEAT:0:U
445 DS:pathconf:COUNTER:HEARTBEAT:0:U
446 DS:commit:COUNTER:HEARTBEAT:0:U
448 =item Network latency / Ping (F<ping-I<E<lt>hostnameE<gt>>.rrd>)
450 DS:ping:GAUGE:HEARTBEAT:0:65535
452 =item Processes (F<processes.rrd>)
454 DS:running:GAUGE:HEARTBEAT:0:65535
455 DS:sleeping:GAUGE:HEARTBEAT:0:65535
456 DS:zombies:GAUGE:HEARTBEAT:0:65535
457 DS:stopped:GAUGE:HEARTBEAT:0:65535
458 DS:paging:GAUGE:HEARTBEAT:0:65535
459 DS:blocked:GAUGE:HEARTBEAT:0:65535
461 =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>)
463 DS:value:GAUGE:HEARTBEAT:U:U
465 =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>)
467 DS:value:GAUGE:HEARTBEAT:U:U
469 =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>)
471 DS:voltage:GAUGE:HEARTBEAT:U:U
473 =item Serial port traffic (F<serial-I<E<lt>numE<gt>>.rrd>)
475 DS:incoming:COUNTER:HEARTBEAT:0:U
476 DS:outgoing:COUNTER:HEARTBEAT:0:U
478 =item Spam score (F<email/spam_score.rrd>)
480 DS:score:GAUGE:HEARTBEAT:0:U
482 =item Spam checks (F<email/spam_check-I<E<lt>typeE<gt>>.rrd>)
484 DS:hits:GAUGE:HEARTBEAT:0:U
486 =item Swap usage (F<swap.rrd>)
488 DS:used:GAUGE:HEARTBEAT:0:1099511627776
489 DS:free:GAUGE:HEARTBEAT:0:1099511627776
490 DS:cached:GAUGE:HEARTBEAT:0:1099511627776
491 DS:resv:GAUGE:HEARTBEAT:0:1099511627776
493 =item Tape drive usage (F<tape-I<E<lt>nameE<gt>>.rrd>)
495 DS:rcount:COUNTER:HEARTBEAT:0:
496 DS:rmerged:COUNTER:HEARTBEAT:0:U
497 DS:rbytes:COUNTER:HEARTBEAT:0:U
498 DS:rtime:COUNTER:HEARTBEAT:0:U
499 DS:wcount:COUNTER:HEARTBEAT:0:U
500 DS:wmerged:COUNTER:HEARTBEAT:0:U
501 DS:wbytes:COUNTER:HEARTBEAT:0:U
502 DS:wtime:COUNTER:HEARTBEAT:0:U
504 =item Network traffic (F<traffic-I<E<lt>interfaceE<gt>>.rrd>)
506 DS:incoming:COUNTER:HEARTBEAT:0:U
507 DS:outgoing:COUNTER:HEARTBEAT:0:U
509 =item Interface packets (F<if_packets-I<E<lt>interfaceE<gt>>.rrd>)
511 DS:rx:COUNTER:HEARTBEAT:0:U
512 DS:tx:COUNTER:HEARTBEAT:0:U
514 =item Interface errors (F<if_errors-I<E<lt>interfaceE<gt>>.rrd>)
516 DS:rx:COUNTER:HEARTBEAT:0:U
517 DS:tx:COUNTER:HEARTBEAT:0:U
519 =item Users (F<users.rrd>)
521 DS:users:GAUGE:HEARTBEAT:0:65535
523 =item VServer load (F<vserver-I<E<lt>xidE<gt>>/load.rrd>)
525 DS:shortterm:GAUGE:HEARTBEAT:0:100
526 DS:midterm:GAUGE:HEARTBEAT:0:100
527 DS:longterm:GAUGE:HEARTBEAT:0:100
529 =item VServer threads (F<vserver-I<E<lt>xidE<gt>>/threads.rrd>)
531 DS:total:GAUGE:HEARTBEAT:0:65535
532 DS:running:GAUGE:HEARTBEAT:0:65535
533 DS:uninterruptible:GAUGE:HEARTBEAT:0:65535
534 DS:onhold:GAUGE:HEARTBEAT:0:65535
536 =item VServer network traffic (F<vserver-I<E<lt>xidE<gt>>/traffic-I<E<lt>nameE<gt>>.rrd>)
538 DS:incoming:COUNTER:HEARTBEAT:0:9223372036854775807
539 DS:outgoing:COUNTER:HEARTBEAT:0:9223372036854775807
540 DS:failed:COUNTER:HEARTBEAT:0:9223372036854775807
542 =item VServer processes (F<vserver-I<E<lt>xidE<gt>>/vs_processes.rrd>)
544 DS:total:GAUGE:HEARTBEAT:0:65535
546 =item VServer memory usage (F<vserver-I<E<lt>xidE<gt>>/vs_memory.rrd>)
548 DS:vm:GAUGE:HEARTBEAT:0:9223372036854775807
549 DS:vml:GAUGE:HEARTBEAT:0:9223372036854775807
550 DS:rss:GAUGE:HEARTBEAT:0:9223372036854775807
551 DS:anon:GAUGE:HEARTBEAT:0:9223372036854775807
553 =item Wireless link quality (F<wireless-I<E<lt>interfaceE<gt>>.rrd>)
555 DS:quality:GAUGE:HEARTBEAT:0:U
556 DS:power:GAUGE:HEARTBEAT:U:0
557 DS:noise:GAUGE:HEARTBEAT:U:0
559 =back
561 =head1 SEE ALSO
563 L<collectd.conf(5)>, L<rrdtool(1)>, L<sensors(1)>, L<hddtemp(8)>,
564 L<kstat(3KSTAT)>
566 =head1 AUTHOR
568 Florian Forster E<lt>octo@verplant.orgE<gt>
570 =cut