Chapter 11. Load Metrics

11.1. Server-Side Load Metrics

A major feature of mod_cluster is the ability to use server-side load metrics to determine how best to balance requests.
The DynamicLoadBalanceFactorProvider bean computes the load balance factor of a node from a defined set of load metrics. 
<bean name="DynamicLoadBalanceFactorProvider" class="org.jboss.modcluster.load.impl.DynamicLoadBalanceFactorProvider" mode="On Demand">
  <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.web:service=LoadBalanceFactorProvider",exposedInterface=org.jboss.modcluster.load.impl.DynamicLoadBalanceFactorProviderMBean.class)</annotation>
  <constructor>
    <parameter>
      <set elementClass="org.jboss.modcluster.load.metric.LoadMetric">
        <inject bean="BusyConnectorsLoadMetric"/>
        <inject bean="HeapMemoryUsageLoadMetric"/>
      </set>
    </parameter>
  </constructor>
  <property name="history">9</property>
  <property name="decayFactor">2</property>
</bean>
Load metrics can be configured with an associated weight and capacity:
  1. The weight (default is 1) indicates the significance of a metric with respect to the other metrics. For example, a metric of weight 2 will have twice the impact on the overall load factor than a metric of weight 1.
  2. The capacity of a metric serves 2 functions:
Each load metric contributes a value to the overall load factor of a node. The load factors from each metric are aggregated according to their weights.
In general, the load factor contribution of given metric is: 
(load ÷ capacity) × weight ÷ total weight
The DynamicLoadBalanceFactorProvider applies a time decay function to the loads returned by each metric. The aggregate load, with respect to previous load values, can be expressed by the following formula: 
L = (L0 + L1∕D + L2∕D2 + L3∕D3 + ... + LH∕DH) × (1 + D + D2 + D3 + ... DH)
... or more concisely as: 
H         H
L = ∑ Li/Di *  ∑ Di
i=0       i=0
... where D = decayFactor and H = history.
Setting history = 0 effectively disables the time decay function and only the current load for each metric will be considered in the load balance factor computation.
The mod_cluster proxy module expects the load factor to be an integer between 0 and 100, where 0 indicates max load and 100 indicates zero load. Therefore, the final load balance factor sent to the proxy is: 
100 - (L × 100)
While you are free to write your own load metrics, the following LoadMetrics are available out of the box: