BIND 10 #170: document how stats are collected (via spec files)

[BIND 10 Development]

#170: document how stats are collected (via spec files)
------------------------+---------------------------------------------------
 Reporter:  larissas    |        Owner:  shane                      
     Type:  task        |       Status:  reviewing                  
 Priority:  major       |    Milestone:  06. 4th Incremental Release
Component:  statistics  |   Resolution:                             
 Keywords:              |    Sensitive:  0                          
------------------------+---------------------------------------------------

Comment(by naokikambe):

 Replying to [comment:12 jinmei]:

 Thank you for your correcting my typos and your comments.

 >   - tcp -- A number of query counts per a process which Auth servers
 >  receives in TCP since it sends last
 >   - udp -- A number of query counts per a process which Auth servers
 >  receives in UDP since it sends last
 >
 >  Does this mean the auth server records counter values last time it
 >  reported to some other modules and only report the diff from the
 previous
 >  value? I'm not sure if this is a good behavior.  If the "previous"
 value
 >  is lost in some way, the receiever can never calculate the total number
 of
 >  that counter.  Also, what if the auth server reports multiple instances
 of
 >  stats-(like) modules?  Does the auth server have to keep the state of
 the
 >  "previously reported value" for all possible clients?  I think it's
 much
 >  simpler and more flexible if the auth server just reports the total
 number
 >  of each counter and have the receiever be responsible for calculating a
 >  diff between two reports (if necessary).

 These counters means "total" count for one auth server, but I
 think "incremental" count for one auth server may be also supported.
 Because I think each auth sever may not know how many auth servers
 work and if it means total counter, all auth servers must support a
 very long-range counter. I think it may be very heavy for auth servers.
 However I also think supporting only total count for all servers is
 easier and more reasonable for the auth server and the stats module.

 So, the stats module(receiver) supports two methods of adding value
 and replacing(setting) value for the sender, so that the sender
 including the auth server can freely choice increment or replace the
 counter values in the stats module, and also the sender freely add
 collecting items.

  - A example of "adding" method:
 If the sender sends this message to the receiver via bindctl,
 {{{
 #!js
 { "command" :  [ "add", { "auth.queries.udp" : 9876 } ]}
 }}}
 the receiver calculates like this:
 {{{
 #!js
 data["auth.queries.udp"] = data["auth.queries.udp"] + 9876
 }}}

  - A example of "replacing(setting)" method:
 If the sender sends this message to the receiver via bindctl,
 {{{
 #!js
 { "command" :  [ "set", { "auth.queries.udp" : 9876 } ]}
 }}}
 the receiver calculates like this:
 {{{
 #!js
 data["auth.queries.udp"] = 9876
 }}}

  - A example of "adding new collecting item and setting value" method:
 There is no difference from "setting" method. If the sender sends this
 message to the receiver via bindctl,
 {{{
 #!js
 { "command" :  [ "set", { "auth2.queries.udp" : 5432 } ]}
 }}}
 the receiver calculates like this:
 {{{
 #!js
 data["auth2.queries.udp"] = 5432
 }}}
 A variable "data" is initially defined as dictionary type.

 What about this idea? If it's no problem for the auth server, I'll
 revise this document, otherwise I welcome better idea than this.:)

-- 
Ticket URL: <http://bind10.isc.org/ticket/170#comment:15>
BIND 10 Development <http://bind10.isc.org>
BIND 10 Development