mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-23 17:52:15 -05:00
429 lines
18 KiB
XML
429 lines
18 KiB
XML
<?xml version='1.0' encoding='UTF-8'?>
|
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
|
<!ENTITY % ents SYSTEM "xep.ent">
|
|
%ents;
|
|
]>
|
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
|
<xep>
|
|
<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>
|
|
<sig>Standards</sig>
|
|
<dependencies><spec>XEP-0053</spec></dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>N/A</shortname>
|
|
<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 make sense for all components so removed these from
|
|
the document.
|
|
This namespace 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>
|
|
<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>
|
|
</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
|
|
document numbering scheme, sorry if it is now confusing but I hadn't
|
|
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
|
|
document a more linear read.</remark>
|
|
</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
|
|
document. I have also received a few comments that this document
|
|
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>
|
|
<remark>Converted to XML format.</remark>
|
|
</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>
|
|
</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
|
|
that are of any use in real world situations. This document attempts to
|
|
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.
|
|
Hopefully by the time this document is formally adopted
|
|
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
|
|
the authors of this document it should be safe for
|
|
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'>
|
|
<p>TBD</p>
|
|
</section1>
|
|
<section1 topic='DTD'>
|
|
<section2 topic='DTD in English'>
|
|
<p>TBD</p>
|
|
</section2>
|
|
<section2 topic='DTD'>
|
|
<p>TBD</p>
|
|
</section2>
|
|
</section1>
|
|
</xep>
|