When monitoring something (a service, for example) it is rare that the current status is described by a single metric. Although you might only want a tiny subset of the available information, the current status is usually described by a vast slew of data. We want a convenient concept that allows the data to be grouped together, allowing easy selection of the interesting subsets.

A datatree is a collection of related information. As the name suggests, the metrics are held in a tree structure, analogous to a filesystem. A datatree has branches (like “directories” or “folders”) each of which contains measurements (like files) and further branches. In general, branches are generic concepts and the data underneath the branches are measurements of the generic concept.

A typical datatree is represented below. Here, the Threads branch contains data related to the generic concept of threads, each of which might be undertaking one of several different activites. The data underneath the Threads branch (waiting, starting, etc.) are the number of threads in the respective state (“waiting for a connection”, “starting up”, etc..)

Apache
 |
 +--Workers
 |   |
 |   +--busy: 1
 |   |
 |   +--idle: 49
 |
 +--Threads
     |
     +--waiting: 49
     |
     +--starting: 0
     |
     +--reading: 0
     |
     +--replying: 1
     |
     +--keep-alive: 0
     |
     +--dns: 0
     |
     +--closing: 0
     |
     +--logging: 0
     |
     +--graceful exit: 0
     |
     +--idle: 0
     |
     +--unused: 0

Each item of data is usually referred to by its full path separated by periods (.), excluding the root node. For example, the number of Apache threads currently replying with requested information is Threads.replying. In the above example, Threads.replying has a value of 1.

Each metric has multiple elements of metadata. They all have a name (e.g., Threads.replying), a value (1 for Threads.replying in above example), a type (integer, floating-point number, string, etc...), a string describing in what units the measurement was taken (with numerical data and where appropriate) and some additional binary metadata such as whether the information is static, a counter or reflects current status.

Datatrees can be combined to form larger datatrees; or subtrees can be selected, limiting the information delivered. Details of how to do this are given in Section 3.6.1, “The read attribute”.