XML status is a project to represent the state of health of a system (such as a datalogger) and its constituent components as a tree structure, which is encoded as an XML document. The tree is split into hardware or software functional groups, termed modules, and information about modules is organised into readings (perhaps through the use of lists). The actual state of health information is encoded by means of an integral normalised status value.
Within Platinum firmware, the XML document may be retrieved via XMLRPC by an automatic collection system, or it may be displayed on the web interface in a manner that allows a user to get a very quick overview of the current system state:
The tree can be considered as follows:
module (XML: <module>)
reading (XML: <reading>)
list (XML: <list>)
list item (XML: <list-item>)
reading
list
…
list item
…
…
module
…
The top-level container element is <xml-status>. It may
only contain zero or more <module> elements.
Modules, readings, lists and list items each have an attribute named
path. This allows a persistent identifier to be built up for a
given status reading. The path to a specific reading is built up appending the
paths of its parent elements using a period character ‘.’ as a
separator.
Modules, readings, lists and list items have a status attribute
which expresses a normalised interpretation of the status (see normalised status).
Modules, readings, lists and list items have a title attribute
which gives a human-readable title for the tree node. They also have a
display-primary attribute which, if true or omitted,
hints to a display agent that this part of the tree should be displayed; if
false, hints to a display agent this part of the tree should be
hidden unless explicitly requested (i.e. a mundane detail).
The value of a reading is taken to be the content of the XML element. A
reading may also have a units attribute, iff the value is a number
with a dimension that is an SI unit. It gives the SI abbreviation for the
dimension (e.g. V for volts or ms¯¹ for metres per second; note the Unicode
characters used to represent the order of the dimensions). SI prefixes must not
be used (e.g. readings should be in V, not µV, even if that means exponential
notation is required for readability of the value).
A RELAX NG schema has been prepared for fully describing the format of the XML, along with a simple example file:
If running a unit with Platinum firmware, the XML status information may be retrieved manually by navigating to the web interface of the unit and, on the very front page, pressing the "Download as XML" button at the bottom. It may also be retrieved automatically by sending an XMLRPC request to:
http://unit_hostname/cgi-bin/xmlrpc-status.cgi
with a method call xmlstatus_get (no arguments). This will
return the XML status file as a string. This may be tested quickly under Linux
if the xmlrpc-c development package (Ubuntu/Debian: libxmlrpc-c3-dev) is installed with the following command:
xmlrpc http://dcm105.platinum.guralp.com/cgi-bin/xmlrpc-status.cgi xmlstatus_get
Alternatively, it may be retrieved via ssh simply by running
the command xmlstatus, so on a Linux system it can be retrieved
from a remote system by running the command below. This can be made more
convenient (not asking for a password) if ssh keys are installed:
ssh unit_hostname xmlstatus
XML status is intended to capture enough information about the state of health of a system to be able to diagnose problems from a single XML file. However, a lot of this information will be redundant or disinteresting in normal operation, and as XML status is also presented to the user it could lead to important details being hidden among mundane ones. To counter this, each element may be classified as display primary (the default) or display secondary. Elements which are display secondary are typically hidden by the display agent.
To record whether an element is display primary or display secondary,
add an attribute display-primary with a value of either
true or false. If omitted, the value of this
attribute is assumed to be true.
At the first level of the tree, there is a list of modules. Each
entry in this list is represented by a <module> element, and
should correspond to one software or hardware component. For example, the
Platinum firmware uses a single module for each running SEEDlink server, a
single module for each serial port configured to acquire data from Güralp
digitisers, etc.
Modules, readings, lists and list items have a status attribute
which expresses a normalised interpretation of the status. This is an integer
value which allows an automatic system to monitor and evaluate the system's own
interpretation of its state of health. Integer values are interpreted as
follows:
| Value | Meaning | Example |
|---|---|---|
| Value | Meaning | Example |
| -1 | No status, good or bad, can be inferred. | System uptime. |
| 0 | Complete failure (display as red). | Last flush to disk operation failed. |
| 1–39 | Bad (display as red). Needs action. | No GSTM clients connected. |
| 40–69 | Not good (display as yellow/orange). Should be investigated. | No GPS lock for < 1 hour. |
| 70–99 | Good (display as green). | GPS was locked < 5 minutes ago. |
| 100 | Perfect operation (display as green). | GPS is locked now. |
If a <reading> element does not have a normalised status
value, then it is taken to be -1. However, if a <list-item>,
<list> or <module> element does not have
an explicit status attribute, then the value is taken to be the
worst of any of its constituent, display-primary elements (or -1 if
there are no such elements).
Each reading has an associated path which is a way of referring to
the specific reading within any tree. For example, this would allow a program
to monitor a known set of variables (e.g. GPS fix) from multiple different
dataloggers. The full path to a reading is created by concatenating all of the
paths of the nodes in the tree with a period character ‘.’, e.g.:
<xml-status>
<module path='module' ...>
<list path='client' ...>
<list-item path='12345678' ...>
<reading path='foo' ...>
Here, the reading node would have a path of
module.client.12345678.foo . As can be seen, the path is
taken from the path XML attribute of the
<module>, <list>,
<list-item> and <reading> elements.
Each <module>, <list>,
<list-item> and <reading> element
has a title attribute which is displayed to the user. This is a
human-readable string (generally unchanging) which describes the meaning of
the element. The title will generally be displayed directly to the user
by the display agent.