XEP-0039: Statistics Gathering

Abstract:A protocol to enable gathering statistics from Jabber servers and components.
Authors:Paul Curtis, Russell Davis, Ryan Eatmon, David Sutton
Copyright:© 1999 - 2014 XMPP Standards Foundation. SEE LEGAL NOTICES.
Status:Deferred
Type:Standards Track
Version:0.6.0
Last Updated:2002-11-05

WARNING: Consideration of this document has been Deferred by the XMPP Standards Foundation. Implementation of the protocol described herein is not recommended.


Table of Contents


1. Introduction
2. Description
    2.1. Namespace
    2.2. Name Attribute
    2.3. Units Attribute
    2.4. Value Attribute
    2.5. Query
    2.6. Errors
3. Implementation
    3.1. Name Registration
    3.2. Core Statistics
    3.3. Human readable labels
    3.4. Namespace query authorization
    3.5. SNMP
4. Realworld Examples
5. DTD
    5.1. DTD in English
    5.2. DTD

Appendices
    A: Document Information
    B: Author Information
    C: Legal Notices
    D: Relation to XMPP
    E: Discussion Venue
    F: Requirements Conformance
    G: Notes
    H: Revision History


1. Introduction

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 number 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.

2. Description

2.1 Namespace

This is a pretty simple namespace. It consists of a <stat/> tag with three attributes. name, units and value.

      <query xmlns='http://jabber.org/protocol/stats'>
        <stat name='' units='' value=''/>
      </query>
      

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.

      <query xmlns='http://jabber.org/protocol/stats'>
        <stat name=''><error code=''>...</error></stat>
      </query>
      

2.2 Name Attribute

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 [1].

2.3 Units Attribute

This is the units type of the statistic. As with the name attribute it will be assigned and administered by JANA [2]It is suggested that JANA use where appropriate commonly accepted international standards when assigning unit types i.e. seconds, grams, meters, bytes etc.

2.4 Value Attribute

This is the actual returned value of the queried statistic. The value returned is in multiples of the unit described by the units attribute.

2.5 Query

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 list of statistics that it supports.

Example 1.

      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>
      

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.

Example 2.

      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>
      

2.6 Errors

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.

Table 1: Error Codes

CodeStringReason
401UnauthorizedQuerying JID is not authorized to perform that query
404Not FoundThe statistic was not found for some reason
501Not ImplementedAlthough statistic is advertised as available it has not been implemented
503Service UnavailableStatistic is temporarily unavailable

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 all the statistics meaningless being indicated with a type='error' in the returned packet.

Example 3.

        <iq type='error' from='component'> 
          <query xmlns='http://jabber.org/protocol/stats'>  
            <error code='401'>Not Authorized</error>
          </query>
        </iq>
      

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.

Example 4.

        <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>
      

3. Implementation

3.1 Name Registration

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 stat. 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.

Table 2: how to document your statistic

StatDescriptionReturned Units
registered namedescription of statistic/reasonunit type returned by query

3.2 Core Statistics

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.

Table 3: core statistic registration information

StatDescriptionReturned Units
time/uptimeuptime of component or serverSeconds
bandwidth/packets-inpackets received by component or serverpackets
bandwidth/packets-outpackets transmitted by component or serverpackets

3.3 Human readable labels

For several reasons the http://jabber.org/protocol/stats 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.

3.4 Namespace query authorization

In most cases the http://jabber.org/protocol/stats 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 http://jabber.org/protocol/stats namespace is configured to use the three tier method of authorizing queries.

3.5 SNMP

Supporting industry accepted standards and procedures [3] within the Jabber protocol is highly desirable as long as it does not restrict the flexibility or functionality of Jabber. So while the http://jabber.org/protocol/stats 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 http://jabber.org/protocol/stats as a pure 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.

4. Realworld Examples

TBD

5. DTD

5.1 DTD in English

TBD

5.2 DTD

TBD

Appendices


Appendix A: Document Information

Series: XEP
Number: 0039
Publisher: XMPP Standards Foundation
Status: Deferred
Type: Standards Track
Version: 0.6.0
Last Updated: 2002-11-05
Approving Body: XMPP Council
Dependencies: None
Supersedes: None
Superseded By: None
Short Name:
Source Control: HTML
This document in other formats: XML  PDF


Appendix B: Author Information

Paul Curtis

Email: pcurtis@terrapin.com
JabberID: pcurtis@www.terrapin.com

Russell Davis

Email: ukscone@burninghorse.com
JabberID: ukscone@burninghorse.com

Ryan Eatmon

Email: reatmon@jabber.org
JabberID: reatmon@jabber.org

David Sutton

Email: dsutton@legend.co.uk
JabberID: peregrine@legend.net.uk


Appendix C: Legal Notices

Copyright

This XMPP Extension Protocol is copyright © 1999 - 2014 by the XMPP Standards Foundation (XSF).

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <http://xmpp.org/about-xmpp/xsf/xsf-ipr-policy/> or obtained by writing to XMPP Standards Foundation, 1899 Wynkoop Street, Suite 600, Denver, CO 80202 USA).

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.


Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata can be sent to <editor@xmpp.org>.


Appendix F: Requirements Conformance

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".


Appendix G: Notes

1. See Name Registration

2. See Name Registration

3. For more details on SNMP and CIM


Appendix H: Revision History

Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/

Version 0.6.0 (2002-11-05)

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. (rkd)

Version 0.5.0 (2002-11-03)

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. (rkd)

Version 0.4.2 (2002-10-25)

Changed rkd's email address and jid. Modified namespace to use http uri. (rkd)

Version 0.4.1 (2002-08-20)

Corrected error codes (rkd)

Version 0.4 (2002-08-18)

Fixed two silly typos that crept back in. Rewrote SNMP to read better. Added the DTD (rkd)

Version 0.3 (2002-08-16)

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. (rkd)

Version 0.2.2 (2002-08-15)

Fixed some typos and generally prettied up (rkd)

Version 0.2.1 (2002-08-14)

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. (rkd)

Version 0.2 (2002-08-13)

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. (rkd)

Version 0.1.5 (2002-07-23)

Changed data returned by <who/> as per comments by psa (rkd)

Version 0.1.4 (2002-07-23)

Converted to XML format. (rkd)

Version 0.1.3 (2002-07-23)

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. (rkd)

Version 0.1.2 (2002-07-23)

Justify inclusion of the 501 (Not Implemented) error code as per comments by Zion (rkd)

Version 0.1.1 (2002-07-22)

Fixed some typos (rkd)

Version 0.1 (2002-07-21)

Initial version. (rkd)

END