WLM classification for z/OS

Read syntax and support notes about Liberty for z/OS® workload management (WLM) feature.

A WLM enclave is associated with the thread that the request is dispatched on. It is also associated with a WLM Service Class. A WLM Service Class is assigned to the WLM enclave by WLM, based on rules that you define in the WLM configuration. The WLM Service Class indicates the WLM goals for each class of client work, for example, 95 percent complete in 1 second or less. The WLM Service Class also indicates the importance of the goals relative to other work on the system. WLM uses information that is provided by the Liberty server during classification to assign a WLM Service Class. The following three properties help WLM to classify the work:

Subsystem Type: For WebSphere®, Subsystem Type is CB.
Collection Name: Name of the server that is running the work. You can create WLM classification rules that are based on the server that is running the work.
Transaction Class: Name that is determined from classification of the work within Liberty code. Transaction Class is based on the Liberty configuration that you provide for the request that is being dispatched. You can assign different Transaction Classes to different applications within the same server, and thus different WLM Service Classes.
Transaction classes can be mixed case and can be up to a maximum number of 8 characters.

Remember: If you turn on WLM, but do not specify a minimum of one rule, WLM is active but no enclaves are created.

HTTP request classification

To classify HTTP requests, configure the zosWLM-1.0 feature and HTTP classification rules. These rules can be configured by using one or more httpClassification elements in the wlmClassification element, as in the following example:

<featureManager>
	<feature>zosWlm-1.0</feature>
</featureManager>

<wlmClassification>
	<httpClassification transactionClass="CLASS001" host="127.0.0.1" port="9080" method="GET"
                      resource="/testResource" />
</wlmClassification>

Table 1. Default Values
Attributes	Default values
`transactionClass=""`	Empty string
`host="*"`	Wildcard
`port="*"`	Wildcard
`method="*"`	Wildcard
`resource="*"`	Wildcard

Important:

Classification rules have a top-down ordering, that is, each rule takes precedence over all rules below it.
All attributes of <httpClassification ... /> are optional.
Ports can be specified as ranges. For example, port="9080-9085".
Ports and methods can be specified as a comma-separated list. For example, port="9043,9080" or method="GET,PUT".
Resources can be defined in the following ways.
- If no resource attribute is specified, the resource attribute is set to asterisk (*) by default. The default is equivalent to specifying resource="*", which means that the resource attribute matches all strings.
- If the resource attribute is set to a string, but the string does not include an asterisk (*), a resource matches only the specified string. For example, if resource="/res1" is specified, the resources matches only the /res1 string.
- To restrict the resource to a specific pattern, use a regular expression. For example, if resource="/res1W*|/res1Web*/**/*" is specified, the resource matches include, but are not limited to, the following patterns: /res1Web, /res1Wa, /res1Web/abc, /res1Web/abc/xyz, /res1Web/abc/xyz/aaa.html.

Example configuration:

<wlmClassification>
	<httpClassification transactionClass="CLASS004" resource="/res2"/>
	<httpClassification transactionClass="CLASS003" resource="/res1"/>
	<httpClassification transactionClass="CLASS002" port="9043" />
	<httpClassification transactionClass="CLASS001" />
</wlmClassification>

The first and second classification rules catch all incoming requests to their respective resources.
The third classification rule catches any incoming request not to either listed resource but on port 9043.
The fourth classification rule is a catch-all rule, which matches any request that comes in that was not matched by the other three classification rules.

MDB request classification

To classify MDB requests, configure the zosWLM-1.0 feature and MDB classification rules. These rules can be configured by using one or more mdbClassification elements in the wlmClassification element, as in the following example:

<server>
    <featureManager>
        <feature>zosWlm-1.0</feature>
    </featureManager>
    ...
    <jmsActivationSpec id="Banking/personal/deposit">
        <properties.wasJms destinationRef="jms/queue1"/>
    </jmsActivationSpec>
    <jmsActivationSpec id="finance/trading/broker">
        <properties.wasJms destinationRef="jms/queue2"/>
    </jmsActivationSpec>
    <jmsActivationSpec id="sales/americas/usa">
        <properties.wasJms destinationRef="jms/queue3"/>
    </jmsActivationSpec>
    ...
    <wlmClassification>
       <mdbClassification transactionClass="CLASMDB1" jmsActivationSpec="Banking/personal/deposit"/>
       <mdbClassification transactionClass="CLASMDB2" jmsActivationSpec="finance/trading/broker"/>
       <mdbClassification transactionClass="CLASMDBN" jmsActivationSpec="*"/>
    </wlmClassification>
...
</server>

The classification of MDB requests is based on the activation specification. As shown in the previous example, the value associated with the jmsActivationSpec attribute can be a single wildcard (*) or the value of the id attribute for a jmsActivationSpec element. If the mdbClassification element is configured with no jmsActivationSpec attribute, Liberty uses the default wildcard value. If the mdbClassification element is configured without a transactionClass attribute, Liberty uses the default empty string value. An empty string transactionClass attribute value prevents requests that match the mdb classification rule from running in an enclave. So, when you need to keep requests associated with a particular activation specification from being processed in an enclave, you can create an mdbClassification element without a transactionClass attribute to satisfy that need.

Similar to the httpClassification elements, multiple mdbClassification elements can be configured in the wlmClassification element. These entries are processed in the order in which they appear in the configuration. For instance, in the previous example, the classification logic first processes the mdbClassification element that contains the jmsActivationSpec attribute set to the value of Banking/personal/deposit. Then, the classification logic processes the second mdbClassification element that contains the jmsActivationSpec attribute set to the value of finance/trading/broker. Lastly, the classification logic processes the third mdbClassification element that contains the jmsActivationSpec attribute set to the value of jmsActivationSpec="*". So, for an MDB request associated with the activation specification of sales/americas/usa, Liberty processes the request by using the CLASMDBN transaction class. Liberty uses this transaction class because the last mdb classification rule defines a jmsActivationSpec with the value of *. This value matches all activation specifications not explicitly defined in previous mdbClassification elements.

Combined example for the HTTP request classification and MDB request classification elements

The following example shows a configuration with both httpClassification and mdbClassification elements:

<server>
    ...
    <wlmClassification>
       <httpClassification transactionClass="CLASS004" resource="/res2"/>
       <httpClassification transactionClass="CLASS003" resource="/res1"/>
       <httpClassification transactionClass="CLASS002" port="9043" />
       <httpClassification transactionClass="CLASS001" />

       <mdbClassification transactionClass="CLASMDB1" jmsActivationSpec="Banking/personal/deposit"/>
       <mdbClassification transactionClass="CLASMDB2" jmsActivationSpec="finance/trading/broker"/>
       <mdbClassification transactionClass="CLASMDBN" jmsActivationSpec="*"/>
    </wlmClassification>
...
</server>