2006-10-02 18:22:13 -04:00
<?xml version='1.0' encoding='UTF-8'?>
2006-10-03 18:46:54 -04:00
< !DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM "xep.ent">
2006-10-02 18:22:13 -04:00
%ents;
]>
2006-10-03 18:46:54 -04:00
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep >
2006-10-02 18:22:13 -04:00
<header >
<title > Statistics Gathering</title>
<abstract > A protocol to enable gathering statistics from Jabber servers and components.</abstract>
&LEGALNOTICE;
<number > 0039</number>
<status > Deferred</status>
<type > Standards Track</type>
2007-01-14 22:38:19 -05:00
<sig > Standards</sig>
2006-10-02 18:22:13 -04:00
<author >
<firstname > Paul</firstname>
<surname > Curtis</surname>
<email > pcurtis@terrapin.com</email>
<jid > pcurtis@www.terrapin.com</jid>
</author>
<author >
<firstname > Russell</firstname>
<surname > Davis</surname>
<email > ukscone@burninghorse.com</email>
<jid > ukscone@burninghorse.com</jid>
</author>
<author >
<firstname > Ryan</firstname>
<surname > Eatmon</surname>
<email > reatmon@jabber.org</email>
<jid > reatmon@jabber.org</jid>
</author>
<author >
<firstname > David</firstname>
<surname > Sutton</surname>
<email > dsutton@legend.co.uk</email>
<jid > peregrine@legend.net.uk</jid>
</author>
<revision >
<version > 0.6.0</version>
<date > 2002-11-05</date>
<initials > rkd</initials>
<remark > Corrected David Sutton's JID and email. It has been pointed out
to me by amoungst others Rob Norris that things such as lists of JIDs
and lists in general are really the province of disco and browse and
that at least one of the suggested 'core' statistics doesn't
2006-10-03 18:46:54 -04:00
make sense for all components so removed these from the document. This namespace
2006-10-02 18:22:13 -04:00
was starting to become a generic data gathering namespace and we already
have one of those, so i've reworked yet again hopefully for the
final time it should now be simpler to implement and more consistent in
all cases.</remark>
</revision>
<revision >
<version > 0.5.0</version>
<date > 2002-11-03</date>
<initials > rkd</initials>
2006-10-03 18:46:54 -04:00
<remark > Heavily modified document according to suggestions from Matt Miller (linuxwolf). rkd had some additional thoughts on the name attribute, this version reflects those. Reorganized the description section.</remark>
2006-10-02 18:22:13 -04:00
</revision>
<revision >
<version > 0.4.2</version>
<date > 2002-10-25</date>
<initials > rkd</initials>
<remark > Changed rkd's email address and jid. Modified namespace to use http uri.</remark>
</revision>
<revision >
<version > 0.4.1</version>
<date > 2002-08-20</date>
<initials > rkd</initials>
<remark > Corrected error codes</remark>
</revision>
<revision >
<version > 0.4</version>
<date > 2002-08-18</date>
<initials > rkd</initials>
<remark > Fixed two silly typos that crept back in. Rewrote SNMP
to read better. Added the DTD</remark>
</revision>
<revision >
<version > 0.3</version>
<date > 2002-08-16</date>
<initials > rkd</initials>
<remark > Added < display/> so a server or component may
optionally return data in a human readable format. It is nothing
more than a bit of visual fluff but it has potential to be quite
useful. Renumbered the revisions to allow room for stpeter's new
2006-10-03 18:46:54 -04:00
document numbering scheme, sorry if it is now confusing but I hadn't
2006-10-02 18:22:13 -04:00
left much room to grow with the previous revision numbering. A
little more prettying and judicious use of punctuation has occurred.</remark>
</revision>
<revision >
<version > 0.2.2</version>
<date > 2002-08-15</date>
<initials > rkd</initials>
<remark > Fixed some typos and generally prettied up</remark>
</revision>
<revision >
<version > 0.2.1</version>
<date > 2002-08-14</date>
<initials > rkd</initials>
<remark > I seem to have misunderstood one of Ryan Eatmon's
suggestions and didn't make this generic enough. I have
fixed that now. Clarified error codes and reworked how errors
are indicated to work with the new generic
namespace. Rearranged the order of the sections a bit make this
2006-10-03 18:46:54 -04:00
document a more linear read.</remark>
2006-10-02 18:22:13 -04:00
</revision>
<revision >
<version > 0.2</version>
<date > 2002-08-13</date>
<initials > rkd</initials>
<remark > Complete reworking to take into account suggestions made
by Ryan Eatmon and others. Ryan Eatmon added to list of authors to
reflect his significant contribution to the current form of this
2006-10-03 18:46:54 -04:00
document. I have also received a few comments that this document
2006-10-02 18:22:13 -04:00
previously read like an IETF document. Whether that was a good or
bad thing I was unable to ascertain but I've tried to lighten the
tone a little.</remark>
</revision>
<revision >
<version > 0.1.5</version>
<date > 2002-07-23</date>
<initials > rkd</initials>
<remark > Changed data returned by < who/> as per comments by
psa</remark>
</revision>
<revision >
<version > 0.1.4</version>
<date > 2002-07-23</date>
<initials > rkd</initials>
2006-10-04 14:40:38 -04:00
<remark > Converted to XML format.</remark>
2006-10-02 18:22:13 -04:00
</revision>
<revision >
<version > 0.1.3</version>
<date > 2002-07-23</date>
<initials > rkd</initials>
<remark > A numeric values unit type is now returned using an attribute
"units" rather than specifying that it be returned in the smallest
sensible unit type to produce an unsigned integer.</remark>
</revision>
<revision >
<version > 0.1.2</version>
<date > 2002-07-23</date>
<initials > rkd</initials>
<remark > Justify inclusion of the 501 (Not Implemented) error code
as per comments by Zion</remark>
</revision>
<revision >
<version > 0.1.1</version>
<date > 2002-07-22</date>
<initials > rkd</initials>
<remark > Fixed some typos</remark>
</revision>
<revision >
<version > 0.1</version>
<date > 2002-07-21</date>
<initials > rkd</initials>
<remark > Initial version.</remark>
</revision>
2006-10-03 18:46:54 -04:00
<dependencies > XEP-0053</dependencies>
2006-10-02 18:22:13 -04:00
</header>
<section1 topic= 'Introduction' >
<p > As things currently stand it is not possible to obtain statistics
from a jabber component or server without resorting to parsing the
various log files. This makes it extremely difficult to obtain statistics
2006-10-03 18:46:54 -04:00
that are of any use in real world situations. This document attempts to
2006-10-02 18:22:13 -04:00
rectify this situation by defining a new namespace that would be used
to obtain statistics from a component or server so that they may be
manipulated and used in a useful manner. For the purposes of this namespace
a statistic is anything that maybe expressed in a numeric form, such as the
uptime of a server, the <strong > number</strong> of registered users and the
number of packets sent. Things such as a list of currently online users or
a list of registered users are beyond the scope of this namespace and
properly belong within browse or disco.</p>
</section1>
<section1 topic= 'Description' >
<section2 topic= 'Namespace' >
<p > This is a pretty simple namespace. It consists of a < stat/> tag with
three attributes. name, units and value.</p>
<code >
< query xmlns='http://jabber.org/protocol/stats'>
< stat name='' units='' value=''/>
< /query>
</code>
<p > There is one variation in the case of an error invalidating one or
more errors in a single returned query that does not actually
invalidate the whole query.</p>
<code >
< query xmlns='http://jabber.org/protocol/stats'>
< stat name=''> < error code=''> ...< /error> < /stat>
< /query>
</code>
</section2>
<section2 topic= 'Name Attribute' >
<p > The name of the statistic. The format for this attribute is the
generic statistic type such as bandwidth, users, time etc. followed by
a '/' character and then then the name of the actual statistic. For
example bandwidth/packets-in, time/uptime and users/online. This will
be assigned and administered by JANA<note > See Name Registration</note> .</p>
</section2>
<section2 topic= 'Units Attribute' >
<p > This is the units type of the statistic. As with the name attribute it
will be assigned and administered by JANA<note > See Name
Registration</note> It is suggested that JANA use where appropriate
commonly accepted international standards when assigning unit types
i.e. seconds, grams, meters, bytes etc.</p>
</section2>
<section2 topic= 'Value Attribute' >
<p > This is the actual returned value of the queried statistic. The value returned is in
multiples of the unit described by the units attribute.</p>
</section2>
<section2 topic= "Query" >
<p > To query a component or server a client sends an iq packet of
the type 'get' to the component or server. The component or
server responds with the <em > list</em> of statistics that it supports.</p>
<example >
send: < iq type='get' to='component'>
< query xmlns='http://jabber.org/protocol/stats'/>
< /iq>
recv: < iq type='result' from='component'>
< query xmlns='http://jabber.org/protocol/stats'>
< stat name='time/uptime'/>
< stat name='users/online'/>
.
.
.
< stat name='bandwidth/packets-in'/>
< stat name='bandwidth/packets-out'/>
< /query>
< /iq>
</example>
<p > Once a client knows which statistics a component or server
supports it may now request the actual statistics by sending an iq
packet of the type 'get' containing a request for the specific
statistics and sending that to the component or server.</p>
<example >
send: < iq type='get' to='component'>
< query xmlns='http://jabber.org/protocol/stats'>
< stat name='time/uptime'/>
< stat name='users/online'/>
< stat name='bandwidth/packets-in'/>
< stat name='bandwidth/packets-out'/>
< /query>
< /iq>
recv: < iq type='result' from='component'>
< query xmlns='http://jabber.org/protocol/stats'>
< stat name='time/uptime' units='seconds' value='3054635'/>
< stat name='users/online' units='users' value='365'/>
< stat name='bandwidth/packets-in' units='packets' value='23434'/>
< stat name='bandwidth/packets-out' units='packets' value='23422'/>
< /query>
< /iq>
</example>
</section2>
<section2 topic= 'Errors' >
<p > If an error occurs with one or more of the requests for
statistics the component or server should return one of the
following error codes.</p>
<table caption= 'Error Codes' >
<tr > <th > Code</th> <th > String</th> <th > Reason</th> </tr>
<tr > <td > 401</td> <td > Unauthorized</td> <td > Querying JID is not
authorized to perform that query</td> </tr>
<tr > <td > 404</td> <td > Not Found</td> <td > The statistic was not
found for some reason</td> </tr>
<tr > <td > 501</td> <td > Not Implemented</td> <td > Although statistic
is advertised as available it has not been implemented</td> </tr>
<tr > <td > 503</td> <td > Service Unavailable</td> <td > Statistic is
temporarily unavailable</td> </tr>
</table>
<p > Because we wish to be able to collect groups of statistics
within a single returned packet errors must be handled in a two
tier way with authorization and core errors that would render
<strong > all</strong> the statistics meaningless being indicated
with a type='error' in the returned packet.</p>
<example >
< iq type='error' from='component'>
< query xmlns='http://jabber.org/protocol/stats'>
< error code='401'> Not Authorized< /error>
< /query>
< /iq>
</example>
<p > Errors in a query that only invalidate one or more of the
requested statistics are indicated with an < /error> tag
embedded inside the < /stat> tag.
</p>
<example >
< iq type='result' from='component'>
< query xmlns='http://jabber.org/protocol/stats'>
< stat name='time/uptime units='seconds' value='4534'/>
< stat name='bandwidth/packets-in'> < error code='503'> Service Unavailable< /error> < /stat>
< stat name='bandwidth/packets-out'> < error code='503'> Service Unavailable< /error> < /stat>
< /query>
< /iq>
</example>
</section2>
</section1>
<section1 topic= 'Implementation' >
<section2 topic= 'Name Registration' >
<p > All statistic names, returned data units types and other
pertinent statistic information will be assigned and registered with
the Jabber Naming Authority in the category <em > <strong > stat</strong> </em> .
Unfortunately at this time such a body does not exist so we will
have to rely on component and server authors diligently
researching to ensure that their desired name is not already
in use and that they adequately document the returned units
type and anything else that would normally be registered.
2006-10-03 18:46:54 -04:00
Hopefully by the time this document is formally adopted
2006-10-02 18:22:13 -04:00
a central naming authority for the Jabber protocol will be in
place and functional and authors will be then able to register
their names.
</p>
<table caption= 'how to document your statistic' >
<tr >
<th > Stat</th> <th > Description</th> <th > Returned Units</th>
</tr>
<tr >
<td > registered name</td> <td > description of
statistic/reason</td> <td > unit type returned by
query</td>
</tr>
</table>
</section2>
<section2 topic= 'Core Statistics' >
<p >
Although components and servers are free to support whichever statistics they
feel are justified for their particular component or server it is
suggested that the following set of three core statistics are
implemented by all components and servers.</p>
<ul >
<li > < stat name='time/uptime'/> </li>
<li > < stat name='bandwidth/packets-in'/> </li>
<li > < stat name='bandwidth/packets-out'/> </li>
</ul>
<table caption= 'core statistic registration information' >
<tr >
<th > Stat</th> <th > Description</th> <th > Returned Units</th>
</tr>
<tr >
<td > time/uptime</td> <td > uptime of component or
server</td> <td > Seconds</td>
</tr>
<tr >
<td > bandwidth/packets-in</td> <td > packets received by component or server</td> <td > packets</td>
</tr>
<tr >
<td > bandwidth/packets-out</td> <td > packets transmitted by component or server</td> <td > packets</td>
</tr>
</table>
</section2>
<section2 topic= 'Human readable labels' >
<p > For several reasons the
<strong > http://jabber.org/protocol/stats</strong> namespace does not
support human readable labels for the returned values. Generally the
application querying the statistic should already know what the
statistic is and in what units the value is returned. However if the
application really wants some form of human readable label for the
returned value although not an optimal solution or even recommended by
2006-10-03 18:46:54 -04:00
the authors of this document it should be safe for
2006-10-02 18:22:13 -04:00
it to convert the value of the units attribute into a string and use
that as a label for the returned statistic value.</p>
</section2>
<section2 topic= 'Namespace query authorization' >
<p > In most cases the <strong > http://jabber.org/protocol/stats</strong> would be tied to the component or
servers admin JID so that only that JID may query the statistics
however there are advantages to having a three tier system where
some statistics are available to all JIDs, some to an arbitrary
JID listed in the configuration file and all available to the
listed admin JID. As the first case can be emulated by the
second I propose that when implemented the <strong > http://jabber.org/protocol/stats</strong>
namespace is configured to use the three tier method of
authorizing queries.</p>
</section2>
<section2 topic= 'SNMP' >
<p > Supporting industry accepted standards and procedures
<note > For more details on <link url= 'http://www.snmplink.org' > SNMP</link>
and <link url= 'http://www.dmtf.org' > CIM</link> </note> within
the Jabber protocol is highly desirable as long as it does not
restrict the flexibility or functionality of Jabber. So while
the <strong > http://jabber.org/protocol/stats</strong> namespace seems to fall within the domain of
the SNMP and CIM standards amongst others and large jabber
installations would find direct support an appealing prospect
when tying jabber into their existing network information and
management systems the jabber:iq:namespace will not do this.
Because Jabber is an XML based protocol, conversion of
the returned data to other formats including those required
for SNMP, CIM etc. should be relatively simple. Not supporting
industry standards is not without advantages. By leaving the
<strong > http://jabber.org/protocol/stats</strong> as a <em > pure</em> jabber namespace we allow
ourselves to obtain not only commonly used statistics but also
some unusual ones as well. For example imagine a jabber enabled
vending machine, by remaining free of the encumberence and
limitations of SNMP etc. we can directly (if allowed by the
controlling component) query the fluid ounces dispensed, most
popular beverage and the amount of money that has been collected.
Finally although it is unlikely to occur by staying true to our
roots and avoiding direct SNMP support we avoid any possibility
of conflict with other network management agents such as net(ucd)-snmp.
</p>
</section2>
</section1>
<section1 topic= 'Realworld Examples' >
TBD
</section1>
<section1 topic= 'DTD' >
<section2 topic= 'DTD in English' >
TBD
</section2>
<section2 topic= 'DTD' >
TBD
</section2>
</section1>
2006-10-03 18:46:54 -04:00
</xep>
