xeps/xep-0039.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>
    <jig>Standards</jig>
    <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 &lt;display/&gt; 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 &lt;who/&gt; 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>
    <dependencies>XEP-0053</dependencies>
  </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 &lt;stat/&gt; tag with
	three attributes. name, units and value.</p>
      <code>
      &lt;query xmlns='http://jabber.org/protocol/stats'&gt;
        &lt;stat name='' units='' value=''/&gt;
      &lt;/query&gt;
      </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>
      &lt;query xmlns='http://jabber.org/protocol/stats'&gt;
        &lt;stat name=''&gt;&lt;error code=''&gt;...&lt;/error&gt;&lt;/stat&gt;
      &lt;/query&gt;
      </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:     &lt;iq type='get' to='component'&gt;
	          &lt;query xmlns='http://jabber.org/protocol/stats'/&gt;
                &lt;/iq&gt;
      

      recv:     &lt;iq type='result' from='component'&gt;
                  &lt;query xmlns='http://jabber.org/protocol/stats'&gt;
	            &lt;stat name='time/uptime'/&gt;
	            &lt;stat name='users/online'/&gt;
	                  .
	                  .
	                  .
	            &lt;stat name='bandwidth/packets-in'/&gt;
	            &lt;stat name='bandwidth/packets-out'/&gt;
	          &lt;/query&gt;
                &lt;/iq&gt;
      </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:     &lt;iq type='get' to='component'&gt;
                  &lt;query xmlns='http://jabber.org/protocol/stats'&gt;
	            &lt;stat name='time/uptime'/&gt;
	            &lt;stat name='users/online'/&gt;
	            &lt;stat name='bandwidth/packets-in'/&gt;
	            &lt;stat name='bandwidth/packets-out'/&gt;
	          &lt;/query&gt;
                &lt;/iq&gt;


      recv:     &lt;iq type='result' from='component'&gt;
                  &lt;query xmlns='http://jabber.org/protocol/stats'&gt;
                    &lt;stat name='time/uptime' units='seconds'	value='3054635'/&gt;
	            &lt;stat name='users/online' units='users' value='365'/&gt;
	            &lt;stat name='bandwidth/packets-in' units='packets' value='23434'/&gt; 
	            &lt;stat name='bandwidth/packets-out' units='packets' value='23422'/&gt;      
                  &lt;/query&gt;
                &lt;/iq&gt;
      </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>
        &lt;iq type='error' from='component'&gt; 
          &lt;query xmlns='http://jabber.org/protocol/stats'&gt;  
            &lt;error code='401'&gt;Not Authorized&lt;/error&gt;
          &lt;/query&gt;
        &lt;/iq&gt;
      </example>

      <p>Errors in a query that only invalidate one or more of the
      requested statistics are indicated with an &lt;/error&gt; tag
      embedded inside the &lt;/stat&gt; tag.
      </p>

      <example>
        &lt;iq type='result' from='component'&gt;
          &lt;query xmlns='http://jabber.org/protocol/stats'&gt;
            &lt;stat name='time/uptime units='seconds' value='4534'/&gt;
	    &lt;stat name='bandwidth/packets-in'&gt;&lt;error code='503'&gt;Service Unavailable&lt;/error&gt;&lt;/stat&gt;
            &lt;stat name='bandwidth/packets-out'&gt;&lt;error code='503'&gt;Service Unavailable&lt;/error&gt;&lt;/stat&gt;
          &lt;/query&gt;
        &lt;/iq&gt;
      </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>&lt;stat name='time/uptime'/&gt;</li>
	<li>&lt;stat name='bandwidth/packets-in'/&gt;</li>
	<li>&lt;stat name='bandwidth/packets-out'/&gt;</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'>
      TBD
  </section1>
  <section1 topic='DTD'>
    <section2 topic='DTD in English'>
      TBD
    </section2>    
    <section2 topic='DTD'>
      TBD
    </section2>
  </section1>
</xep>