A Load Balancing Using mod_oc4j

A.1.1 Random

mod_oc4j randomly selects an OC4J instance from a list of OC4J instances that are candidates to service a request.

A.1.2 Round Robin

mod_oc4j randomly selects an OC4J instance from an ordered list of OC4J instances that are candidates to service a request. Other OC4J instances are selected from the ordered list in turn, until the initially selected server is selected again. This sequence is repeated. If a particular OC4J instance is stopped or is unavailable, then that instance is skipped (no attempt is made to select it) until it can be brought back in service.

A.1.3 Random with Local Affinity

mod_oc4j randomly selects local OC4J processes to service requests. When no local OC4J processes are available, mod_oc4j randomly selects remote OC4J processes and gives them equal opportunity to be selected.

A.1.4 Round Robin with Local Affinity

mod_oc4j routes all requests to local OC4J processes in a round robin manner. When no local processes are available, mod_oc4j routes requests equally to each OC4J process on different hosts.

A.1.5 Random using Routing Weight

mod_oc4j distributes requests according to the routing weight configured for each host. One OC4J process is selected randomly from the OC4J processes on that host.

A.1.6 Round Robin using Routing Weight

mod_oc4j distributes the total request load to OC4J processes on each host based on the routing weight configured to each host. mod_oc4j selects an OC4J process in round robin manner from the OC4J processes on that host.

A.1.7 Metric Based

mod_oc4j routes requests based on run time metrics from OC4J processes that indicate how much load can be placed on the OC4J process.

A.1.8 Metric Based with Local Affinity

mod_oc4j routes all requests to local OC4J processes based on the run time performance metrics of OC4J processes. When there are no local OC4J processes available, mod_oc4j routes requests to each OC4J process on different hosts as per their performance metrics only.

A.2.1 Oc4jSelectMethod

Selects an OC4J instance for load balancing.

This directive is only applicable to the base server for Oracle Application Server 10g Release 2 (10.1.2) and an error will be printed at startup if specified within a VirtualHost container.

A.2.2 Oc4jRoutingWeight

Associates a request routing weight for each machine during load balancing. Weighted routing is a load balancing strategy that distributes requests according to a predefined value assigned to each machine based on the predicted ability to handle load.

This directive is only applicable to the base server for Oracle Application Server 10g Release 2 (10.1.2) and an error will be printed at startup if specified within a VirtualHost container.

A.3.1 Configuring Oracle HTTP Server

On the Oracle HTTP Server side, specify "Oc4jSelectMethod metric" or "Oc4jSelectMethod metric:local" in mod_oc4j.conf.

A.3.2 Configuring OC4J

On the OC4J side, you must configure the metric collector in ORACLE_HOME/j2ee/home/config/server.xml in UNIX or ORACLE_HOME/j2ee\home\config\server.xml on Windows. Configuring the <metric-collector> element tells OC4J to start sending a metric to mod_oc4j so that mod_oc4j can make routing decisions to load balance incoming requests to a list of available OC4J instances.

The metric sent from OC4J to mod_oc4j is used only when metric-based load balancing is specified for mod_oc4j and when OC4J runs in an Oracle Application Server environment.

If you specify metric-based load balancing in mod_oc4j and do not specify the <metric-collector> element in server.xml, then mod_oc4j expects OC4J to send metrics, but OC4J does not send metrics. In this case, mod_oc4j reports the following warning message:

No run time metrics for oc4j(opmnid=%s) in notification Oc4jSelectMethod is
configured to use run time metrics, please make sure OC4J side is configured
accordingly. Default to 50.

In this case, mod_oc4j uses the value "50" for each of the OC4J processes and continues.

Likewise, if you specify the <metric-collector> element in server.xml, but do not specify metric-based load balancing in mod_oc4j, then OC4J sends metrics but mod_oc4j is not configured to receive metrics. In this case, mod_oc4j ignores the metrics and uses whatever the configured method is for load balancing. You specify the load balancing method with Oc4jSelectMethod. If no Oc4jSelectMethod is specified, then mod_oc4j uses the default, which is roundrobin.

