The Archiveopteryx monitoring protocol

It is perhaps wrong to describe it as a protocol. You connect to a port and receive a data dump, then Archiveopteryx closes the connection.

The data dump consists of one or more lines, each describing a single variable. A variable is described as a name, a space, and one or more data points. A data point is a time, a colon, and a value. Here is an abbreviated example:

successful-logins 1200483945:453 1200483953:453 1200483954:454

The name may contain a-z, 0-9 and hyphen (-). The time is a unix time (1200483954 is sometime on 2001-01-16) and the value is a number. In the case of successful-logins, the number counts how many IMAP, POP and SMTP connections have successfully authenticated since the server started.

If a value doesn't change, Archiveopteryx leaves out some times in order to abbreviate the output. In the example above, the value was 453 from 1200483945 to 1200483953 inclusive. Archiveopteryx never leaves out more than 28 seconds, so if a value is unchanged for ten minutes, you get about twenty repetitions.

A variable may be omitted from the dump if it hasn't been used since the server started. (In fact the monitoring subsystem doesn't know a variable exists until its value is recorded for the first time.)

For the moment, Archiveopteryx delivers data for the most recent 16 minutes, so you should retrieve the data every 15 minutes. We may change the period in a future release if there is a really good reason.

ABNF syntax

This syntax uses ABNF as defined in RFC 5234, including the core rules from Appendix B.1.

dump = 1*variable
variable = name 1*960(SP time ":" value) CRLF
name = 1*(%x61-7a / DIGIT / "-") 
time = 1*DIGIT
value = 1*DIGIT

The number 960 is subject to change.

Relevant links

About this page

Last modified: 2010-11-19