Plain text protocol

From collectd Wiki
(Redirected from LISTVAL)
Jump to: navigation, search

Description

This page described the plain text protocol used by some plugins to provide communication channels to the outside world. Using this protocol it is possible to submit statistics and notifications to the daemon as well as query the current value of collected statistics. Plugins currently using this protocol are Exec (partially) and UnixSock. A client-side implementation of this protocol is available as the collectdclient library starting with version 4.6.

Replies

Let's start with the replies, because they are simple and generic: Upon each request, the server answers with a one-line status message and possibly additional lines. The status message consists of a numeric status code, a space and a informative message.

For example: 

42 Answer to Life, the Universe, and Everything.

The status code is less than zero to signal failure and greater than or equal to zero to signal success. If the value is greater than or equal to zero, it indicates the number of lines that are following the initial status message.

For example: 

3 Success
foo
bar
baz

Note that these status messages are never actually passed to the Exec plugin. If you write a script or program to be used with the Exec plugin, you don't have to worry about return values at all.

Requests

Now that we know how the daemon will answer, let's see what we can ask it.

Please note, what full request message must be limited to 1024 bytes, otherwise request will fail and you get message "Parsing options failed".

GETVAL

Synopsis

GETVAL Identifier

Description

If the value identified by Identifier is found the complete value-list is returned. If the Identifier contains any spaces, it must be enclosed in double quotes. 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 name=value. Counter-values are converted to a rate, e. g. bytes per second. Undefined values are returned as "NaN".

Example

-> | GETVAL "myhost/cpu-0/cpu-user"
<- | 1 Value found
<- | value=1.260000e+00

Implemented by

LISTVAL

Synopsis

LISTVAL

Description

Returns a list of the values available in the value cache together with the time of their last update, so that querying applications can issue a GETVAL 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 myhost/cpu-0/cpu-idle
<- | 1182204284 myhost/cpu-0/cpu-nice
<- | 1182204284 myhost/cpu-0/cpu-system
<- | 1182204284 myhost/cpu-0/cpu-user
     ...

Implemented by

PUTVAL

Synopsis

PUTVAL Identifier [OptionList] Valuelist

Description

Submits one or more values (identified by Identifier) to the daemon which will dispatch it to all its write plugins.

The OptionList is an optional list of Options, where each option is a key-value-pair. A list of currently understood options can be found below, all other options will be ignored. Values that contain spaces must be quoted with double quotes.

Valuelist is a colon-separated list of the time and the values, each either an unsigned integer if the data source is of type COUNTER or ABSOLUTE(*), a signed integer if the data source is of type DERIVE(*) or a double if the data source is of type GAUGE. You can submit an undefined GAUGE value by using “U”. When submitting “U” to a COUNTER the behavior is undefined. The time is given as epoch (i. e. standard UNIX time). You can use “N” instead of a time in epoch which is interpreted as “now”.

You can mix options and values, but the order is important: Options only effect following values, so specifying an option as last field is allowed, but useless. Also, an option applies to all following values, so you don’t need to re-set an option over and over again.

(*) The ABSOLUTE and DERIVE data source types have been added in Version 4.8.

Options

The currently defined Options are:

  • interval=seconds
    Gives the interval in which the data identified by Identifier is being collected.

Example

-> | PUTVAL "testhost/interface/if_octets-test0" interval=10 1179574444:123:456
<- | 0 Success

Implemented by

PUTNOTIF

Synopsis

PUTNOTIF [OptionList] message=Message

Description

Submits a notification to the daemon which will then dispatch it to all plugins which have registered for receiving notifications.

The PUTNOTIF command is followed by a list of options which further describe the notification. The message option is special in that it will consume the rest of the line as its value. The message, severity, and time options are mandatory.

Options

Valid options are:

  • message=Message (Required)
    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. As with all options: If the message includes spaces, it must be quoted with double quotes. This option is mandatory.
  • severity=failure|warning|okay (Required)
    Sets the severity of the notification. This option is mandatory.
  • time=Time (Required)
    Sets the time of the notification. The time is given as "epoch", i. e. as seconds since January 1st, 1970, 00:00:00. This option is mandatory.
  • host=Hostname
  • plugin=Plugin
  • plugin_instance=Plugin-Instance
  • type=Type
  • type_instance=Type-Instance
    These "associative" options establish a relation between this notification and collected performance data. This connection is purely informal, i. e. the daemon itself doesn't do anything with this information. However, websites or GUIs may use this information to place notifications near the affected graph or table. All the options are optional, but plugin_instance without plugin or type_instance without type doesn't make much sense and should be avoided.

Example

-> | PUTNOTIF type=temperature severity=warning time=1201094702 message="The roof is on fire!"
<- | 0 Success

Implemented by

FLUSH

Synopsis

FLUSH [timeout=Timeout] [plugin=Plugin [...]] [identifier=Ident [...]]

Description

Flushes all cached data older than Timeout seconds. If no timeout has been specified, it defaults to "−1" which causes all data to be flushed.

If the plugin option has been specified, only the Plugin plugin will be flushed. You can have multiple plugin options to flush multiple plugins in one go. If the plugin option is not given all plugins providing a flush callback will be flushed.

If the identifier option is given only the specified values will be flushed. This is meant to be used by graphing or displaying front-ends which want to have the latest values for a specific graph. Again, you can specify the identifier 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

Implemented by

GETTHRESHOLD

This command has been removed in version 5.0 due to changes in the threshold infrastructure!

Synopsis

GETTHRESHOLD Identifier

Description

Searched for a threshold for identifier and returns the configured limits if it is found. 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 “key: value”. Keys with undefined values are not returned at all.

Example

-> | GETTHRESHOLD "myhost/cpu-0/cpu-idle"
<- | 6 Threshold found
<- | Type: cpu
<- | Type Instance: idle
<- | Warning Min: 5
<- | Warning Max: 100
<- | Failure Min: 1
<- | Failure Max: 120

Implemented by

Abstraction layers

There are currently three libraries available which implement this protocol and provide a high level interface to the daemon.

libcollectdclient

The collectdclient library was added in version 4.6 and is installed automatically. It provides access to the daemon via this plain text protocol for C and C++ programs. Its main header file is src/libcollectdclient/client.h (installed to the package include directory), which is hopefully straight forward.

go-collectd

The collectd.org/exec Go package makes it easy to write PUTVAL to STDOUT: 

import (
        "collectd.org/api"
        "collectd.org/exec"
)

vl := api.ValueList{/* … */}
exec.Putval.Write(vl)

Alternatively, you can use the collectd.org/format Go package to write the metrics elsewhere, for example a UNIX socket: 

import (
        "io"

        "collectd.org/api"
        "collectd.org/format"
)

vl := api.ValueList{/* … */}

var w io.Writer // e.g. UNIX socket
f := format.NewPutval(w)
f.Write(vl)

Collectd::Unixsock

This Perl module provides a pure-Perl implementation of the above protocol. It is used for example by the contributed collection3 script to flush values just before creating the graph. Documentation is available as inline-POD, which you can access using: 

perldoc Collectd/Unixsock.pm

collectd-unixsock.py

This Python module provides a pure-Python interface for the LISTVAL and GETVAL commands. The other commands should be easy to add to this module, too. This file can be found at contrib/collectd-unixsock.py.

Retrieved from "https://www.collectd.org/wiki/index.php?title=Plain_text_protocol&oldid=4445#LISTVAL"