Overview
A major use case of IBM Z OMEGAMON for JVM is for z/OS Connect EE API monitoring. API metrics are derived for every API that passes through z/OS Connect EE and stored in z/OS System Logger DASD-only log streams. A part of the configuration process requires customers to edit and submit a System Logger policy utility batch job to define log streams for every z/OS Connect EE server to be monitored (one for providers and one for API requesters). A new feature delivered with version 5.5.0 Fix Pack 7 (APAR OA63898, PTF UJ09673) means you no longer need to do this. It can be a time-consuming and potentially error-prone process, especially if you have a large number of servers to configure. Instead, the OMEGAMON for JVM Java agent can automatically define the required log streams on first startup if the log stream does not already exist.
Details
This feature uses an XML file to supply template parameters for creating log streams. The XML file contains two major elements: one for API provider log streams and for API requester log streams. Within each of these elements there are further elements that define default values applicable to all log streams of that type and override parameter for specific servers. Server overrides are based on the started task job name which can be specified as a regular expression. A sample kjj_logstream.xml file is provided with the feature. As provided, automatic log stream creation is disabled for both provider and requester APIs.
Figure 1 shows an example XML file which must be called kjj_logstream.xml. It resides in the RTE USS install directory and it is encoded in UTF-8. You will need to edit this file in ISPF option 3.17 using the ASCII edit line command (“ea”).
<?xml version="1.0" encoding="UTF-8"?>
<logstreams>
<providers>
<defaults name="$SMFID.$CID.$JOBNAME" ehlq="" lssize="10000" stgsize="10000" retpd="1" define=”false”/>
<override jobname="BAQ*" name="$SMFID.$CID.$JOBNAME" ehlq="" lssize="10000"
stgsize="10000" retpd="1"/>
</providers>
<requesters>
<defaults name="$SMFID.$CID.$JOBNAME" ehlq="" lssize="10000" stgsize="10000" retpd="1" define=”false” />
<override jobname="BAQ*" name="$SMFID.$CID.$JOBNAME" ehlq="" lssize="10000"
stgsize="10000" retpd="1"/>
</requesters>
</logstreams>
Figure 1.
There are two major elements within the <logstreams> definition: one for API provider log streams and one for API requesters. Within each of these elements there must be one <defaults> element and zero or more <override> elements. Overrides are selected based on the jobname attribute. When a z/OS Connect EE server is started, the XML file is examined to find any override elements with a jobname that matches the server started task job name. The jobname attribute specifies an extended regular expression pattern. OMEGAMON for JVM uses the java/util/regex package. A summary of regular-expression constructs can be found here:
https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html
Log Stream Names
You will notice that the “name” attribute used in defaults and override elements contains symbolic variables beginning with a “$” sign. The “name” attribute specifies the name of the log stream that will be defined. The symbolic variables are substituted as follows:
$SMFID The name of the LPAR defined in the system SMF ID
$CID The Collector ID defined in system property com.ibm.tivoli.kjj.collector.id. The default is KJJ1.
$JOBNAME Substituted with the name of the z/OS Connect server started task job name.
You can use a hard-coded value for an element of the log stream name, particularly in the case where the SMF ID does not begin with an alphabetic character. While an SMF ID of “3SYS” is legitimate, a log stream qualifier cannot start with a numeric character. In this case, an alternative name can be specified for all log streams defined in a particular RTE, say “SYS3” instead. Using:
name=”SYS3.$CID.$JOBNAME”
The other possible parameter attributes that may be specified are:
|
Attribute
|
Description
|
|
ehlq
|
Extended high-level-qualifier of log stream staging and offload data sets
|
|
stgsize
|
Specifies the size, in 4K blocks, of the DASD staging data set for the log stream being defined.
|
|
lssize
|
Specifies the size, in 4K blocks, of the log stream offload DASD data sets for the log stream being defined.
|
|
retpd
|
Specifies the retention period, in days, for log data in the log stream.
|
Below are some more examples of kjj_logstream.xml file configurations
Example 1
Only provider API log streams will be created. All servers will use the standard, default name, with the default system logger high-level qualifier for data sets. Log stream datasets and staging data sets will be allocated will 10000 blocks. The retention period will be 1 day.
<?xml version="1.0" encoding="UTF-8"?>
<logstreams>
<providers>
<defaults name="$SMFID.$CID.$JOBNAME" ehlq="" lssize="10000"
stgsize="10000" retpd="1" define=”true”/>
</providers>
<requesters>
<defaults define=”false” />
</requesters>
</logstreams>
Example 2
Only provider API log streams will be created. All servers will use SYS2 as the SMFID in the log stream name. The system logger data set high-level qualifier will be “OMJAVA.V550”. Log stream datasets and staging data sets will be allocated will 10000 blocks. The retention period will be 1 day.
<?xml version="1.0" encoding="UTF-8"?>
<logstreams>
<providers>
<defaults name="SYS2.$CID.$JOBNAME" ehlq="OMJAVA.V550" lssize="10000"
stgsize="10000" retpd="1" define=”true”/>
</providers>
</logstreams>
Example 3
In this example, only API provider log streams will be created for servers with jobnames beginning with “BAQ” (No requester log streams will be created for these servers. API Requester log streams will be created for all server started task names beginning with “BRQ”, but no API provider log streams will be created.
<?xml version="1.0" encoding="UTF-8"?>
<logstreams>
<providers>
<defaults define=”false”/>
<override jobname="BAQ*" name="$SMFID.$CID.$JOBNAME" ehlq="" lssize="10000" stgsize="10000" retpd="1" define=”true”/>
</providers>
<requesters>
<defaults define=”false” />
<override jobname="BRQ*" name="$SMFID.$CID.$JOBNAME" ehlq="" lssize="10000"
stgsize="10000" retpd="1" define=”true”/>
</requesters>
</logstreams>
For further information refer to the IBM product documentation at:
https://www.ibm.com/docs/en/om-jvm/5.5.0?topic=SSMTJ5_5.5.0/com.ibm.omegamon_jvm.doc/jvm_welcome.htm
#OMEGAMON #Java #z/OS Connect