UDP Interface

This is a write-only interface. It uses UDP and the protocol is plain text. The protocol is fairly simple:

<type> <length>|<key> <value>[ timestamp];
  • gauge
  • derive
  • counter
  • absolute

The size of the key string;


Any string (ascii encoded), up to 255 characters;


Any double value (e.g.: 0.0, nan, 3.2e12);


[optional] the unix timestamp you want to store this event. If you don’t provide this value the server will use the current timestamp;

There is no ack [=confirmation the event was received], nor authentication, nor checksum [application level] whatsoever. If you need such a feature, use a different protocol [e.g. collectd].

N.B.: There is no trailing newline here. Adding a trailing newline is a parser error.


The UDP protocol is also capable of receiving a PING message that can use used to test connectivity. The syntax is as follows:



Assuming you have netcat, and the server up and running, the following shell commands should work:

# the ping message
$ echo ping                                      | nc -u localhost 6968

$ echo -n "gauge 10|example.e0 0.75 1350332001;" | nc -u localhost 6968
$ echo -n "derive 10|example.e0 0.76;"           | nc -u localhost 6968

Legacy udp protocol

This protocol is deprecated. It will be removed in future releases:

<name>: <value>[ timestamp]\n