diff options
-rw-r--r-- | docs/manual/mod/mod_lbmethod_bybusyness.xml | 57 | ||||
-rw-r--r-- | docs/manual/mod/mod_lbmethod_byrequests.xml | 217 | ||||
-rw-r--r-- | docs/manual/mod/mod_lbmethod_bytraffic.xml | 72 | ||||
-rw-r--r-- | docs/manual/mod/mod_proxy_balancer.xml | 244 |
4 files changed, 356 insertions, 234 deletions
diff --git a/docs/manual/mod/mod_lbmethod_bybusyness.xml b/docs/manual/mod/mod_lbmethod_bybusyness.xml new file mode 100644 index 0000000000..07fe1f14da --- /dev/null +++ b/docs/manual/mod/mod_lbmethod_bybusyness.xml @@ -0,0 +1,57 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> +<!-- $LastChangedRevision$ --> + +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> + +<modulesynopsis metafile="mod_lbmethod_bybusyness.xml.meta"> + +<name>mod_lbmethod_bybusyness</name> +<description>Pending Request Counting load balancer scheduler algorithm for <module +>mod_proxy_balancer</module></description> +<status>Extension</status> +<sourcefile>mod_lbmethod_bybusyness.c</sourcefile> +<identifier>lbmethod_bybusyness_module</identifier> +<compatibility>Split off from <module>mod_proxy_balancer</module> in 2.3</compatibility> + +<summary> +</summary> +<seealso><module>mod_proxy</module></seealso> +<seealso><module>mod_proxy_balancer</module></seealso> + +<section id="busyness"> + + <title>Pending Request Counting Algorithm</title> + + <p>Enabled via <code>lbmethod=bybusyness</code>, this scheduler keeps + track of how many requests each worker is assigned at present. A new + request is automatically assigned to the worker with the lowest + number of active requests. This is useful in the case of workers + that queue incoming requests independently of Apache, to ensure that + queue length stays even and a request is always given to the worker + most likely to service it fastest.</p> + + <p>In the case of multiple least-busy workers, the statistics (and + weightings) used by the Request Counting method are used to break the + tie. Over time, the distribution of work will come to resemble that + characteristic of <code>byrequests</code>.</p> + +</section> + +</modulesynopsis> diff --git a/docs/manual/mod/mod_lbmethod_byrequests.xml b/docs/manual/mod/mod_lbmethod_byrequests.xml new file mode 100644 index 0000000000..3a2c257594 --- /dev/null +++ b/docs/manual/mod/mod_lbmethod_byrequests.xml @@ -0,0 +1,217 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> +<!-- $LastChangedRevision$ --> + +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> + +<modulesynopsis metafile="mod_lbmethod_byrequests.xml.meta"> + +<name>mod_lbmethod_byrequests</name> +<description>Request Counting load balancer scheduler algorithm for <module +>mod_proxy_balancer</module></description> +<status>Extension</status> +<sourcefile>mod_lbmethod_byrequests.c</sourcefile> +<identifier>lbmethod_byrequests_module</identifier> +<compatibility>Split off from <module>mod_proxy_balancer</module> in 2.3</compatibility> + +<summary> +</summary> +<seealso><module>mod_proxy</module></seealso> +<seealso><module>mod_proxy_balancer</module></seealso> + +<section id="requests"> + <title>Request Counting Algorithm</title> + <p>Enabled via <code>lbmethod=byrequests</code>, the idea behind this + scheduler is that we distribute the requests among the + various workers to ensure that each gets their configured share + of the number of requests. It works as follows:</p> + + <p><dfn>lbfactor</dfn> is <em>how much we expect this worker + to work</em>, or <em>the workers's work quota</em>. This is + a normalized value representing their "share" of the amount of + work to be done.</p> + + <p><dfn>lbstatus</dfn> is <em>how urgent this worker has to work + to fulfill its quota of work</em>.</p> + + <p>The <dfn>worker</dfn> is a member of the load balancer, + usually a remote host serving one of the supported protocols.</p> + + <p>We distribute each worker's work quota to the worker, and then look + which of them needs to work most urgently (biggest lbstatus). This + worker is then selected for work, and its lbstatus reduced by the + total work quota we distributed to all workers. Thus the sum of all + lbstatus does not change(*) and we distribute the requests + as desired.</p> + + <p>If some workers are disabled, the others will + still be scheduled correctly.</p> + + <example><pre><code>for each worker in workers + worker lbstatus += worker lbfactor + total factor += worker lbfactor + if worker lbstatus > candidate lbstatus + candidate = worker + +candidate lbstatus -= total factor</code></pre> + </example> + + <p>If a balancer is configured as follows:</p> + + <table style="data"> + <tr><th>worker</th> + <th>a</th> + <th>b</th> + <th>c</th> + <th>d</th></tr> + <tr><th>lbfactor</th> + <td>25</td> + <td>25</td> + <td>25</td> + <td>25</td></tr> + <tr><th>lbstatus</th> + <td>0</td> + <td>0</td> + <td>0</td> + <td>0</td></tr> + </table> + + <p>And <var>b</var> gets disabled, the following schedule is produced:</p> + + <table style="data"> + <tr><th>worker</th> + <th>a</th> + <th>b</th> + <th>c</th> + <th>d</th></tr> + <tr><th>lbstatus</th> + <td><em>-50</em></td> + <td>0</td> + <td>25</td> + <td>25</td></tr> + <tr><th>lbstatus</th> + <td>-25</td> + <td>0</td> + <td><em>-25</em></td> + <td>50</td></tr> + <tr><th>lbstatus</th> + <td>0</td> + <td>0</td> + <td>0</td> + <td><em>0</em></td></tr> + <tr><td colspan="5">(repeat)</td></tr> + </table> + + <p>That is it schedules: <var>a</var> <var>c</var> <var>d</var> + <var>a</var> <var>c</var> <var>d</var> <var>a</var> <var>c</var> + <var>d</var> ... Please note that:</p> + + <table style="data"> + <tr><th>worker</th> + <th>a</th> + <th>b</th> + <th>c</th> + <th>d</th></tr> + <tr><th>lbfactor</th> + <td>25</td> + <td>25</td> + <td>25</td> + <td>25</td></tr> + </table> + + <p>Has the exact same behavior as:</p> + + <table style="data"> + <tr><th>worker</th> + <th>a</th> + <th>b</th> + <th>c</th> + <th>d</th></tr> + <tr><th>lbfactor</th> + <td>1</td> + <td>1</td> + <td>1</td> + <td>1</td></tr> + </table> + + <p>This is because all values of <dfn>lbfactor</dfn> are normalized + with respect to the others. For:</p> + + <table style="data"> + <tr><th>worker</th> + <th>a</th> + <th>b</th> + <th>c</th></tr> + <tr><th>lbfactor</th> + <td>1</td> + <td>4</td> + <td>1</td></tr> + </table> + + <p>worker <var>b</var> will, on average, get 4 times the requests + that <var>a</var> and <var>c</var> will.</p> + + <p>The following asymmetric configuration works as one would expect:</p> + + <table style="data"> + <tr><th>worker</th> + <th>a</th> + <th>b</th></tr> + <tr><th>lbfactor</th> + <td>70</td> + <td>30</td></tr> + <tr><td colspan="2"> </td></tr> + <tr><th>lbstatus</th> + <td><em>-30</em></td> + <td>30</td></tr> + <tr><th>lbstatus</th> + <td>40</td> + <td><em>-40</em></td></tr> + <tr><th>lbstatus</th> + <td><em>10</em></td> + <td>-10</td></tr> + <tr><th>lbstatus</th> + <td><em>-20</em></td> + <td>20</td></tr> + <tr><th>lbstatus</th> + <td><em>-50</em></td> + <td>50</td></tr> + <tr><th>lbstatus</th> + <td>20</td> + <td><em>-20</em></td></tr> + <tr><th>lbstatus</th> + <td><em>-10</em></td> + <td>10</td></tr> + <tr><th>lbstatus</th> + <td><em>-40</em></td> + <td>40</td></tr> + <tr><th>lbstatus</th> + <td>30</td> + <td><em>-30</em></td></tr> + <tr><th>lbstatus</th> + <td><em>0</em></td> + <td>0</td></tr> + <tr><td colspan="3">(repeat)</td></tr> + </table> + + <p>That is after 10 schedules, the schedule repeats and 7 <var>a</var> + are selected with 3 <var>b</var> interspersed.</p> +</section> + +</modulesynopsis> diff --git a/docs/manual/mod/mod_lbmethod_bytraffic.xml b/docs/manual/mod/mod_lbmethod_bytraffic.xml new file mode 100644 index 0000000000..5cb01c3585 --- /dev/null +++ b/docs/manual/mod/mod_lbmethod_bytraffic.xml @@ -0,0 +1,72 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> +<!-- $LastChangedRevision$ --> + +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> + +<modulesynopsis metafile="mod_lbmethod_bytraffic.xml.meta"> + +<name>mod_lbmethod_bytraffic</name> +<description>Weighted Traffic Counting load balancer scheduler algorithm for <module +>mod_proxy_balancer</module></description> +<status>Extension</status> +<sourcefile>mod_lbmethod_bytraffic.c</sourcefile> +<identifier>lbmethod_bytraffic_module</identifier> +<compatibility>Split off from <module>mod_proxy_balancer</module> in 2.3</compatibility> + +<summary> +</summary> +<seealso><module>mod_proxy</module></seealso> +<seealso><module>mod_proxy_balancer</module></seealso> + +<section id="traffic"> + <title>Weighted Traffic Counting Algorithm</title> + <p>Enabled via <code>lbmethod=bytraffic</code>, the idea behind this + scheduler is very similar to the Request Counting method, with + the following changes:</p> + + <p><dfn>lbfactor</dfn> is <em>how much traffic, in bytes, we want + this worker to handle</em>. This is also a normalized value + representing their "share" of the amount of work to be done, + but instead of simply counting the number of requests, we take + into account the amount of traffic this worker has seen.</p> + + <p>If a balancer is configured as follows:</p> + + <table style="data"> + <tr><th>worker</th> + <th>a</th> + <th>b</th> + <th>c</th></tr> + <tr><th>lbfactor</th> + <td>1</td> + <td>2</td> + <td>1</td></tr> + </table> + + <p>Then we mean that we want <var>b</var> to process twice the + amount of bytes than <var>a</var> or <var>c</var> should. It does + not necessarily mean that <var>b</var> would handle twice as + many requests, but it would process twice the I/O. Thus, the + size of the request and response are applied to the weighting + and selection algorithm.</p> + +</section> + +</modulesynopsis> diff --git a/docs/manual/mod/mod_proxy_balancer.xml b/docs/manual/mod/mod_proxy_balancer.xml index 1097f71d81..98efcfd0ff 100644 --- a/docs/manual/mod/mod_proxy_balancer.xml +++ b/docs/manual/mod/mod_proxy_balancer.xml @@ -35,9 +35,17 @@ <code>HTTP</code>, <code>FTP</code> and <code>AJP13</code> protocols </p> + <p>Load balancing scheduler algorithm is provided by not this + module but other modules such as: + <module>mod_lbmethod_byrequests</module>, + <module>mod_lbmethod_bytraffic</module> and + <module>mod_lbmethod_bybusyness</module>. + </p> + <p>Thus, in order to get the ability of load balancing, - <module>mod_proxy</module> and <module>mod_proxy_balancer</module> - have to be present in the server.</p> + <module>mod_proxy</module>, <module>mod_proxy_balancer</module> + and at least one of load balancing scheduler algorithm modules have + to be present in the server.</p> <note type="warning"><title>Warning</title> <p>Do not enable proxying until you have <a @@ -74,238 +82,6 @@ </example> </section> -<section id="requests"> - <title>Request Counting Algorithm</title> - <p>Enabled via <code>lbmethod=byrequests</code>, the idea behind this - scheduler is that we distribute the requests among the - various workers to ensure that each gets their configured share - of the number of requests. It works as follows:</p> - - <p><dfn>lbfactor</dfn> is <em>how much we expect this worker - to work</em>, or <em>the workers's work quota</em>. This is - a normalized value representing their "share" of the amount of - work to be done.</p> - - <p><dfn>lbstatus</dfn> is <em>how urgent this worker has to work - to fulfill its quota of work</em>.</p> - - <p>The <dfn>worker</dfn> is a member of the load balancer, - usually a remote host serving one of the supported protocols.</p> - - <p>We distribute each worker's work quota to the worker, and then look - which of them needs to work most urgently (biggest lbstatus). This - worker is then selected for work, and its lbstatus reduced by the - total work quota we distributed to all workers. Thus the sum of all - lbstatus does not change(*) and we distribute the requests - as desired.</p> - - <p>If some workers are disabled, the others will - still be scheduled correctly.</p> - - <example><pre><code>for each worker in workers - worker lbstatus += worker lbfactor - total factor += worker lbfactor - if worker lbstatus > candidate lbstatus - candidate = worker - -candidate lbstatus -= total factor</code></pre> - </example> - - <p>If a balancer is configured as follows:</p> - - <table style="data"> - <tr><th>worker</th> - <th>a</th> - <th>b</th> - <th>c</th> - <th>d</th></tr> - <tr><th>lbfactor</th> - <td>25</td> - <td>25</td> - <td>25</td> - <td>25</td></tr> - <tr><th>lbstatus</th> - <td>0</td> - <td>0</td> - <td>0</td> - <td>0</td></tr> - </table> - - <p>And <var>b</var> gets disabled, the following schedule is produced:</p> - - <table style="data"> - <tr><th>worker</th> - <th>a</th> - <th>b</th> - <th>c</th> - <th>d</th></tr> - <tr><th>lbstatus</th> - <td><em>-50</em></td> - <td>0</td> - <td>25</td> - <td>25</td></tr> - <tr><th>lbstatus</th> - <td>-25</td> - <td>0</td> - <td><em>-25</em></td> - <td>50</td></tr> - <tr><th>lbstatus</th> - <td>0</td> - <td>0</td> - <td>0</td> - <td><em>0</em></td></tr> - <tr><td colspan="5">(repeat)</td></tr> - </table> - - <p>That is it schedules: <var>a</var> <var>c</var> <var>d</var> - <var>a</var> <var>c</var> <var>d</var> <var>a</var> <var>c</var> - <var>d</var> ... Please note that:</p> - - <table style="data"> - <tr><th>worker</th> - <th>a</th> - <th>b</th> - <th>c</th> - <th>d</th></tr> - <tr><th>lbfactor</th> - <td>25</td> - <td>25</td> - <td>25</td> - <td>25</td></tr> - </table> - - <p>Has the exact same behavior as:</p> - - <table style="data"> - <tr><th>worker</th> - <th>a</th> - <th>b</th> - <th>c</th> - <th>d</th></tr> - <tr><th>lbfactor</th> - <td>1</td> - <td>1</td> - <td>1</td> - <td>1</td></tr> - </table> - - <p>This is because all values of <dfn>lbfactor</dfn> are normalized - with respect to the others. For:</p> - - <table style="data"> - <tr><th>worker</th> - <th>a</th> - <th>b</th> - <th>c</th></tr> - <tr><th>lbfactor</th> - <td>1</td> - <td>4</td> - <td>1</td></tr> - </table> - - <p>worker <var>b</var> will, on average, get 4 times the requests - that <var>a</var> and <var>c</var> will.</p> - - <p>The following asymmetric configuration works as one would expect:</p> - - <table style="data"> - <tr><th>worker</th> - <th>a</th> - <th>b</th></tr> - <tr><th>lbfactor</th> - <td>70</td> - <td>30</td></tr> - <tr><td colspan="2"> </td></tr> - <tr><th>lbstatus</th> - <td><em>-30</em></td> - <td>30</td></tr> - <tr><th>lbstatus</th> - <td>40</td> - <td><em>-40</em></td></tr> - <tr><th>lbstatus</th> - <td><em>10</em></td> - <td>-10</td></tr> - <tr><th>lbstatus</th> - <td><em>-20</em></td> - <td>20</td></tr> - <tr><th>lbstatus</th> - <td><em>-50</em></td> - <td>50</td></tr> - <tr><th>lbstatus</th> - <td>20</td> - <td><em>-20</em></td></tr> - <tr><th>lbstatus</th> - <td><em>-10</em></td> - <td>10</td></tr> - <tr><th>lbstatus</th> - <td><em>-40</em></td> - <td>40</td></tr> - <tr><th>lbstatus</th> - <td>30</td> - <td><em>-30</em></td></tr> - <tr><th>lbstatus</th> - <td><em>0</em></td> - <td>0</td></tr> - <tr><td colspan="3">(repeat)</td></tr> - </table> - - <p>That is after 10 schedules, the schedule repeats and 7 <var>a</var> - are selected with 3 <var>b</var> interspersed.</p> -</section> - -<section id="traffic"> - <title>Weighted Traffic Counting Algorithm</title> - <p>Enabled via <code>lbmethod=bytraffic</code>, the idea behind this - scheduler is very similar to the Request Counting method, with - the following changes:</p> - - <p><dfn>lbfactor</dfn> is <em>how much traffic, in bytes, we want - this worker to handle</em>. This is also a normalized value - representing their "share" of the amount of work to be done, - but instead of simply counting the number of requests, we take - into account the amount of traffic this worker has seen.</p> - - <p>If a balancer is configured as follows:</p> - - <table style="data"> - <tr><th>worker</th> - <th>a</th> - <th>b</th> - <th>c</th></tr> - <tr><th>lbfactor</th> - <td>1</td> - <td>2</td> - <td>1</td></tr> - </table> - - <p>Then we mean that we want <var>b</var> to process twice the - amount of bytes than <var>a</var> or <var>c</var> should. It does - not necessarily mean that <var>b</var> would handle twice as - many requests, but it would process twice the I/O. Thus, the - size of the request and response are applied to the weighting - and selection algorithm.</p> - -</section> - -<section id="busyness"> - - <title>Pending Request Counting Algorithm</title> - - <p>Enabled via <code>lbmethod=bybusyness</code>, this scheduler keeps - track of how many requests each worker is assigned at present. A new - request is automatically assigned to the worker with the lowest - number of active requests. This is useful in the case of workers - that queue incoming requests independently of Apache, to ensure that - queue length stays even and a request is always given to the worker - most likely to service it fastest.</p> - - <p>In the case of multiple least-busy workers, the statistics (and - weightings) used by the Request Counting method are used to break the - tie. Over time, the distribution of work will come to resemble that - characteristic of <code>byrequests</code>.</p> - -</section> - <section id="environment"> <title>Exported Environment Variables</title> <p>At present there are 6 environment variables exported:</p> |