Configuring Services and Process Groups

This section describes configuration tasks associated with WLOC services. It contains the following sections:

Overview

A WLOC service is a collection of one or more processes that WLOC manages as a unit. Each process in a service is a software stack starting from the Java Virtual machine (JVM) and including the classes that are running in the JVM. You organize processes (JVMs) that perform the same function and have the same runtime characteristics into process groups within the service. For example, you can organize all of the Managed Servers in a cluster within a process group.

The configuration information for a service contains the following types of information:

Constraints on the number of process instances. Initial process constraints specify how many processes of each type are created when the service is deployed. Once the service is deployed, WLOC uses process constraints to determine the boundary requirements when a policy leads to an action that starts or stops instances. For example, if a policy leads to an action that would otherwise start a new instance of a process group, a maximum process constraint will stop the creation of a new process instance if you have already reached the maximum number of allowed processes. Similarly if a policy leads to an action that would otherwise destroy an instance, a minimum process constraint will prevent process destruction if you are already at the minimum requirement for the process group.
Information that WLOC needs to start the processes. For example, a process group can specify Java classes or other executables along with startup parameters such as the names of WebLogic Server instances.
Requirements for the physical computing resources that are needed to start and run each process. These resource requirements are expressed as a range of CPU cycles, memory, and IP addresses.
Requirements for access to the collection of software and systems that are used to run the applications.
An optional set of service policies which define a service level agreement (SLA) and actions to take when the service is operating outside of the SLA constraints.

Java commands for starting three Managed Servers (MS1, MS2, and MS3) and an Admin Server, each of which belongs to a WebLogic Server cluster.
A set of resource requirements that indicate that the service needs a total of at least 400 MHz of CPU cycles and 400 MB of RAM, and that the service can scale up to using no more than 800 MHz of CPU and 800 MB of RAM.
The list of software that is needed in order for all the processes in the service to run.
A set of policies that start the service with only 2 Managed Servers running and start the third Managed Server if a specific servlet's response time drops below 2 seconds. The policies can also require that the third Managed Server shuts down if the servlet's response time is faster than one second.

Service Process Management

Some of the types of processes that WLOC manages provide their own set of management tools. For example, WebLogic Server provides an Administration Console that creates and configures servers and that deploys applications. While you can use these external management tools to configure processes that are running as WLOC services, note the following restrictions:

For example, you create a WLOC service with a process group consisting of 3 WebLogic Managed Servers that are in a cluster. This cluster of Managed Servers hosts a collection of Web Services. If you use WebLogic Server utilities to add a new Managed Server (MS4) to the cluster, MS4 can function as a cluster member, but WLOC cannot manage MS4 until you add it to the service configuration. Similarly, if you use WebLogic Server utilities to deploy a new Web Service to the cluster, users can access the Web Service and WLOC can measure the additional use of memory and other computing resources that result from adding the new Web Service, but WLOC cannot monitor specific activity within the new Web Service until you add one or more service policies to the WLOC service configuration.

Configuring a Service

The primary tool for defining services is the WLOC Administration Console. Services you define or modify using the console will take place in real time. For detailed instructions about using the Administration Console to create services, see the WLOC Administration Console Online Help. You can access the Help by clicking the Help link in the upper right corner of the Administration Console.

When defining service processes in the console, you can manually enter the required information or use a number of helper functions the console provides for importing much of the information. These include:

It is also possible to define or modify a service by directly editing the metadata configuration file. The location and name of this file is:

Note that direct modifications to the file do not take effect until the Controller is restarted. In addition, manual changes are not validated or error-checked until they are loaded by the next Controller boot.

There are number of resources to help you obtain more information about metadata-config.xml file. These include:

The metadata schema file. The name and location of this file is BEA_HOME\WLOC_HOME\schemas\loc-metadata.xsd. This file may also be accessed at http://download.oracle.com/docs/cd/E13156_01/wloc/docs103/schemaref/metadata/loc/-metadata.xsd.
The Service Metadata Configuration Schema Reference.
The sample metadata configuration file provided when WLOC is installed. The name and location of this file is: BEA_HOME\user_projects\controller\config\metadata-config.xml.SAMPLE.

Configuring a Process Group

When configuring a process group, you need to specify information required by WLOC to instantiate it, including:

When defining the process group, the console prompts for information about its processes. Table 5-1 describes in more detail the information needed to define a process group.

