X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd.pod;h=5e4b3b24e8c7e8352a47d0e567fa456dcd40ab26;hb=79c9bbd7a08532936e9c229e41d1d9201d7b7f21;hp=d926017bbb6d1cbdae48793587d52c3bd46e9f44;hpb=50cadef109fdefb91794ab2e059f6a295fd7136b;p=collectd.git diff --git a/src/collectd.pod b/src/collectd.pod index d926017b..5e4b3b24 100644 --- a/src/collectd.pod +++ b/src/collectd.pod @@ -8,358 +8,219 @@ collectd I<[options]> =head1 DESCRIPTION -collectd is a daemon that collects various system statistics periodically and -stores them into RRD-files. Which data is collected depends on compile-time -settings. The following features may be available: +collectd is a daemon that receives system statistics and makes them available +in a number of ways. The main daemon itself doesn't have any real functionality +appart from loading, querying and submitting to plugins. For a description of +available plugins please see L below. -=over 4 - -=item - -CPU utilization (I) - -=item - -Mountpoint usage (I) - -=item - -Disk and partition usage/throughput (I) - -=item - -Harddisk temperatures (I) +=head1 OPTIONS -=item +Most of collectd's configuration is done using using a configfile. See +L for an in-depth description of all options. -System load averages (I) +=over 4 -=item +=item B<-C> Iconfig-fileE> -Memory usage (I) +Specify an alternative config file. This is the place to go when you wish to +change B's behavior. The path may be relative to the current working +directory. -=item +=item B<-P> Ipid-fileE> -MySQL statistics (I) +Specify an alternative pid file. This overwrites any settings in the config +file. This is thought for init-scripts that require the PID-file in a certain +directory to work correctly. For everyday-usage use the B +config-option. -=item +=item B<-f> -NFS utilization (I, Linux only) +Don't fork to the background. I will also B close standard file +descriptors, detach from the session nor write a pid file. This is mainly +thought for 'supervisioning' init replacements such as I. -=item +=item B<-h> -Network latency (I) +Output usage information and exit. -=item +=back -Number of processes (I, Linux only) +=head1 PLUGINS -=item +As noted above, the real power of collectd lies within it's plugins. There are +two big groups of plugins, B and B plugins: -lm_sensors information (I, Linux only) +=over 4 =item -Serial port traffic (I, Linux only) +Input plugins are queried periodically. They somehow aquire the current value +of whatever they where designed to work with and submit these values back to +the daemon, i. e. they "dispatch" the values. As an example, the C +reads the current cpu-counters of time spent in the various modes (user, +system, nice, ...) and dispatches these counters to the daemon. =item -Swap usage (I) +Output plugins get the dispatched values from the daemon and does something +with them. Common applications are writing to RRD-files, CSV-files or sending +the data over a network link to a remote box. -=item +=back -Tape drive usage (I, Solaris only) +Of course not all plugins fit neatly into one of the two above categories. The +C, for example, is able to send (i.Ee. "write") B +receive (i.Ee. "dispatch") values. Also, it opens a socket upon +initialization and dispatches the values when it receives them and isn't +triggered at the same time the input plugins are being read. You can think if +the network receive part as working asynchronous if it helps. -=item +In addition to the above, there are "logging plugins". Right now those are the +C and the C. With these plugins collectd can +provide information about issues and significant situations to the user. +Several loglevels let you suppress uninteresting messages. -Network traffic (I) +Please note that some plugins, that provide other means of communicating with +the daemon, have manpages of their own to describe their functionality in more +detail. In particular those are L, L, +... -=item +=head1 SPECIAL PLUGINS -Number of users logged into the system (I) +=head2 perl -=back +The C includes a Perl-interpreter in collectd and provides +Perl-equivalents of the plugin-functions. This makes it possible to write +plugins in Perl. -=head1 OPTIONS +There are two more complex types you need to know about: =over 4 -=item B<-C> Iconfig-fileE> +=item Data-Set -Specify an alternative config file. This is the place to go when you wish to -change B's behavior. The path may be relative to the current working -directory. +A data-set is a list of one or more data-sources. Each data-source defines a +name, type, min- and max-value and the data-set wraps them up into one +structure. The general layout looks like this: -=item B<-f> + [{ + name => 'data_source_name', + type => DS_TYPE_COUNTER || DS_TYPE_GAUGE + min => value || undef, + max => value || undef + }, ...] -Don't fork to the background. I will also B close standard file -descriptors, detach from the session nor write a pid file. This is mainly -thought for 'supervisioning' init replacements such as I. +=item Value-List -=item B<-h> +A value-list is one structure which features an array of values and fields to +identify the values, i. e. time and host, plugin name and plugin-instance as +well as a type and type-instance. Since the "type" is not included in the +value-list but is passed as an extra argument, the general layout looks like +this: -Output usage information and exit. + { + values => [123, 0.5], + time => time (), + host => 'localhost', + plugin => 'myplugin', + plugin_instance => '', + type_instance => '' + } =back -=head1 RRD FILES - -The RRD files are created automatically with the following RRAs: - - RRA:AVERAGE:0.2:6:1500 - RRA:AVERAGE:0.1:180:1680 - RRA:AVERAGE:0.1:2160:1520 - RRA:MIN:0.2:6:1500 - RRA:MIN:0.1:180:1680 - RRA:MIN:0.1:2160:1520 - RRA:MAX:0.2:6:1500 - RRA:MAX:0.1:180:1680 - RRA:MAX:0.1:2160:1520 - -Since collectd uses a 10 second I the RRAs contain the following -timespans: - - Resolution | Data points | Timespan - -----------+-------------+---------- - 60 seconds | 1500 | 25 hours - 30 minutes | 1680 | 35 days - 6 hours | 1520 | 380 days - -The DS'es depend on the module creating the RRD files: +The following functions provide the C-interface to Perl-modules: =over 4 -=item CPU (FnumE>.rrd>) - - DS:user:COUNTER:25:0:100 - DS:nice:COUNTER:25:0:100 - DS:syst:COUNTER:25:0:100 - DS:idle:COUNTER:25:0:100 - DS:wait:COUNTER:25:0:100 - -=item Mountpoints (FpathE>.rrd>) - - DS:used:GAUGE:25:0:U - DS:free:GAUGE:25:0:U - -=item Diskstats (FmajorE>-IminorE>.rrd>) - - DS:rcount:COUNTER:25:0:U - DS:rmerged:COUNTER:25:0:U - DS:rbytes:COUNTER:25:0:U - DS:rtime:COUNTER:25:0:U - DS:wcount:COUNTER:25:0:U - DS:wmerged:COUNTER:25:0:U - DS:wbytes:COUNTER:25:0:U - DS:wtime:COUNTER:25:0:U - -=item Diskstats (FmajorE>-IminorE>.rrd>) - - DS:rcount:COUNTER:25:0:U - DS:rbytes:COUNTER:25:0:U - DS:wcount:COUNTER:25:0:U - DS:wbytes:COUNTER:25:0:U - -=item HDD Temperature (FmajorE>-IminorE>.rrd>) - - DS:value:GAUGE:25:U:U - -=item System load (F) - - DS:shortterm:GAUGE:25:0:100 - DS:midterm:GAUGE:25:0:100 - DS:longterm:GAUGE:25:0:100 - -=item Memory usage (F) - - DS:used:GAUGE:25:0:9223372036854775807 - DS:free:GAUGE:25:0:9223372036854775807 - DS:buffers:GAUGE:25:0:9223372036854775807 - DS:cached:GAUGE:25:0:9223372036854775807 +=item B (I, I, I) -=item MySQL statistics (FcommandE>.rrd> and FhandlerE>.rrd>) +Registers a callback-function or data-set. - DS:value:COUNTER:25:0:U +I can be one of: -=item NFSv2 Procedures (F.rrd>) - - DS:null:COUNTER:25:0:U - DS:getattr:COUNTER:25:0:U - DS:setattr:COUNTER:25:0:U - DS:root:COUNTER:25:0:U - DS:lookup:COUNTER:25:0:U - DS:readlink:COUNTER:25:0:U - DS:read:COUNTER:25:0:U - DS:wrcache:COUNTER:25:0:U - DS:write:COUNTER:25:0:U - DS:create:COUNTER:25:0:U - DS:remove:COUNTER:25:0:U - DS:rename:COUNTER:25:0:U - DS:link:COUNTER:25:0:U - DS:symlink:COUNTER:25:0:U - DS:mkdir:COUNTER:25:0:U - DS:rmdir:COUNTER:25:0:U - DS:readdir:COUNTER:25:0:U - DS:fsstat:COUNTER:25:0:U - -=item NFSv3 Procedures (F.rrd>) - - DS:null:COUNTER:25:0:U - DS:getattr:COUNTER:25:0:U - DS:setattr:COUNTER:25:0:U - DS:lookup:COUNTER:25:0:U - DS:access:COUNTER:25:0:U - DS:readlink:COUNTER:25:0:U - DS:read:COUNTER:25:0:U - DS:write:COUNTER:25:0:U - DS:create:COUNTER:25:0:U - DS:mkdir:COUNTER:25:0:U - DS:symlink:COUNTER:25:0:U - DS:mknod:COUNTER:25:0:U - DS:remove:COUNTER:25:0:U - DS:rmdir:COUNTER:25:0:U - DS:rename:COUNTER:25:0:U - DS:link:COUNTER:25:0:U - DS:readdir:COUNTER:25:0:U - DS:readdirplus:COUNTER:25:0:U - DS:fsstat:COUNTER:25:0:U - DS:fsinfo:COUNTER:25:0:U - DS:pathconf:COUNTER:25:0:U - DS:commit:COUNTER:25:0:U +=over 4 -=item Network latency / Ping (FhostnameE>.rrd>) +=item TYPE_INIT - DS:ping:GAUGE:25:0:65535 +=item TYPE_READ -=item Processes (F) - - DS:running:GAUGE:25:0:65535 - DS:sleeping:GAUGE:25:0:65535 - DS:zombies:GAUGE:25:0:65535 - DS:stopped:GAUGE:25:0:65535 - DS:paging:GAUGE:25:0:65535 - DS:blocked:GAUGE:25:0:65535 - -=item lm_sensors (FchipE>-IfeatureE>.rrd>) +=item TYPE_WRITE - DS:value:GAUGE:25:U:U - -=item Serial port traffic (FnumE>.rrd>) - - DS:incoming:COUNTER:25:0:U - DS:outgoing:COUNTER:25:0:U - -=item Swap usage (F) +=item TYPE_LOG - DS:used:GAUGE:25:0:1099511627776 - DS:free:GAUGE:25:0:1099511627776 - DS:cached:GAUGE:25:0:1099511627776 - DS:resv:GAUGE:25:0:1099511627776 - -=item Tape drive usage (FnameE>.rrd>) +=item TYPE_SHUTDOWN - DS:rcount:COUNTER:25:0: - DS:rmerged:COUNTER:25:0:U - DS:rbytes:COUNTER:25:0:U - DS:rtime:COUNTER:25:0:U - DS:wcount:COUNTER:25:0:U - DS:wmerged:COUNTER:25:0:U - DS:wbytes:COUNTER:25:0:U - DS:wtime:COUNTER:25:0:U - -=item Network traffic (FnameE>.rrd>) - - DS:incoming:COUNTER:25:0:U - DS:outgoing:COUNTER:25:0:U - -=item Users (F) - - DS:users:GAUGE:25:0:65535 +=item TYPE_DATASET =back -=head1 MODES +I is the name of the callback-function or the type of the data-set, +depending on the value of I. (Please note that the type of the data-set +is the value passed as I here and has nothing to do with the I +argument which simply tells B what is being registered.) -By default collectd starts in the so called I which is not very -interesting. It collects data and writes it into RRD files in -F. There's nothing special so I won't discuss that in more -detail.. +The last argument, I, is either a function- or an array-reference. If +I is B, then the I argument must be an +array-reference which points to an array of hashes. Each hash describes one +data-source. For the exact layout see B above. -Please be aware that B. A -later declaration overrides earlier ones. I will start in -server-mode. If you want statistics of the server too you will have to start a -client process as well. +If the I argument is any of the other types (B, B, +...) then I is expected to be a function reference. These functions are +called in the various stages of the daemon and are passed the following +arguments: -Starting with version 3 collectd may send data over a network. As common with -network stuff there are two modes: A I and a I. Since one -usually has many senders and only a few listeners the sender is also called -I (using the option B<-c>) and the listener is called I (using -the option B<-s>). +=over 4 -Communication happends using the (IPv4) multicast group B<239.192.74.66> and -packets sent to the port B<25826/udp>. Every ten seconds the I queries -all the modules and sends the collected data to the multicast group. The -I subscribes to the multicast group upon startup and then waits for -incoming packets. As it receives the packets it checks wether it has the -neccessary module and, if found, writes the data to an RRD file, creating -directories and files as needed. +=item TYPE_INIT -The multicast group used is within the I as defined -by L. Addresses within that space are meant to be routed within an AS -but not to the outside. However collectd cannot control this and won't try. So -it's totally up to you to secure your net. +=item TYPE_READ -The UDP port used has been checked to not be assigned by the IANA. +=item TYPE_SHUTDOWN -On multi-homed machines you may need to add a route to the multicast net -(B<224.0.0.0/4>) if multicast packages take the wrong interface. The listener -on the other hand listens on B interfaces. +No arguments are passed -=head1 SPECIAL PLUGINS +=item TYPE_WRITE -=head2 cpufreq +The arguments passed are I, I, and I. I is a +string. For the layout of I and I see above. -This module reads F (for -the first CPU installed) to get the current CPU frequency. If this file does -not exist make sure B (L) or a -similar tool is installed. +=item TYPE_LOG -=head2 mysql +The arguments are I and I. The log level is small for +important messages and high for less important messages. The least important +level is B, the most important level is B. In between there +are (from least to most important): B, B, and +B. I is simply a string B a newline at the end. -Requires B to be installed. It connects to the database when -started and keeps the connection up as long as possible. When the connection is -interrupted for whatever reason it will try to re-connect. The syslog will -contain loud complaints in case anything goes wrong. +=back -This plugin issues C and evaluates C, -C and C which correspond to F, -F and F. Please refer to the B, I<5.2.4. Server Status Variables> for an explanation of -these values. +=item B (I, I) -=head2 sensors +Removes a callback or data-set from collectd's internal list of +functionsE/ datasets. -The B module uses lm_sensors to retrieve sensor-values. This means -that all the needed modules have to be loaded and lm_sensors has to be -configured (most likely by editing F. Read -L for details. +=item B (I, I) -The B homepage can be found at -L. +Submits a I of type I to the daemon. If the data-set I +is found (and the number of values matches the number of data-sources) then the +type, data-set and value-list is passed to all write-callbacks that are +registered with the daemon. -=head2 hddtemp +=item B (I, I) -To get values from B collectd connects to B (127.0.0.1), -port B<7634/tcp>. hddtemp has to be running to work correctly. If hddtemp is -not running timeouts may appear which may interfere with other statistics.. +Submits a I of level I to collectd's logging mechanism. +The message is passed to all log-callbacks that are registered with collectd. -The B homepage can be found at -L. +=back =head1 SEE ALSO -L, L, L, L, -L +L, +L, +L, +L, +L =head1 AUTHOR