From: Franciszek Gorski Date: Fri, 2 Aug 2019 07:48:37 +0000 (+0200) Subject: [731-Kea_statistics_enhancements] rewrite stats documentation to sphinx X-Git-Tag: Kea-1.6.1~10^2~7 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=798f70f6181fed979a58a7bddded1c7e4f4fd20f;p=thirdparty%2Fkea.git [731-Kea_statistics_enhancements] rewrite stats documentation to sphinx --- diff --git a/doc/api/statistic-set-max-sample-age-all.json b/doc/sphinx/api/statistic-set-max-sample-age-all.json similarity index 100% rename from doc/api/statistic-set-max-sample-age-all.json rename to doc/sphinx/api/statistic-set-max-sample-age-all.json diff --git a/doc/api/statistic-set-max-sample-age.json b/doc/sphinx/api/statistic-set-max-sample-age.json similarity index 100% rename from doc/api/statistic-set-max-sample-age.json rename to doc/sphinx/api/statistic-set-max-sample-age.json diff --git a/doc/api/statistic-set-max-sample-count-all.json b/doc/sphinx/api/statistic-set-max-sample-count-all.json similarity index 100% rename from doc/api/statistic-set-max-sample-count-all.json rename to doc/sphinx/api/statistic-set-max-sample-count-all.json diff --git a/doc/api/statistic-set-max-sample-count.json b/doc/sphinx/api/statistic-set-max-sample-count.json similarity index 100% rename from doc/api/statistic-set-max-sample-count.json rename to doc/sphinx/api/statistic-set-max-sample-count.json diff --git a/doc/sphinx/arm/stats.rst b/doc/sphinx/arm/stats.rst index 139504774f..80495903bc 100644 --- a/doc/sphinx/arm/stats.rst +++ b/doc/sphinx/arm/stats.rst @@ -233,3 +233,131 @@ If the removal of all statistics is successful, the server responds with a status of 0, indicating success, and an empty parameters field. If an error is encountered, the server returns a status code of 1 (error) and the text field contains the error description. + +.. _command-statistic-set-max-sample-age: + +The statistic-set-max-sample-age Command +---------------------------------------- + +The ``statistic-set-max-sample-age`` command sets time based limit +for collecting samples for given statistic. An example command may look +like this: + +:: + + { + "command": "statistic-set-max-sample-age", + "arguments": { + "name": "pkt4-received", + "duration": 1245 + } + + } + +The server will respond with message about successfully set limit +for the given statistic, with a result set to 0 indicating success +and an empty parameters field. If an error is encountered (e.g. the +requested statistic was not found), the server returns a status code +of 1 (error) and the text field contains the error description. + +.. _command-statistic-set-max-sample-age-all: + +The statistic-set-max-sample-age-all Command +-------------------------------------------- + +The ``statistic-set-max-sample-age-all`` command sets time based limits +for collecting samples for all statistics. An example command may look +like this: + +:: + + { + "command": "statistic-set-max-sample-age-all", + "arguments": { + "duration": 1245 + } + + } + +The server will respond with message about successfully set limit +for all statistics, with a result set to 0 indicating success +and an empty parameters field. If an error is encountered, the server returns +a status code of 1 (error) and the text field contains the error description. + +.. _command-statistic-set-max-sample-count: + +The statistic-set-max-sample-count Command +------------------------------------------ + +The ``statistic-set-max-sample-count`` command sets size based limit +for collecting samples for given statistic. An example command may look +like this: + +:: + + { + "command": "statistic-set-max-sample-count", + "arguments": { + "name": "pkt4-received", + "max-samples": 100 + } + + } + +The server will respond with message about successfully set limit +for the given statistic, with a result set to 0 indicating success +and an empty parameters field. If an error is encountered (e.g. the +requested statistic was not found), the server returns a status code +of 1 (error) and the text field contains the error description. + +.. _command-statistic-set-max-sample-count-all: + +The statistic-set-max-sample-count-all Command +---------------------------------------------- + +The ``statistic-set-max-sample-count-all`` command sets size based limits +for collecting samples for all statistics. An example command may look +like this: + +:: + + { + "command": "statistic-set-max-sample-count-all", + "arguments": { + "max-samples": 100 + } + + } + +The server will respond with message about successfully set limit +for all statistics, with a result set to 0 indicating success +and an empty parameters field. If an error is encountered, the server returns +a status code of 1 (error) and the text field contains the error description. + +.. _time-series: + +Time series +==================== + +Previously, by default, each statistic holded only a single data point. When Kea +attempted to record a new value, the existing previous value was +overwritten. That approach has the benefit of taking up little memory and +it covers most cases reasonably well. However, there may be cases where +you need to have many data points for some process. For example, some +processes, such as received packet size, packet processing time or number +of database queries needed to process a packet, are not cumulative and it +would be useful to keep many data points, perhaps to do some form of +statistical analysis afterwards. + + +Since Kea 1.6, by default, each statistic holds 20 data points. Setting such +limit prevent unlimited memory consumption growth. +There are two ways to define the limts: time based (e.g. keep samples from +the last 5 minutes) and size based. It's possible to change the size based +limit by using one of two commands: ``statistic-set-max-sample-count``, +to set size limit for single statistic and ``statistic-set-max-sample-count-all`` +for setting size based limits for all statistics. To set time based +limit for single statistic use ``statistic-set-max-sample-age``, +and ``statistic-set-max-sample-age-all`` to set time based limits for all statistics. +For given statistic only one type of limit can be active. It means that +storage is limited only by time based limit or size based, never by both of them.