X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd-unixsock.pod;h=ac4a1b13fb4810b99e2fbc6f40ae853c27b1091f;hb=4027126a75439c7d2b1d5572092fd291ef19ead6;hp=d17852a79affe9d7f943c38069b2669fe1a39c50;hpb=9ebb82bf36ac779a8af81f2e9a513226387a5679;p=collectd.git diff --git a/src/collectd-unixsock.pod b/src/collectd-unixsock.pod index d17852a7..ac4a1b13 100644 --- a/src/collectd-unixsock.pod +++ b/src/collectd-unixsock.pod @@ -17,11 +17,11 @@ collectd-unixsock - Documentation of collectd's C The C opens an UNIX-socket over which one can interact with the daemon. This can be used to use the values collected by collectd in other -applications, such as monitoring, or submit externally collected values to -collectd. +applications, such as monitoring solutions, or submit externally collected +values to collectd. -This plugin is used by L to check if some value is in a -certain range and exit with a Nagios-compatible exit code. +For example, this plugin is used by L to check if some +value is in a certain range and exit with a Nagios-compatible exit code. =head1 COMMANDS @@ -29,6 +29,18 @@ Upon start the C opens a UNIX-socket and waits for connections. Once a connection is established the client can send commands to the daemon which it will answer, if it understand them. +In general the plugin answers with a status line of the following form: + +I I + +If I is greater than or equal to zero the message indicates success, +if I is less than zero the message indicates failure. I is a +human-readable string that further describes the return value. + +On success, I furthermore indicates the number of subsequent lines of +output (not including the status line). Each such lines usually contains a +single return value. See the description of each command for details. + The following commands are implemented: =over 4 @@ -36,37 +48,34 @@ The following commands are implemented: =item B I If the value identified by I (see below) is found the complete -value-list is returned. The response is a space separated list of -name-value-pairs: - -I IB<=>I[ IB<=>I[ ...]] - -If I is less then zero, an error occurred. Otherwise it contains the -number of values that follow. Each value is of the form IB<=>I. +value-list is returned. The response is a list of name-value-pairs, each pair +on its own line (the number of lines is indicated by the status line - see +above). Each name-value-pair is of the form IB<=>I. Counter-values are converted to a rate, e.Eg. bytes per second. Undefined values are returned as B. Example: -> | GETVAL myhost/cpu-0/cpu-user - <- | 1 value=1.260000e+00 + <- | 1 Value found + <- | value=1.260000e+00 =item B Returns a list of the values available in the value cache together with the time of the last update, so that querying applications can issue a B -command for the values that have changed. - -The first line's status number is the number of identifiers returned or less -than zero if an error occurred. Each of the following lines contains the -update time as an epoch value and the identifier, separated by a space. +command for the values that have changed. Each return value consists of the +update time as an epoch value and the identifier, separated by a space. The +update time is the time of the last value, as provided by the collecting +instance and may be very different from the time the server considers to be +"now". Example: -> | LISTVAL <- | 69 Values found - <- | 1182204284 leeloo/cpu-0/cpu-idle - <- | 1182204284 leeloo/cpu-0/cpu-nice - <- | 1182204284 leeloo/cpu-0/cpu-system - <- | 1182204284 leeloo/cpu-0/cpu-user + <- | 1182204284 myhost/cpu-0/cpu-idle + <- | 1182204284 myhost/cpu-0/cpu-nice + <- | 1182204284 myhost/cpu-0/cpu-system + <- | 1182204284 myhost/cpu-0/cpu-user ... =item B I [I] I @@ -83,12 +92,13 @@ plugin within collectd. I identifies the type and number of values (i.Ee. data-set) passed to collectd. A large list of predefined data-sets is available in the B file. -The I is an optional list of I, where each option if a +The I is an optional list of I, where each option is a key-value-pair. A list of currently understood options can be found below, all -other options will be ignored. +other options will be ignored. Values that contain spaces must be quoted with +double quotes. I is a colon-separated list of the time and the values, each either -an integer if the data-source is a counter, of a double if the data-source if +an integer if the data-source is a counter, or a double if the data-source is of type "gauge". You can submit an undefined gauge-value by using B. When submitting B to a counter the behavior is undefined. The time is given as epoch (i.Ee. standard UNIX time). @@ -133,10 +143,9 @@ Valid options are: =item BI (B) Sets the message of the notification. This is the message that will be made -accessible to the user, so it should contain some useful information. This -option must be the last option because the rest of the line will be its value, -even if there are spaces and equal-signs following it! This option is -mandatory. +accessible to the user, so it should contain some useful information. As with +all options: If the message includes spaces, it must be quoted with double +quotes. This option is mandatory. =item B|B|B (B) @@ -174,6 +183,26 @@ Example: -> | PUTNOTIF type=temperature severity=warning time=1201094702 message=The roof is on fire! <- | 0 Success +=item B [BI] [BI [...]] [BI [...]] + +Flushes all cached data older than I seconds. If no timeout has been +specified, it defaults to -1 which causes all data to be flushed. + +If the B option has been specified, only the I plugin will be +flushed. You can have multiple B options to flush multiple plugins in +one go. If the B option is not given all plugins providing a flush +callback will be flushed. + +If the B option is given only the specified values will be flushed. +This is meant to be used by graphing or displaying frontends which want to have +the lastest values for a specific graph. Again, you can specify the +B option multiple times to flush several values. If this option is +not specified at all, all values will be flushed. + +Example: + -> | FLUSH plugin=rrdtool identifier=localhost/df/df-root identifier=localhost/df/df-var + <- | 0 Done: 2 successful, 0 errors + =back =head2 Identifiers @@ -183,34 +212,24 @@ Value or value-lists are identified in a uniform fashion: I/I/I Where I and I are both either of type "I" or -"I-I". This sounds more complicated than it is, so here are +"I-I". If the identifier includes spaces, it must be quoted +using double quotes. This sounds more complicated than it is, so here are some examples: myhost/cpu-0/cpu-user myhost/load/load myhost/memory/memory-used myhost/disk-sda/disk_octets - -=head2 Return values - -Unless otherwise noted the plugin answers with a line of the following form: - -I I - -If I is zero the message indicates success, if I is non-zero the -message indicates failure. I is a human-readable string that describes -the return value further. - -Commands that return values may use I to return the number of values that -follow, such as the B command. These commands usually return a negative -value on failure and never return zero. + "myups/snmp/temperature-Outlet 1" =head1 ABSTRACTION LAYER -Shipped with the sourcecode comes the Perl-Module L which +B ships the Perl-Module L which provides an abstraction layer over the actual socket connection. It can be -found in the directory F. If you want to use Perl to -communicate with the daemon, you're encouraged to use and expand this module. +found in the directory F in the source distribution or +(usually) somewhere near F if you're using a package. If +you want to use Perl to communicate with the daemon, you're encouraged to use +and expand this module. =head1 SEE ALSO