mirror of https://github.com/moparisthebest/xeps
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
428 lines
18 KiB
428 lines
18 KiB
<?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>
|
|
|