-
Notifications
You must be signed in to change notification settings - Fork 0
/
xep-0039.xml
428 lines (418 loc) · 18.2 KB
/
xep-0039.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
<?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>