Table 5-1 Process Group Configuration
Process Group Attribute	Description
Process Group	A string identifier for the process group.
Number of Processes	Number of processes that are configured for the process group when it is initially created.
Name	Name of the initial JVM instance. For each additional instance, a numeric suffix is added to the name.
Description	Description of the JVM.
Main Class or Main JAR	Class or JAR file that instantiates this process.
Host	Fully-qualified host name where the JVM resides. The host and port number are used to determine the address the Agent uses to collect JMX metric information from the endpoint.
Starting Port #	Starting port number for the machine where the JVMs reside. The first process instance uses this port number. For each additional instance, the port address is incremented by 1. The host and port number are used to determine the address the Agent uses to collect JMX metric information from the endpoint. For more information, see Creating Multiple Java Processes Using Templates.
JMX Service URL	JMX service URL to use instead of specifying a WLS host and port. This URL is used to connect to a non-WLS endpoint, such as any MBean server.
Classpath	CLASSPATH for the class or JAR file that instantiates this process. For information about obtaining CLASSPATH information, see Determining the Classpath.
JVM Arguments	JVM arguments to use with the command that instantiates the process. These arguments are passed as Java options. Separate each Java argument using a space. For more detailed information, see JVM Arguments for Processes.
Java Arguments	Command line arguments needed for running the application in this JVM. These are passed to the Java main class as arguments.
Username and password	Security credentials required to make a JMX connection to the JVM. These will be the default values for all subsequently created processes.
Instance Directory	Working directory in which the process instance is started.
Native Lib Directory	Directory in which the JVM native libraries reside. The value will be passed to jvm args as `-Djava.library.path`
Use Native JMX	Flag that specifies whether or not to use JMX connection native JMX MBean server.
SSH Enabled	Flag that specifies whether or not SSH is enabled for the instance.
Protocol	Protocol used for JMX connections (`iiop`, `iiops`, `http`, and `https`).
Ready metric	Information about the metric that WLOC obtains from the JVM instance and uses to determine whether or not a process is available. For more detailed information, see Ready Metrics for Processes.
Process Requirements	The required minimum and maximum number of processes.
Resource Requirements	The required minimum and maximum amount of CPU and memory. For more information, see Resource Requirements.
Software Requirements	The name and directory location of the software required by the process.
Manual Placement Addresses	Suggested IP addresses for placement of the process. Doing this supplements WLOC’s internal placement algorithm, which searches for the set of placement locations that would work given the constraints of memory, CPU capacity, software availability, and IP addresses.

Resource Requirements

When using the console to define a service’s processes, the console solicits information about the service’s resource requirements. This information constitutes the service’s out-of-gate deployment policies and is saved in the form of constraints and actions.

Resource requirements specify the required amount of physical computing resources for each instance in a process group. For example, to create a process group that includes a WebLogic Server domain, specify resource requirements for running all WebLogic Server instances. You can specify that a WebLogic cluster needs a minimum of 400 MHz of CPU cycles and 400 MB of RAM and can scale up to a maximum of 800 MHz of CPU and 800 MB of RAM.

These requirements do not include resources needed to run software outside of the process group, but declared as a dependency. For example, if a process group specifies that it requires a RDBMS system, the resource requirements do not include computing resources for the RDBMS.

Minimums and Maximums

Resource requirements are specified in terms of minimum and maximum amounts. The minimum requirement specifies the smallest amount of resources that must be reserved for exclusive use by a process group. As the resources consumed by a process group approach the minimum, a WLOC policy can request additional resources up to the maximum requirement.

WLOC may not be able to actually obtain additional resources if all available resources are being consumed by other WLOC resource pools or non-WLOC applications. For example, Figure 5-1 shows a hypervisor resource pool containing two WLOC resource pools. Although the pool provides 600 MB of memory, the WLOC Resource Pool has two services, each configured for a minimum of 200 MB and maximum of 400 MB. While both services can consume the minimum required memory (200 MB) at the same time, they cannot simultaneously consume the maximum. In Figure 5-1, service 1 is consuming 400 MB, so the total amount of consumed memory is 600 MB. Service 2 cannot use additional memory until service 1 decreases its memory consumption.

Ready Metrics for Processes

WLOC needs to know when a process has successfully started and is ready for work. This is made possible by specifying the process group’s ready metric. When defined, the action to start an instance is not considered complete until the ready metric is satisfied. If the ready metric isn't satisfied in a configurable amount of time, then the instance is considered failed and will be stopped.