All OC4Js that are used from this Oracle HTTP Server instance must be configured identically. Otherwise, the number returned from the OC4Js will not be comparable and can produce some very poor load balancing results.

When mod_oc4j receives a notification containing the metrics information from OC4J, it immediately changes the request routing behavior. The default interval between notifications from OC4J is 30 seconds. This value can be configured using the system property opmnPingInterval, which is passed on the command line when OC4J is started by OPMN. To change the interval between notifications, specify the following in opmn.xml under the OC4J <process-set> configuration element:

<module-data> 
  <category id="start-parameters"> 
    <data id="java-options" value="-DopmnPingInterval=<new ping interval value>"/>
  </category> 
</module-data>

Specifying Metrics for OC4J

The following two methods can be used to specify metrics for OC4J:

• Configuring Metric-based Load Balancing to Use the DMSMetricCollector

• Building Your Own Metric Collector

<metric-collector classname="oracle.oc4j.server.DMSMetricCollector">
   <init-param>
     <param-name>
       dms-noun
     </param-name>
     <param-value>
       /oc4j/default/WEBs/processRequest.time
     </param-value>
   </init-param>
   <init-param>
     <param-name>
       history-proportion
     </param-name>
     <param-value>
       0.2
     </param-value>
   </init-param>
   <init-param>
     <param-name>
       debug
     </param-name>
     <param-value>
       false
     </param-value>
   </init-param>
</metric-collector>

metric = 100 / (1 + (log (1 + delta)))

smoothedmetric = ((1 - history-proportion) * metric) + (history-proportion * previousmetric)

<metric-collector classname="my.package.name.MyClassName">
  <init-param>
    <param-name>
      mysetting
    </param-name>
    <param-value>
      12345
    </param-value>
  </init-param>
</metric-collector>

<library path="<path to>/mymetric.jar"/>

package oracle.oc4j.api;
 
 import java.util.Map;
 
 /**
  * Defines an interface for gathering and obtaining a server-wide metric.
  * The metric is used in iAS mode, by mod_oc4j, to load balance between
  * virtual oc4j instances.
  * The metric value is relative, and should be between 0 and 100, both
  * inclusive.
  * When configured for metric load balancing,
  * Mod_oc4j will route preferably to an oc4j with the greater value.
  * <p>Concrete instances of this class must have a public empty constructor in
  * order to be loaded and instantiated.
  */
 public interface MetricCollector {
   /**
    * Support for debugging: This is a property name to set to true in order
    * to display the metric that is sent from the server
    */
   String OC4J_METRIC_DEBUG_PROPERTY = "oc4j.metric.debug";
 
   /**
    * Debugging flag that depends on @{link #OC4J_METRIC_DEBUG_PROPERTY}
    */
   boolean DEBUG = Boolean.getBoolean( OC4J_METRIC_DEBUG_PROPERTY );
 
   /**
    * Initial metric to return when no measurement has been made (property key)
    */
   String OC4J_INITIAL_METRIC_PROPERTY = "oc4j.metric.initial";
   /**
    * Initial metric to return when no measurement has been made.
    * Default is 50
    */
   int INITIAL_METRIC = Integer.getInteger( OC4J_INITIAL_METRIC_PROPERTY, 50 ).intValue();
 
   /**
    * Enabled flag for the collector.
    * @return true if the collector is collecting data
    */
   boolean isEnabled();
 
   /**
    */
   void setEnabled( boolean enabled);
 
   /**
    * The parameters the metric collector is configured with.
    * This method will be called even when the set of parameters is null.
    * @param params the key/value pairs the metric collector is configured with,
    * or <code>null</code> if none
    */
   void setParameters( Map params );
 
   /**
    * @return a metric between 0 and 100, inclusive. 100 is better, 0 is worse
    */
   int getMetric();
 
 }