Commit 9ba6e222 authored by Per Cederqvist's avatar Per Cederqvist
Browse files

(Statistics): New section.

(get-stats-description): New request.
(get-stats): New request.
(Error Codes): Documented undefined-measurement.
(Measured Properties): New chapter.
parent eb95802a
......@@ -384,6 +384,7 @@ The most up-to-date version if this document can always be found at
* LysKOM Content Types:: Predefined content types for articles.
* The User Area:: Store client-specific settings in the server.
* Membership visibility:: How the security features interacts.
* Measured Properties:: Load average, number of processed requests...
* Writing Clients:: A few tips for client writers.
* Importing and Exporting E-Mail:: A few thoughts on e-mail integration.
* Some Client-specific Aux-Item Types:: Informative info about more aux-items.
......@@ -1475,6 +1476,7 @@ definitions are more concise in this section.
* Article Information:: Information about an article.
* Who Information:: Old-style info about logged-on users.
* Session Information:: New-style info about logged-on users.
* Statistics:: The server measures several things.
@end menu
@node Common Types
......@@ -2785,6 +2787,37 @@ The dynamic session flags (see above.)
What the client is doing. This string is set by the client.
@end table
@node Statistics
@section Statistics
@anchor{Stats-Description}
@tindex Stats-Description
@example
Stats-Description ::=
( what : @lt{ARRAY} @lt{HOLLERITH};
when : @lt{ARRAY} @lt{INT32};
)
@end example
The @type{Stats-Description} structure returns information about what
kind of statistical information that the server gathers. It contains
these fields:
@table @field
@item what
A list of all things that the server collect statistics about.
@ref{Measured Properties}, for a list of things that might be included
in this list.
@item when
The statistics returned by @reqlink{get-stats} is a number of average
values collected during various periods of time. This array contains
the periods, measured in seconds. The value 0 means that the current
value is returned. @ref{Measured Properties}, for more info.
@end table
@node Protocol Requests
@chapter Protocol Requests
......@@ -2906,6 +2939,8 @@ their current status.
* get-membership:: r Get membership for a person (108)
* mark-as-unread:: r Mark a text as not read (109)
* set-read-ranges:: r Specify which texts that are read (110)
* get-stats-description:: r Get a list of measured properties (111)
* get-stats:: r Get a measurement (112)
@end menu
@ifnottex
......@@ -8025,7 +8060,6 @@ The person logged on is not a member of conference @rarg{conference}.
@end table
@node set-read-ranges
@section set-read-ranges [110] (11) Recommended
......@@ -8102,6 +8136,80 @@ the previous range. The @field{error-status} indicates the interval
@end table
@node get-stats-description
@section get-stats-description [111] (11) Recommended
@findex get-stats-description
@example
get-stats-description [111] ( )
-> ( @lt{Stats-Description} );
@end example
Return a list of the supported statistical measurements. This request
always succeeds, but it might return additional values if you are
logged in or if you have enough privileges.
@xref{Stats-Description}, for more info about the data type.
@xref{Measured Properties}, for more info on what the returned values
means.
@reqexample
@example
1 111
@t{=1 2 @{ @holl{3,X-a} @holl{3,X-b} @} 4 @{ 0 60 300 900 @}}
@end example
@subheading Error codes
This call always succeeds.
@node get-stats
@section get-stats [112] (11) Recommended
@findex get-stats
@example
get-stats [112] ( what : @lt{HOLLERITH} )
-> ( @lt{ARRAY} @lt{INT32} );
@end example
Return a list of the statistical measurements of @rarg{what}. Each
returned number should be multiplied by 0.01 to get the proper value.
The number of elements in the result corresponds to the @code{when}
field of the @type{Stats-Description} returned by
@reqlink{get-stats-description}.
@xref{Measured Properties}, for more info on the @rarg{what}
argument. See also @ref{Stats-Description}.
@reqexample
@example
1 112 @holl{7,clients}
@t{=1 4 @{ 2000 1980 1833 1611 @}}
@end example
Assuming that the @code{when} field of @req{get-stats-description}
contains the time periods 0, 60, 300 and 900, the above result
indicates that there is currently 20 connected clients. The past
averages for 1, 5 and 15 minutes are 19.8, 18.33 and 16.11 connected
clients.
You can use this call even if you are not logged in.
@subheading Error codes
@table @errorcode
@item feature-disabled
The measurement that was requested has been disabled.
@item undefined-measurement
The server doesn't measure the value requested by @rarg{what}.
@item access-denied
The client isn't allowed to retrieve the requested value.
@end table
@node Asynchronous Messages
@chapter Asynchronous Messages
......@@ -8625,7 +8733,6 @@ contains the text number of the text that already is a comment.
Attempt to add a footnote to a text twice over. @field{error-status}
contains the text number of the text that already is a footnote.
@item not-recipient (30)
Attempt to remove a recipient that isn't really a recipient.
@field{error-status} contains the conference number in question.
......@@ -8747,6 +8854,11 @@ The lower limit of a supplied range is not greater than the upper
limit of the previous range in the list.
@field{error-status} is undefined.
@item undefined-measurement (57)
A request for a measurement that the server doesn't make has been
made.
@field{error-status} is undefined.
@end table
......@@ -9622,6 +9734,69 @@ Otherwise, @var{V} is not allowed to se the membership.
@node Measured Properties
@chapter Measured Properties
The server measures a number of properties, and can return information
about them to a client via the @reqdlink{get-stats}
request@linkhere{}. A server implementation may include experimental
properties, whose name should begin with @samp{X-}. All other
properties should be defined in this chapter.
Some of the properties that are suggested here might prove to be too
hard to measure efficiently, or might prove to expose too much
information. In that case, a server may select to not implement them.
Clients must be prepared to receive a @errorcode{feature-disabled} or
@errorcode{undefined-measurement} error if they call @req{get-stats}
with a value that wasn't received from
@reqlink{get-stats-description}.
There are two kinds of properties that can be measured: rates and
levels.
@section Measured Rates
Rates are always normalized to a number of events per second. If the
server states that the length of a time period is 0, the number of
events during that period will always be 0.
@table @code
@item req-rate
The rate of Protocol A requests that were processed.
@item dns-rate
The rate of answered DNS requests.
@item ident-rate
The rate of received IDENT responses.
@item run-queue-enter
@itemx run-queue-leave
The rate at which clients enter and leave the run-queue.
@end table
@section Measured Levels
If the server states that the length of a time period is 0, the level
returned for that period will be the current level when the
measurement is taken.
@table @code
@item run-queue-length
The number of clients that the server is currently refusing to serve
since its time for the server to process other clients for a while.
@item pending-dns
The number of pending DNS requests.
@item pending-ident
The number of pending IDENT requests.
@item clients
The number of connected clients.
@end table
@node Writing Clients
@appendix Writing Clients (informative)
......@@ -10699,7 +10874,7 @@ End:
@c LocalWords: Elisp HOLLERITHs INT JSK JySKom KOM LysKOM lysator Magnusson
@c LocalWords: Padrone's PortaCOM PottaKOM QZ RFC RPC Stat TLS TZ Tolke FIXME
@c LocalWords: UConference UTC WinKOM abbrev'd addr admin aronsson async aux
@c LocalWords: bcc cc ciokwe comm compface conf confs dst elisp se
@c LocalWords: bcc cc ciokwe comm compface conf confs dst elisp se IANA Stats
@c LocalWords: exempel faq flg foo footn gazonk getmail guwal hakka hopi pell
@c LocalWords: hostname html iconifies ident infos kajsa kom komimportmail om
@c LocalWords: lage ldb letterbox letterboxes linefeed linus loc ludd luth db
......@@ -10709,4 +10884,4 @@ End:
@c LocalWords: sven svensson swascii sync synched synching texinfo tkom kent
@c LocalWords: ttykom uconf undef unmark userid username val varg yoruba dont
@c LocalWords: Nyheter davby Testconf com Unicode roadmap interoperability
@c LocalWords: Bugzilla
@c LocalWords: Bugzilla stats spam SpamAssassin DNS
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment