From 0105676f2a47b21f21c5c7e1e02ea419ae697f6c Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Tue, 15 May 2018 13:33:26 +0200 Subject: [PATCH] [5589] Updated XML corrections to the hooks-stats-lib doc. --- doc/guide/hooks-stat-cmds.xml | 162 ++++++++++++++++------------------ 1 file changed, 78 insertions(+), 84 deletions(-) diff --git a/doc/guide/hooks-stat-cmds.xml b/doc/guide/hooks-stat-cmds.xml index 57890b7c5f..02afe088b9 100644 --- a/doc/guide/hooks-stat-cmds.xml +++ b/doc/guide/hooks-stat-cmds.xml @@ -2,7 +2,7 @@ stat_cmds: Supplemental Statistics Commands This library provides additional statistics commands for - retrieving lease statistics from kea-dhcp servers. These commands + retrieving lease statistics from Kea DHCP servers. These commands were added to address an issue with obtaining accurate lease statistics in deployments running multiple Kea servers that use shared lease back end. The in-memory statistics kept by individual @@ -35,14 +35,14 @@ - All commands use JSON syntax and can be issued either using directly to + All commands use JSON syntax and can be issued either directly to the servers via the control channel (see ) or via Control Agent (see ). This library may be loaded by both kea-dhcp4 and kea-dhcp6 servers. - It is loaded in the same way as other other libraries and currently has + It is loaded in the same way as other libraries and currently has no parameters: @@ -59,7 +59,7 @@ - In a deployment with multiple kea-dhcp servers sharing a common lease + In a deployment with multiple Kea DHCP servers sharing a common lease storage, it may be loaded by any or all of the servers. However, one thing to keep in mind is that a server's response to a stat-lease{4/6}-get command will only contain data for subnets known to that server. In @@ -91,12 +91,12 @@ will be 2 (i.e. CONTROL_RESULT_EMPTY). - first-subnet-id - ID of the first - subnet in the range. + first-subnet-id - ID of the first + subnet in the range. - last-subnet-id - ID of the first - subnet in the range. + last-subnet-id - ID of the first + subnet in the range. @@ -106,8 +106,9 @@ If no parameters are given, the result will contain data for all known subnets. Note that in configurations with large numbers of subnets, this can be result in a large response. - - The following command would fetch lease statistcis for all known subnets from kea-dhcp4 server: + + + The following command would fetch lease statistcis for all known subnets from kea-dhcp4 server: { "command": "stat-lease4-get", @@ -115,8 +116,8 @@ } } - - + + The following command would fetch lease statistcis for subnet ID 10 from kea-dhcp6 server: { @@ -126,8 +127,8 @@ } } - - + + The following command would fetch lease statistcis for all subnets from subnet ID 10 through 50 from kea-dhcp4 server: { @@ -140,99 +141,102 @@ } } - + - - The response to the either command will contain three elements: - - - result - numeric value indicating the outcome of the - command where: - - 0 - command was successful - 1 - an error occurred, an explanation will - be the "text" element - 2 - indicates the fetch found no matching data - - - - - text - an explanation of the command outcome. When the command - succeeds it will contain the command name along with the number of rows returned. - - - arguments - a map containing the data returned by the - command as the element "result-set", which patterned after SQL statement responses: + + The response to the either command will contain three elements: - columns - a list of text column labels. - The columns returned for DHCPv4 are: + + result - numeric value indicating the outcome of the + command where: + + 0 - command was successful + 1 - an error occurred, an explanation will + be the "text" element + 2 - indicates the fetch found no matching data + + + + + text - an explanation of the command outcome. When the command + succeeds it will contain the command name along with the number of rows returned. + + + arguments - a map containing the data returned by the + command as the element "result-set", which patterned after SQL statement responses: - subnet-id - ID of the subnet - total-addresses - total number of addresses + columns - a list of text column labels. + The columns returned for DHCPv4 are: + + subnet-id - ID of the subnet + total-addresses - total number of addresses available for DHCPv4 management. In other words, this is the sum of all addresses in all configured pools. This statistic changes only during configuration changes. Note it does not take into account any addresses that may be reserved due to host reservation. - - assigned-addresses - number of assigned + + assigned-addresses - number of assigned addresses in a given subnet. It increases every time a new lease is allocated (as a result of receiving a DHCPREQUEST message) and is decreased every time a lease is released (a DHCPRELEASE message is received) or expires. - - declined-addresses - number of IPv4 addresses + + declined-addresses - number of IPv4 addresses that are currently declined in a given subnet, so is a count of the number of leases currently unavailable. Once a lease is recovered, this statistic will be decreased. Ideally, this statistic should be zero. If this statistic is non-zero (or worse increasing), a network administrator should investigate if there is a misbehaving device in his network. + + - - The columns returned for DHCPv6 are: - - subnet-id - ID of the subnet - total-nas - number of NA addresses available + The columns returned for DHCPv6 are: + + subnet-id - ID of the subnet + total-nas - number of NA addresses available for DHCPv6 management for a given subnet. In other words, this is the sum of all addresses in all configured pools. This statistic changes only during configuration changes. Note that it does not take into account - any addresses that may be reserved due to host reservation. - - assigned-nas - number of NA addresses in a + any addresses that may be reserved due to host reservation. + + assigned-nas - number of NA addresses in a the subnet that are assigned. This statistic increases every time a new lease is allocated (as a result of receiving a REQUEST message) and is decreased every time a lease is released (a RELEASE message is received) or expires. - - declined-nas - number of IPv6 addresses that + + declined-nas - number of IPv6 addresses that are currently declined and so counts the number of leases currently unavailable. Once a lease is recovered, this statistic will be decreased. Ideally, this statistic should be zero. If this statistic is non-zero (or worse, increasing), the network administrator should investigate if there is a misbehaving device in the network. - - total-pds - total number of PD prefixes available + + total-pds - total number of PD prefixes available of DHCPv6 management for a given subnet. In other words, this is the sum of all prefixes in all configured pools. This statistic changes only during configuration changes. Note it does not take into account any prefixes that may be reserved due to host reservation. - - assigned-pds - number of PD prefixes in a given + + assigned-pds - number of PD prefixes in a given subnet that are assigned. This statistic increases every time a new lease is allocated (as a result of receiving a REQUEST message) and is decreased every time a lease is released (a RELEASE message is received) or expires. + + + rows - a list of rows, one per subnet ID. Each row + contains a data value for corresponding to and in the same order as each column + listed in "columns" for a given subnet. + + timestamp - textual date and time the data was fetched, + expressed as GMT - - rows - a list of rows, one per subnet ID. Each row - contains a data value for corresponding to and in the same order as each column - listed in "columns" for a given subnet. - - timestamp - textual date and time the data was fetched, - expressed as GMT - - - - - The response to a DHCPv4 command might look as follows: + + + + + + The response to a DHCPv4 command might look as follows: { "result": 0, @@ -248,9 +252,9 @@ } } - - - The response to a DHCPv6 command might look as follows: + + + The response to a DHCPv6 command might look as follows: { "result": 0, @@ -267,17 +271,7 @@ } } - - - - - - - - - - - + -- 2.47.2