Table 5-2 Ready Metric
Ready Metric Attribute	Description
Instance Name	The name of the MBean that has the attribute to test. Example: `com.bea:Name=AdminServer,Type=ServerRuntime`
Attribute	The name of the MBean attribute to test. Example: `state`. For more information about the format to use to specify MBean attributes, see WebLogic Server MBean Reference.
Value	A constant value to test the MBean attribute against. This field is valid only if the Operator is set to `Value` `Equals`. For example: RUNNING.
Operator	The operator (`Value Equals` or `Value` `Exists`).
Value Type	The value type (Integer, Long, Float, Double, Boolean, Date, String). The default is `Integer`.
Wait	(Optional) The number of milliseconds to wait after the ready metric constraint is satisfied before the process is considered ready.

Table 5-3 specifies a ready metric that reports a JVM instance is in RUNNING state:

Table 5-3 WebLogic Server Instance Ready Metric Configuration
Ready Metric Attribute	Value
Ready metric instance	Name=com.bea:AdminServer,Type=ServerRuntime
Attribute	State
Value	RUNNING
Operator	ValueEquals
Value Type	String
Wait	30000

JVM Arguments for Processes

For proper operation and tuning, managed applications must typically start with a specific set of JVM arguments. For each process group, you can specify the JVM arguments to use when the process starts. In the WLOC Administration Console, you specify JVM arguments on the Process Properties page when you define the instance.

When configuring a JVM instance, you need to specify connection information to tell the Agent how to get the management information from the running instance. For more information, see Setting the JMX Port. You also need to configure the JVM instance itself to open the port to which the Agent needs to connect.

Typically, the native configuration for the JVM instance will specify how it exposes its management information. In some cases, however, you may need to specify command line arguments for the instance. For example, with WebLogic Server, the listen port can be defined in the config.xml for the WebLogic domain or it can be overridden on the command line. For non-WebLogic endpoints, you may want to enable remote access to the JDK platform MBeanServer by setting command line arguments.

Setting Communication Protocols

Although all of the management information for a managed endpoint is obtained through JMX MBeans, the communication protocols over which that information is passed can vary depending on the application running in the VM. Here are some examples:

WebLogic

Coherence

When the endpoint is Coherence, the port for exposing Coherence MBeans is configured by setting command line properties starting with -Dtangosol.coherence. Note that best practices for Coherence are to set up a small set of instances within the cluster to expose JMX data; these instances aggregate information about all cluster members. As mentioned above, the Plain Agent uses the JDK Platform MBeans to obtain CPU and Memory statistics. Therefore, certain charts in the WLOC Administration Console will not be able to obtain default CPU and memory statistics for each instance with this setup. For more information on exposing MBeans from Coherence, see the Coherence documentation.

Generic Application

Although all three of the above examples are providing JMX data, the underlying protocols are all different and the JMX client, in this case the Agent, needs to know how to read the data. JMX provides quite a bit of flexibility in how the JMX information is transported and serialized on the wire. In the case of WLS, various protocols may be used, for example http, https, t3, t3s, etc.

If you only set protocol, host and port, the WLOC agent will assume that it is interacting with a WebLogic endpoint and will use WebLogic RMI to transport the data over the protocol you specify.

If the endpoint is not WLS, then you should set native-jmx to true in the metadata-config.xml file. In the WLOC Administration Console, select the Use Native JMX check box on the Process Properties page when you define the instance. When you do so, the WLOC agent will use standard JMX protocols.

Coherence uses two ports to expose JMX. One port is for the JMX traffic itself and the other is for the JNDI information needed to lookup JMX. The basic protocol, host and port settings are not sufficient to connect to this endpoint, so when interacting with the Coherence MBeanServer, you must specify the jmx-service-url in the metadata-config.xml file. In the WLOC Administration Console, you specify this value on the Process Properties page when you define the instance. When jmx-service-url is specified, the protocol, host and port settings will be ignored.

Listing 5-3 provides an example of the JVM arguments as contained in metadata-config.xml.

<ns2:jvm-args>
	<ns2:arg>-Xmx128m</ns2:arg>
	<ns2:arg>-Xms64m</ns2:arg>
	<ns2:arg>-da</ns2:arg>
	<ns2:arg>-cp</ns2:arg> 	
	<ns2:arg>CLASSPATH=C:\bea\patch_weblogic921\profiles\default\
	sys_manifest_classpath\weblogic_patch.jar;C:\bea\WEBLOG~1\server\
	lib\weblogic_sp.jar;C:\bea\WEBLOG~1\server\lib\weblogic.jar;C:\bea\
	WEBLOG~1\server\lib\webservices.jar;</ns2:arg>
	<ns2:arg>-Dwls.home=C:\bea\weblogic92\server</ns2:arg>
	<ns2:arg>-Dweblogic.management.discover=true</ns2:arg>
	<ns2:arg>-Dweblogic.Name=AdminServer</ns2:arg>
	<ns2:arg>-Dweblogic.management.username=weblogic</ns2:arg>
	<ns2:arg>-Dweblogic.management.password=weblogic</ns2:arg>
	<ns2:arg>-Djava.security.policy=C:\bea\weblogic92\server\lib\
	weblogic.policy</ns2:arg>
	<ns2:arg>-Dweblogic.RootDirectory=C:\bea\user_projects\domains\
	WLOCdomain</ns2:arg>
