No Description
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.

xep-0039.xml 18KB

  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <!DOCTYPE xep SYSTEM 'xep.dtd' [
  3. <!ENTITY % ents SYSTEM "xep.ent">
  4. %ents;
  5. ]>
  6. <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
  7. <xep>
  8. <header>
  9. <title>Statistics Gathering</title>
  10. <abstract>A protocol to enable gathering statistics from Jabber servers and components.</abstract>
  12. <number>0039</number>
  13. <status>Deferred</status>
  14. <type>Standards Track</type>
  15. <sig>Standards</sig>
  16. <dependencies><spec>XEP-0053</spec></dependencies>
  17. <supersedes/>
  18. <supersededby/>
  19. <shortname>N/A</shortname>
  20. <author>
  21. <firstname>Paul</firstname>
  22. <surname>Curtis</surname>
  23. <email></email>
  24. <jid></jid>
  25. </author>
  26. <author>
  27. <firstname>Russell</firstname>
  28. <surname>Davis</surname>
  29. <email></email>
  30. <jid></jid>
  31. </author>
  32. <author>
  33. <firstname>Ryan</firstname>
  34. <surname>Eatmon</surname>
  35. <email></email>
  36. <jid></jid>
  37. </author>
  38. <author>
  39. <firstname>David</firstname>
  40. <surname>Sutton</surname>
  41. <email></email>
  42. <jid></jid>
  43. </author>
  44. <revision>
  45. <version>0.6.0</version>
  46. <date>2002-11-05</date>
  47. <initials>rkd</initials>
  48. <remark>
  49. Corrected David Sutton's JID and email.
  50. It has been pointed out to me by amoungst others Rob Norris that things
  51. such as lists of JIDs and lists in general are really the province of
  52. disco and browse and that at least one of the suggested 'core'
  53. statistics doesn't make sense for all components so removed these from
  54. the document.
  55. This namespace was starting to become a generic data gathering namespace
  56. and we already have one of those, so I've reworked yet again hopefully
  57. for the final time it should now be simpler to implement and more
  58. consistent in all cases.
  59. </remark>
  60. </revision>
  61. <revision>
  62. <version>0.5.0</version>
  63. <date>2002-11-03</date>
  64. <initials>rkd</initials>
  65. <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>
  66. </revision>
  67. <revision>
  68. <version>0.4.2</version>
  69. <date>2002-10-25</date>
  70. <initials>rkd</initials>
  71. <remark>Changed rkd's email address and jid. Modified namespace to use http uri.</remark>
  72. </revision>
  73. <revision>
  74. <version>0.4.1</version>
  75. <date>2002-08-20</date>
  76. <initials>rkd</initials>
  77. <remark>Corrected error codes</remark>
  78. </revision>
  79. <revision>
  80. <version>0.4</version>
  81. <date>2002-08-18</date>
  82. <initials>rkd</initials>
  83. <remark>Fixed two silly typos that crept back in. Rewrote SNMP
  84. to read better. Added the DTD</remark>
  85. </revision>
  86. <revision>
  87. <version>0.3</version>
  88. <date>2002-08-16</date>
  89. <initials>rkd</initials>
  90. <remark>Added &lt;display/&gt; so a server or component may
  91. optionally return data in a human readable format. It is nothing
  92. more than a bit of visual fluff but it has potential to be quite
  93. useful. Renumbered the revisions to allow room for stpeter's new
  94. document numbering scheme, sorry if it is now confusing but I hadn't
  95. left much room to grow with the previous revision numbering. A
  96. little more prettying and judicious use of punctuation has occurred.</remark>
  97. </revision>
  98. <revision>
  99. <version>0.2.2</version>
  100. <date>2002-08-15</date>
  101. <initials>rkd</initials>
  102. <remark>Fixed some typos and generally prettied up</remark>
  103. </revision>
  104. <revision>
  105. <version>0.2.1</version>
  106. <date>2002-08-14</date>
  107. <initials>rkd</initials>
  108. <remark>I seem to have misunderstood one of Ryan Eatmon's
  109. suggestions and didn't make this generic enough. I have
  110. fixed that now. Clarified error codes and reworked how errors
  111. are indicated to work with the new generic
  112. namespace. Rearranged the order of the sections a bit make this
  113. document a more linear read.</remark>
  114. </revision>
  115. <revision>
  116. <version>0.2</version>
  117. <date>2002-08-13</date>
  118. <initials>rkd</initials>
  119. <remark>Complete reworking to take into account suggestions made
  120. by Ryan Eatmon and others. Ryan Eatmon added to list of authors to
  121. reflect his significant contribution to the current form of this
  122. document. I have also received a few comments that this document
  123. previously read like an IETF document. Whether that was a good or
  124. bad thing I was unable to ascertain but I've tried to lighten the
  125. tone a little.</remark>
  126. </revision>
  127. <revision>
  128. <version>0.1.5</version>
  129. <date>2002-07-23</date>
  130. <initials>rkd</initials>
  131. <remark>Changed data returned by &lt;who/&gt; as per comments by
  132. psa</remark>
  133. </revision>
  134. <revision>
  135. <version>0.1.4</version>
  136. <date>2002-07-23</date>
  137. <initials>rkd</initials>
  138. <remark>Converted to XML format.</remark>
  139. </revision>
  140. <revision>
  141. <version>0.1.3</version>
  142. <date>2002-07-23</date>
  143. <initials>rkd</initials>
  144. <remark>A numeric values unit type is now returned using an attribute
  145. "units" rather than specifying that it be returned in the smallest
  146. sensible unit type to produce an unsigned integer.</remark>
  147. </revision>
  148. <revision>
  149. <version>0.1.2</version>
  150. <date>2002-07-23</date>
  151. <initials>rkd</initials>
  152. <remark>Justify inclusion of the 501 (Not Implemented) error code
  153. as per comments by Zion</remark>
  154. </revision>
  155. <revision>
  156. <version>0.1.1</version>
  157. <date>2002-07-22</date>
  158. <initials>rkd</initials>
  159. <remark>Fixed some typos</remark>
  160. </revision>
  161. <revision>
  162. <version>0.1</version>
  163. <date>2002-07-21</date>
  164. <initials>rkd</initials>
  165. <remark>Initial version.</remark>
  166. </revision>
  167. </header>
  168. <section1 topic='Introduction'>
  169. <p>As things currently stand it is not possible to obtain statistics
  170. from a jabber component or server without resorting to parsing the
  171. various log files. This makes it extremely difficult to obtain statistics
  172. that are of any use in real world situations. This document attempts to
  173. rectify this situation by defining a new namespace that would be used
  174. to obtain statistics from a component or server so that they may be
  175. manipulated and used in a useful manner. For the purposes of this namespace
  176. a statistic is anything that maybe expressed in a numeric form, such as the
  177. uptime of a server, the <strong>number</strong> of registered users and the
  178. number of packets sent. Things such as a list of currently online users or
  179. a list of registered users are beyond the scope of this namespace and
  180. properly belong within browse or disco.</p>
  181. </section1>
  182. <section1 topic='Description'>
  183. <section2 topic='Namespace'>
  184. <p>This is a pretty simple namespace. It consists of a &lt;stat/&gt; tag with
  185. three attributes. name, units and value.</p>
  186. <code>
  187. &lt;query xmlns=''&gt;
  188. &lt;stat name='' units='' value=''/&gt;
  189. &lt;/query&gt;
  190. </code>
  191. <p> There is one variation in the case of an error invalidating one or
  192. more errors in a single returned query that does not actually
  193. invalidate the whole query.</p>
  194. <code>
  195. &lt;query xmlns=''&gt;
  196. &lt;stat name=''&gt;&lt;error code=''&gt;...&lt;/error&gt;&lt;/stat&gt;
  197. &lt;/query&gt;
  198. </code>
  199. </section2>
  200. <section2 topic='Name Attribute'>
  201. <p>The name of the statistic. The format for this attribute is the
  202. generic statistic type such as bandwidth, users, time etc. followed by
  203. a '/' character and then then the name of the actual statistic. For
  204. example bandwidth/packets-in, time/uptime and users/online. This will
  205. be assigned and administered by JANA<note>See Name Registration</note>.</p>
  206. </section2>
  207. <section2 topic='Units Attribute'>
  208. <p>This is the units type of the statistic. As with the name attribute it
  209. will be assigned and administered by JANA<note>See Name
  210. Registration</note>It is suggested that JANA use where appropriate
  211. commonly accepted international standards when assigning unit types
  212. i.e. seconds, grams, meters, bytes etc.</p>
  213. </section2>
  214. <section2 topic='Value Attribute'>
  215. <p>This is the actual returned value of the queried statistic. The value returned is in
  216. multiples of the unit described by the units attribute.</p>
  217. </section2>
  218. <section2 topic="Query">
  219. <p>To query a component or server a client sends an iq packet of
  220. the type 'get' to the component or server. The component or
  221. server responds with the <em>list</em> of statistics that it supports.</p>
  222. <example>
  223. send: &lt;iq type='get' to='component'&gt;
  224. &lt;query xmlns=''/&gt;
  225. &lt;/iq&gt;
  226. recv: &lt;iq type='result' from='component'&gt;
  227. &lt;query xmlns=''&gt;
  228. &lt;stat name='time/uptime'/&gt;
  229. &lt;stat name='users/online'/&gt;
  230. .
  231. .
  232. .
  233. &lt;stat name='bandwidth/packets-in'/&gt;
  234. &lt;stat name='bandwidth/packets-out'/&gt;
  235. &lt;/query&gt;
  236. &lt;/iq&gt;
  237. </example>
  238. <p>Once a client knows which statistics a component or server
  239. supports it may now request the actual statistics by sending an iq
  240. packet of the type 'get' containing a request for the specific
  241. statistics and sending that to the component or server.</p>
  242. <example>
  243. send: &lt;iq type='get' to='component'&gt;
  244. &lt;query xmlns=''&gt;
  245. &lt;stat name='time/uptime'/&gt;
  246. &lt;stat name='users/online'/&gt;
  247. &lt;stat name='bandwidth/packets-in'/&gt;
  248. &lt;stat name='bandwidth/packets-out'/&gt;
  249. &lt;/query&gt;
  250. &lt;/iq&gt;
  251. recv: &lt;iq type='result' from='component'&gt;
  252. &lt;query xmlns=''&gt;
  253. &lt;stat name='time/uptime' units='seconds' value='3054635'/&gt;
  254. &lt;stat name='users/online' units='users' value='365'/&gt;
  255. &lt;stat name='bandwidth/packets-in' units='packets' value='23434'/&gt;
  256. &lt;stat name='bandwidth/packets-out' units='packets' value='23422'/&gt;
  257. &lt;/query&gt;
  258. &lt;/iq&gt;
  259. </example>
  260. </section2>
  261. <section2 topic='Errors'>
  262. <p>If an error occurs with one or more of the requests for
  263. statistics the component or server should return one of the
  264. following error codes.</p>
  265. <table caption='Error Codes'>
  266. <tr><th>Code</th><th>String</th><th>Reason</th></tr>
  267. <tr><td>401</td><td>Unauthorized</td><td>Querying JID is not
  268. authorized to perform that query</td></tr>
  269. <tr><td>404</td><td>Not Found</td><td>The statistic was not
  270. found for some reason</td></tr>
  271. <tr><td>501</td><td>Not Implemented</td><td>Although statistic
  272. is advertised as available it has not been implemented</td></tr>
  273. <tr><td>503</td><td>Service Unavailable</td><td>Statistic is
  274. temporarily unavailable</td></tr>
  275. </table>
  276. <p>Because we wish to be able to collect groups of statistics
  277. within a single returned packet errors must be handled in a two
  278. tier way with authorization and core errors that would render
  279. <strong>all</strong> the statistics meaningless being indicated
  280. with a type='error' in the returned packet.</p>
  281. <example>
  282. &lt;iq type='error' from='component'&gt;
  283. &lt;query xmlns=''&gt;
  284. &lt;error code='401'&gt;Not Authorized&lt;/error&gt;
  285. &lt;/query&gt;
  286. &lt;/iq&gt;
  287. </example>
  288. <p>Errors in a query that only invalidate one or more of the
  289. requested statistics are indicated with an &lt;/error&gt; tag
  290. embedded inside the &lt;/stat&gt; tag.
  291. </p>
  292. <example>
  293. &lt;iq type='result' from='component'&gt;
  294. &lt;query xmlns=''&gt;
  295. &lt;stat name='time/uptime units='seconds' value='4534'/&gt;
  296. &lt;stat name='bandwidth/packets-in'&gt;&lt;error code='503'&gt;Service Unavailable&lt;/error&gt;&lt;/stat&gt;
  297. &lt;stat name='bandwidth/packets-out'&gt;&lt;error code='503'&gt;Service Unavailable&lt;/error&gt;&lt;/stat&gt;
  298. &lt;/query&gt;
  299. &lt;/iq&gt;
  300. </example>
  301. </section2>
  302. </section1>
  303. <section1 topic='Implementation'>
  304. <section2 topic='Name Registration'>
  305. <p>All statistic names, returned data units types and other
  306. pertinent statistic information will be assigned and registered with
  307. the Jabber Naming Authority in the category <em><strong>stat</strong></em>
  308. Unfortunately at this time such a body does not exist so we will
  309. have to rely on component and server authors diligently
  310. researching to ensure that their desired name is not already
  311. in use and that they adequately document the returned units
  312. type and anything else that would normally be registered.
  313. Hopefully by the time this document is formally adopted
  314. a central naming authority for the Jabber protocol will be in
  315. place and functional and authors will be then able to register
  316. their names.
  317. </p>
  318. <table caption='how to document your statistic'>
  319. <tr>
  320. <th>Stat</th><th>Description</th><th>Returned Units</th>
  321. </tr>
  322. <tr>
  323. <td>registered name</td><td>description of
  324. statistic/reason</td><td>unit type returned by
  325. query</td>
  326. </tr>
  327. </table>
  328. </section2>
  329. <section2 topic='Core Statistics'>
  330. <p>
  331. Although components and servers are free to support whichever statistics they
  332. feel are justified for their particular component or server it is
  333. suggested that the following set of three core statistics are
  334. implemented by all components and servers.</p>
  335. <ul>
  336. <li>&lt;stat name='time/uptime'/&gt;</li>
  337. <li>&lt;stat name='bandwidth/packets-in'/&gt;</li>
  338. <li>&lt;stat name='bandwidth/packets-out'/&gt;</li>
  339. </ul>
  340. <table caption='core statistic registration information'>
  341. <tr>
  342. <th>Stat</th><th>Description</th><th>Returned Units</th>
  343. </tr>
  344. <tr>
  345. <td>time/uptime</td><td>uptime of component or
  346. server</td><td>Seconds</td>
  347. </tr>
  348. <tr>
  349. <td>bandwidth/packets-in</td><td>packets received by component or server</td><td>packets</td>
  350. </tr>
  351. <tr>
  352. <td>bandwidth/packets-out</td><td>packets transmitted by component or server</td><td>packets</td>
  353. </tr>
  354. </table>
  355. </section2>
  356. <section2 topic='Human readable labels'>
  357. <p>For several reasons the
  358. <strong></strong> namespace does not
  359. support human readable labels for the returned values. Generally the
  360. application querying the statistic should already know what the
  361. statistic is and in what units the value is returned. However if the
  362. application really wants some form of human readable label for the
  363. returned value although not an optimal solution or even recommended by
  364. the authors of this document it should be safe for
  365. it to convert the value of the units attribute into a string and use
  366. that as a label for the returned statistic value.</p>
  367. </section2>
  368. <section2 topic='Namespace query authorization'>
  369. <p>In most cases the <strong></strong> would be tied to the component or
  370. servers admin JID so that only that JID may query the statistics
  371. however there are advantages to having a three tier system where
  372. some statistics are available to all JIDs, some to an arbitrary
  373. JID listed in the configuration file and all available to the
  374. listed admin JID. As the first case can be emulated by the
  375. second I propose that when implemented the <strong></strong>
  376. namespace is configured to use the three tier method of
  377. authorizing queries.</p>
  378. </section2>
  379. <section2 topic='SNMP'>
  380. <p>Supporting industry accepted standards and procedures
  381. <note>For more details on <link url=''>SNMP</link>
  382. and <link url=''>CIM</link></note> within
  383. the Jabber protocol is highly desirable as long as it does not
  384. restrict the flexibility or functionality of Jabber. So while
  385. the <strong></strong> namespace seems to fall within the domain of
  386. the SNMP and CIM standards amongst others and large jabber
  387. installations would find direct support an appealing prospect
  388. when tying jabber into their existing network information and
  389. management systems the jabber:iq:namespace will not do this.
  390. Because Jabber is an XML based protocol, conversion of
  391. the returned data to other formats including those required
  392. for SNMP, CIM etc. should be relatively simple. Not supporting
  393. industry standards is not without advantages. By leaving the
  394. <strong></strong> as a <em>pure</em> jabber namespace we allow
  395. ourselves to obtain not only commonly used statistics but also
  396. some unusual ones as well. For example imagine a jabber enabled
  397. vending machine, by remaining free of the encumberence and
  398. limitations of SNMP etc. we can directly (if allowed by the
  399. controlling component) query the fluid ounces dispensed, most
  400. popular beverage and the amount of money that has been collected.
  401. Finally although it is unlikely to occur by staying true to our
  402. roots and avoiding direct SNMP support we avoid any possibility
  403. of conflict with other network management agents such as net(ucd)-snmp.
  404. </p>
  405. </section2>
  406. </section1>
  407. <section1 topic='Realworld Examples'>
  408. <p>TBD</p>
  409. </section1>
  410. <section1 topic='DTD'>
  411. <section2 topic='DTD in English'>
  412. <p>TBD</p>
  413. </section2>
  414. <section2 topic='DTD'>
  415. <p>TBD</p>
  416. </section2>
  417. </section1>
  418. </xep>