X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=src%2Fcollectd-unixsock.pod;h=971cb36dc0a138a9c826d5148178714e57078b91;hb=da27344d819e431e74b15a638c91f8d0ff44125d;hp=d17852a79affe9d7f943c38069b2669fe1a39c50;hpb=c999f7e40b0e9ce8f5fd4eb2042d6f3adbd6ce1e;p=collectd.git diff --git a/src/collectd-unixsock.pod b/src/collectd-unixsock.pod index d17852a7..971cb36d 100644 --- a/src/collectd-unixsock.pod +++ b/src/collectd-unixsock.pod @@ -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,12 @@ 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. 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). @@ -174,6 +183,20 @@ Example: -> | PUTNOTIF type=temperature severity=warning time=1201094702 message=The roof is on fire! <- | 0 Success +=item B [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. B +may be specified multiple times - each occurrence applies to plugins listed +afterwards. + +If specified, only specific plugins are flushed. Otherwise all plugins +providing a flush callback are flushed. + +Example: + -> | FLUSH + <- | 0 Done + =back =head2 Identifiers @@ -191,26 +214,14 @@ some examples: 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. - =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