</ns2:jvm-args>

Setting the JMX Port

You set the JMX port of the managed endpoint using the Starting Port # field in the Administration Console, or the <port> field of the <jvm-instance> definition in the metadata-config.xml file. The host and port number are used to determine the address the Agent uses to collect JMX metric information from the endpoint.

For WLS endpoints

The WLS listen port, by default, becomes the JMX port. However, if the WLS Administration Port is enabled, the Administration Port should be used as JMX port. For more information, see “Configure the domain-wide administration port” in the WLS Administration Console Online Help.

For generic Java endpoints

Enable the JMX port using the JVM specific method for your platform as follows:

JRockit JVM: Use -Xmanagement as described in “-X Command-line Options” in the JRockit Command Line Reference
Sun JVM: Refer to the Sun JMX documenatation at http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html

You can also use -Dcom.sun.management.jmxremote.port=<port_num> to set the JMX port.

Determining the Classpath

One of the required JVM arguments is the classpath needed to start the JVM instance. This section describes how to obtain the classpath in different environments.

JVMs on Plain Agents

For WebLogic Server, execute the setDomainEnv command and obtain the WLS classpath by echoing CLASSPATH environment variable. Examples:

Windows — \bin\setDomainEnv.cmdSolaris/Linux — ./bin/setDomainEnv.sh

For generic Java applications, set the classpath based on application installation on Plain Agent host. Examples:

Windows — c:\apps\myapp\lib\myapp1.jar;C:\apps\myapp\lib\myapp2.jarSolaris/Linux — /apps/myapp/lib/myapp1.jar;C:/apps/myapp/lib/myapp2.jar

LiquidVMs

Classpath elements can be sourced anywhere from the LiquidVM file system. If the element is in the ISO image, the path must begin with /appliance since the ISO is mounted on /appliance. If the element is in an NFS share, then the path must begin with the NFS mount point. If the element is in the local disk, then the path would begin with / (forward slash).

For WLS-VE 9.2v1.1, the standard classpath as set by the commonStartVE script is:

Creating Multiple Java Processes Using Templates

To simplify the task of creating multiple copies of Java processes in a service, WLOC provides the capability to define the common characteristics of the process in a template, and to use variables to replace common parameters. You can then use the template to generate multiple copies of the process without having to physically configure duplicates in the metadata configuration. When you create the template, you define:

Defining the Common JVM Parameters

You define the common parameters of the Java process template in the same way in which you define an individual process instance. If you know the name of the variables that you will define, you can specify them as part of your arguments when you configure the template. Otherwise, you will need to update the template definition after the variables are created. For more information, see the following topics:

Specifying the Number of Processes

In addition to the variable definitions, you can specify the number of copies of the instance that you want to create by using the max-copies element:

For example, when you specify 5 as the value for the max-copies element, WLOC expands the definitions into five JavaInstanceMetaData instances.

When max-copies is greater than 1, the name of each Java instance will be appended with a dash followed by the number of the copy (0,1,2,...), such as managed-0, managed-1, and so on.

Defining Variables

To take advantage of the variable definitions, you can insert variable references into certain attributes of the jvm-instance definition. You can specify variables for the following attributes:

Java arguments <JavaArgs>
JVM arguments <JvmArgs>
Instance directory <InstanceDir>
Host <Host>
Port <Port>
JMX Service URL <JmxServiceUrl>

You can also define variables for the Instance and Value attributes of the Ready Metric definition.

Two types of variables are supported: scalar and arrays. If you use a scalar variable, then its value replaces the reference in the attribute. If you use an array variable, you can specify a set of values to use to replace the reference in the attribute.

For example, you can create a variable named ManagedPort that you can use to define a different port value for each instance as follows:

To use a scalar variable, you simply specify the value to be substituted for the reference. For example, a scalar value in the metadata file is shown as:

In this example, the first copy will be assigned port number 7010, the second 7011, and so on.

There is an implicit variable ${index} which can be used to insert the array index somewhere in your declaration, for example

Sample Template Using Variables

Listing 5-4 provides a sample JVM template using variables. The template specifies that 5 copies of the instance should be created, and uses variables for the name, host, and port fields. The variables and the variable references are shown in bold text.

