Batch Server Configuration
The batch component contains several configuration files and utilities to manage the configuration of the cluster, threadpools and submitters. This section outlines the configuration files and configuration process for configuring batch.
Batch Configuration Files
As with the online component of the Oracle Utilities Application Framework there are a number of configuration files that control the performance and behaviour of the batch component.
The batch component houses the configuration files differently to the online and web services component. The online and web services are housed within a JEE Web Application Server and therefore the configuration files are located according to the JEE standards.
In the batch component the configuration is housed in directories as the batch component is housed as a standalone process that is clustered using Oracle Coherence. Therefore, during the configuration process, the configuration files used by the batch component are built using templates using the initialSetup utility. This utility deposits the configuration files in the $SPLEBASE\splapp\standalone\config directory. See initialSetup – Maintain Configuration Settings for details.
The figure below summarizes the directory structure and the relevant configuration files:
The following configuration files (along with their templates) are listed below:
General Configuration Process
To configure the batch component during the installation process and post-installation then the following process should be used:
• The configureEnv utility is used during installation time and can be used post installation to set parameters in the ENVIRON.INI. See configureEnv – Set up Environment Settings for details.
Note: The configureEnv utility should be used to make any changes to the ENVIRON.INI. Manual changes to this configuration file are not recommended.
• After the ENVIRON.INI has been set or altered, the settings must be reflected in the relevant configuration files used by the batch component using the initialSetup utility. The initialSetup utility takes the relevant templates, builds the configuration files and deposits them in the $SPLEBASE\splapp\standalone\config directory. See initialSetup – Maintain Configuration Settings for details.
The configuration files are now ready to be used for the batch component. Additional configuration can be performed using
bedit. See
Configuring Batch Using Bedit for details.Configuring Batch Using Bedit
The bedit - Batch Edit utility is a set of wizards that allow a batch configuration to be built for an implementation using simple commands. The utility uses a set of templates to build a complete set of configuration files for the cluster, its threadpools and submitters at a global and individual level.
For guidelines and scenarios using this facility, refer to the
Batch Best Practices (Doc Id:
836362.1) reference paper available from
My Oracle Support.Batch Configuration Overview Using Bedit
The bedit utility allows for a set of configuration files to be built on top of the global configuration setting managed using the
Batch Configuration Guidelines. The following process should be used:
• Global Settings - Specify global batch settings using the configureEnv utility to set the defaults in the ENVIRON.INI. See configureEnv – Set up Environment Settings for details.
• Apply Settings - Apply any configuration settings to the global templates and default configuration files using the initialSetup utility. See initialSetup – Maintain Configuration Settings for details.
Note: Use the -t option to allow templates to be rebuilt only. Using other options may affect online.
• Perform Cluster Configuration - Configure the desired
cluster configuration using bedit utility. Clusters are set up once per environment in either using multicast, unicast or single server optimized configurations. See
Cluster Configuration using bedit for details.
• Perform Threadpoolworker Configuration - Configure the desired
threadpoolworker configuration using bedit. Threadpoolworkers can be created on an individual basis with unique configurations or
labelled to share configurations. See
Threadpoolworker Configuration Using Bedit for details.
• Perform Submitter Configuration - C
onfigure the desired submitter configuration using bedit. Submitters can be set up for specific development execution modes (
THIN or
LOCAL), generic configuration or project specific jobs. See
Submitter Configuration using bedit for details.
The process is shown below:
Note: At any time, the file name and location of the generated file is determined at the start of the edit session or using the what command.
Batch Edit Usage Guidelines
The bedit utility is available to simplify the creation and maintenance of these files to promote stability and flexibility whilst minimizing maintenance mistakes (see bedit - Batch Edit for details). The following guidelines apply when using the utility:
• The command line options specify the configuration file to be modified. The specific configuration file or the shortcut option can be used to set the scope of the command.
• Pre-optimized specialist templates (with.be extension) are used to decide the parameters applicable to the setting or command used in the configuration file being edited. The template name is displayed at the start of execution to confirm the configuration file edited.
• Configuration settings can be added, modified or deleted using interactive commands. The following commands are supported:
• The templates will generate the necessary settings based upon the scope of the command. Use the online help to determine valid settings for your configuration.
• User preferences for labels and cluster types are stored in the be.prefs file.
• Using the save command will reflect your changes to the configuration file directly.
• If exit command is issued and changes have been detected, then a confirmation message will be issued. Press y to save, n to quit without saving or c to cancel out of exit command.
Each subsection will outline specific settings within the scope of each configuration.
Cluster Configuration using bedit
Oracle Coherence is used to define and manage the batch cluster. The cluster must be configured to decide how the cluster will operate on the network and the scope of the cluster. The major decision for this step in the process is the type of cluster to implement. There are three styles of cluster supported:
• Multicast cluster (default) - A batch cluster based upon the multicast network protocol. The protocol requires a multicast address and common port. This protocol supports dynamic clustering.
• Unicast cluster - A batch cluster based upon unicast network protocol. Each host and port in the cluster must be explicitly configured and each server must be.
• Single Server cluster - A batch cluster confined to a single server using unicast. This is designed for use in non-production environments to simplify the configuration.
The templates for these cluster types are as follows:
To configure the cluster use one of the example commands:
Once the configuration is opened the following settings need to be configured:
For unicast implementations a socket section must be created per host/port combination defined in the file using the following commands:
• Use the add socket command to add a new socket group. The group name generated will be in the form socket.<number> where <number> is the sequence number. For example:
> add socket
…
socket.2
wkaaddress (localhost)
wkaport (42020)
• Set the wkaaddress and wkaport using the set socket.<number> <variable> <value> where <number> is the sequence number, <variable> is wkaaddress or wkaport and <value> is the desired value. For example:
> set socket.2 wkaport 6402
…
socket.2
wkaaddress (localhost)
wkaport (6402)
• Repeat for each node in the cluster.
Threadpoolworker Configuration Using Bedit
Once a cluster is defined the threadpools that will execute across that cluster must be defined with their name and attributes. Oracle Utilities Smart Grid Gateway supports different types of threadpools that can execute batch processes with the following:
• Cache Threadpools - Threadpoolworkers that do not execute jobs but act as co-ordination node for network traffic. It is recommended that there be at least one cache threadpool per physical host per cluster. For a discussion of cache threadpools, see the
Batch Best Practices (Doc Id:
836362.1) reference paper available from
My Oracle Support. This threadpool type has
tangosol.coherence.distributed.localstorage - DistributedCache Storage set to
true.
• Job Threadpools - Threadpoolworkers that are optimized to run batch threads with support for additional java options and other cluster specific optimization settings.
• Default Threadpools - For backward compatibility, the default template used is pre-optimized with settings from past releases. It is recommended to migrate from this template to job template.
The templates for these threadpool types are as follows:
To configure the cluster use one of the example commands:
Once the configuration is opened the following settings need to be configured:
For multiple threadpools per configuration use the following process:
• Use the add pool command to add a new pool group. The group name generated will be in the form pool.<number> where <number> is the sequence number. For example:
> add pool
…
pool.2
wkaaddress (localhost)
wkaport (42020)
• Set the poolname and threads using the set pool.<number> <variable> <value> where <number> is the sequence number, <variable> is poolname or threads and <value> is the desired value.
Submitter Configuration using bedit
The last step in configuration is to configure the submitters. A submitter is a JVM that submits jobs or threads of jobs to a threadpoolworker and waits for the thread to complete. It is responsible for interfacing to the threadpoolworker and also provides an interface to the process that submits the jobs in the first place (e.g. a third party batch scheduler or Oracle Scheduler).
A submitter needs one or more of the following pieces of information:
• It needs a configuration file that defines the parameters to be used for the individual batch process being executed. These can be global configuration files or individual configuration files optimized for a batch process.
• Command line options to set or override configuration parameters that define the execution parameters for the individual process or thread.
The single execution of a submitter can run a single threaded batch job, a single individual thread of a multi-threaded batch job or all threads of a multi-threaded job.
To create a specific configuration file for a batch job any of the following commands can be used:
Once the configuration is opened the following settings need to be configured:
For multiple parameters per configuration use the following process:
• Use the add soft command to add a new parameter group. The group name generated will be in the form soft.<number> where <number> is the sequence number. For example:
> add soft
…
soft.2
parm (maxErrors)
value (500)
• Set the parm and value using the set pool.<number> <variable> <value> where where <number> is the sequence number, <variable> is parm or value and <value> is the desired value. For example:
> set soft.2 parm fred
…
soft.2
parm (fred)
value (500)
Batch Configuration Guidelines
The following sections outline general guidelines for batch configuration.
Cache Threadpools
One of the new facilities in the batch architecture is the ability to define cache or storage nodes in your architecture. By default a batch cluster communicates across the cluster elements such as threadpools the state of other elements in the cluster. While this has benefits, as any element in the cluster can be queried, through JMX, to find out the global status of all active processes in that cluster, it can generate a large amounts of network traffic and cause instability as the cluster is performing a large amount of maintenance operations. To address this, in Oracle Utilities Smart Grid Gateway it is now possible to create cache or storage threadpools. These act as conduits with the architecture and greatly reduce the network traffic and overheads in managing the cluster. This translates to more stable clusters.
The communications between elements are shown below:
The performance advantages of the cache increases with the number of elements the cluster must manage and cache threadpools have the following implementation recommendations:
• Cache threadpools do not execute any threads of any jobs within them. They are exclusively used for administration, a storage node for the cluster state and a conduit for cluster management.
• Cache threadpools act as Coherence local storage nodes to maintain the integrity of the cluster and allow cluster management.
• Cache threadpools are ideally suited to allow JMX connections to monitor the performance of the cluster using the Batch JMX Reference interface.
At least one cache threadpool per cluster per host is recommended. Multiple cache threadpools can be implemented where high availability is required or there are a lrge number of submitters, threads and/or threadpools to manage.
If a cache threadpool, is shut down and no cache threadpools are active at any time, the cluster will not revert to individual elements communicating across other elements.
To create cache clusters, use the bedit.sh -l cache command. A prebuilt template is created for the cache where storage is enabled, distthds, invocthds and the number of threads is set to 0 (to prevent jobs from running in the cache). See bedit - Batch Edit for details.
Adding custom JMX Information to jobs
The
Batch JMX Reference interface can be extended for additional tags using a new parameter
f1.jmxInfo for filtering purposes or additional documentation. For example:
The submitbatch.properties file for the particular job should have the following additional parameter:
com.splwg.batch.submitter.softParameter.f1.jmxInfo.<tag>=<value>
where:
Multiple parameters of this type are supported within a single configuration file.
For example:
com.splwg.batch.submitter.softParameter.f1.jmxInfo.foo=bar
When using bedit the command sequence to use this facility is:
• Add a soft parameter section for each desaired tag/value pair using the command (a section soft.<sequence> is created where <sequence> is a generated sequence number):
add soft
• Specify the parm property as f1.jmxInfo.<tag> where <tag> is the desired tag using the command:
set soft.<sequence> parm f1.jmxInfo.<tag>
• Specify the value property as the desired value for the tag using the command:
set soft.<sequence> value <value>
It is possible to specify this setting on the submitjob.sh command using the -x option (see submitjob.sh - Submit Batch Threads). For example:
submit.sh … -x f1.jmxInfo.foo=bar