<ns2:jvm-instance>
	<ns2:name>MyServerInstance</ns2:name>
	<ns2:description>This JVM instance defines a template to stamp out five instances of MyServer</ns2:description>
	<ns2:max-copies>5</ns2:max-copies>
	<ns2:variables>
		<ns2:variable>
			<ns2:name>serverName</ns2:name>
			<ns2:values>
				<ns2:value>server-A</ns2:value>
				<ns2:value>server-B</ns2:value>
				<ns2:value>server-C</ns2:value>
				<ns2:value>server-D</ns2:value>
				<ns2:value>server-E</ns2:value>
			</ns2:values>
		</ns2:variable>
		<ns2:variable>
			<ns2:name>host</ns2:name>
			<ns2:values>
				<ns2:value>123.12.123.100</ns2:value>
				<ns2:value>123.12.123.107</ns2:value>
				<ns2:value>123.12.123.104</ns2:value>
				<ns2:value>123.12.123.109</ns2:value>
				<ns2:value>123.12.123.111</ns2:value>
			</ns2:values>
		</ns2:variable>
		<ns2:variable>
			<ns2:name>port</ns2:name>
			<ns2:value>@range{8000,8005}</ns2:value>
		</ns2:variable>
	</ns2:variables>
	<ns2:main-class>com.mycompany.MyServer</ns2:main-class>
	<ns2:jvm-args>
		<ns2:arg>-Xms64m</ns2:arg>
		<ns2:arg>-Xmx128m</ns2:arg>
		<ns2:arg>-cp</ns2:arg>
		<ns2:arg></ns2:arg>
		<ns2:arg>-Dcom.mycompany.servername=${serverName}</ns2:arg>
		<ns2:arg>-Dcom.mycompany.maxthreads=8</ns2:arg>
		<ns2:arg>-Dcom.mycompany.minthreads=3</ns2:arg>
	</ns2:jvm-args>
	<ns2:java-args/>
	<ns2:native-lib-dir></ns2:native-lib-dir>
	<ns2:instance-dir></ns2:instance-dir>
	<ns2:native-jmx>false</ns2:native-jmx>
	<ns2:protocol>http</ns2:protocol>
	<ns2:host>${host}</ns2:host>
	<ns2:port>${port}</ns2:port>
	<ns2:username></ns2:username>
	<ns2:ssh-enabled>false</ns2:ssh-enabled>
	<ns2:wait-for-ssh>false</ns2:wait-for-ssh>
	<ns2:priority>0</ns2:priority>
	<ns2:copies-at-create/>
	<ns2:copies-at-shutdown/>
</ns2:jvm-instance>

Service Deployment Process

To start a WLOC service, you deploy it using the WLOC Administration Console. Before you start the service, the state of the service is undeployed, which indicates that there are no instances running. When you start the service, the Controller performs the following steps:

Evaluates the process requirements of each process group in the service.
Compares the resource pools available for each process group in the service against the resource agreements and eliminates any resource pools that cannot host the service. For example:

If the service requires high availability, resource pools indicating that they do not support high availability are eliminated as candidates.
If the service requires a specific IP Address, resource pools that do not contain that IP address are eliminated as candidates.
If the service specifies software requirements (iso-constraint and software-constraint), resource pools that do not offer access to all of the required software are eliminated as candidates.
If the service consists of a single process, resource pools that offer fewer computing resources than the service's minimum resource requirements are eliminated.

For example, if a resource pool offers 150 MHz of CPU cycles and a service contains one process and requires at least 200 MHz (and up to 400 MHz), the resource pool is eliminated as a candidate. Note, however, that if a resource pool offers 200 MHz of CPU cycles, the resource pool is considered a candidate for deployment.

If the service consists of multiple processes, WLOC might choose multiple resource pools to run the service.

After the process of elimination, the Controller uses the placement algorithm specified when the service was defined to determine the resource pool on which to place the service:

Prefer resource pools with the most resources: WLOC selects the resource pool combination that provides the greatest amount of computing resources.
Prefer resource pools with fewer resources: WLOC selects the resource pool that most closely matches the minimum resource requirements of the service. This algorithm ensures the most efficient use of resources in your data center.

Note: The placement criteria is the same for both plain and ESX instances with the exception of the iso-constraint, which is not applicable to plain instances.

Stages each instance individually.
Starts each instance individually. When the minimum number of processes from each group is started, the service is deployed.
Evaluates the runtime policy and initiates the specified actions when a constraint is violated.
Continually evaluates the runtime policy using information it obtains from the managed application.

Configuration Guide