IBM Tivoli Monitoring Self-Describing Agents: z/OS Considerations
Mike Bonett, IBM Advanced Technical Skills
IBM Tivoli® Monitoring (ITM) 6.23 has added a new feature called Self-Describing Agent (SDA)
support. This support allows agents with this feature to automatically have their application support
files installed in the appropriate components in the ITM infrastructure, without manual intervention.
OMEGAMON® XE on z/OS® 5.1 and OMEGAMON® XE for CICS® 5.1 are the first z/OS agents
to contain the SDA feature. For environments with z/OS agents, the SDA feature improves the z/OS
agent installation and maintenance process.
Overview
Agents in the IBM Tivoli Monitoring infrastructure provide a structure for using the data they provide
in the ITM infrastructure. This is referred to as Agent Application Support. This support consists of
various files used by various ITM components:
• Catalog and attribute (or CAT and ATR) files describe the agent metric tables and metric
attributes, which are necessary to present and use this information in the Tivoli Enterprise
Portal (TEP) workspaces. These files must be installed on the Tivoli Enterprise Portal Server
(TEPS) and Hub Tivoli Enterprise Monitoring Server (TEMS). If the agent connects to a
Remote TEMS, that TEMS must also have these files installed.
Without these files, the following types of errors are seen in the TEMS log:
("CreateServerView") Bad status from VPM1_CreateViewPlan, 209
("VPA1_CreateRequest") Create request failed with return code 209
In addition, workspaces requiring the support will display the following message on the TEP
and in the TEPS log:
KFWITM217E Request error: SQL1_CreateRequest failed, rc=209
•
•
SQL files that add to or update agent specific situations, templates, and policies in the
Enterprise Information Base (EIB). The EIB is a set of tables maintained at the HUB TEMS.
This information is also referred to as “seed data”; adding/updating the EIB with these SQL
files is also called “seeding”.
ODI files that describe the historical data attribute groups for the agent. These files are
installed on the TEPS. They are used for enabling historical collection for attribute groups to
allow historical data collection to occur, and to allow the Warehouse Proxy agent to properly
retrieve data from the agent persistent data store files for mapping into the Tivoli Data
Warehouse tables.
The application support file versions must be synchronized across the agent and the ITM infrastructure
components. If they are not, data will be missing, or not collected, or improperly collected. For
© IBM Copyright, 2012
(www.ibm.com/support/techdocs)
IBM Tivoli Monitoring Self-Describing Agent Feature: z/OS Considerations
May 2012
Page 1 of 8
example, one obvious sign of application support being out of sync is the presence of navigation tree
items and workspaces named Kxx:<string> in the TEP, where xx = the agent product code:
Current application support installation process
For z/OS agents, ensuring that application support is synchronized requires performing installation and
maintenance tasks on both z/OS and on the platforms where the TEP and, if not on z/OS, the Hub
TEMS, reside. The required steps for agent installation/maintenance are:
1. Install the agent code and/or maintenance code on z/OS via SMP/E.
2. Update the z/OS Runtime Environments (RTEs) using either the Installation and Configuration
Tool (ICAT) or PARMGEN methods.
3. Obtain the corresponding installation media for distributed platforms (the product application
support CD/DVD image, or, for maintenance, the fixpack image).
4. If the Hub TEMS is not on z/OS, install application support into the Hub TEMS using the
installation media.
5. Install application support into the TEPS using the installation media.
For non-z/OS agents reporting to a TEMS on z/OS, steps 3-5 above apply. The following steps must
also be performed on the TEPS platform, for the TEMS on the z/OS the agent reports to, and for the
Hub TEMS if it is on z/OS:
1. The CAT/ATR files must be FTPed to the RKANDATV dataset of the Hub TEMS RTE.
2. Application support files for the TEMS must be installed from the TEPS, using either the
itmcmd manage GUI or the tacmd command line interface.
In many environments different organizations support the different platforms, and coordinating these
manual installation steps across organizations can be a challenge due to the different skills required. In
addition, each component that has been updated must be restarted for the updates to take effect.
Planned outages for the monitoring infrastructure are required.
© IBM Copyright, 2012
(www.ibm.com/support/techdocs)
IBM Tivoli Monitoring Self-Describing Agent Feature: z/OS Considerations
May 2012
Page 2 of 8
Self-Describing Agent application support installation process
With the self-describing agent (SDA) feature the installation/maintenance process becomes much
simpler. When it is enabled in the ITM infrastructure, agents with this feature have their application
support files automatically installed across all of the required components. The process works as
follows for agents running on z/OS:
1. The agent is installed using SMP/E (z/OS) or the installation package for the platform.
2. The z/OS RTE is customized and the agent is started.
3. When the agent connects to its TEMS, if the TEMS does not recognize the agent type, or if
maintenance has been added to the agent, the TEMS obtains the updated application support
files from the agent and installs them. The TEMS does not have to be restarted.
4. If the agent connected to a remote TEMS, the remote TEMS notifies the Hub that application
support needs to be updated, and sends the updates to the Hub TEMS. The Hub TEMS then
installs the updates. The Hub TEMS does not have to be restarted.
5. The Hub TEMS notifies the TEPS of the updated application support, and the TEPS obtains
the updates from the Hub TEMS and installs them. The TEPS does not have to be restarted.
The above steps are performed automatically and eliminate the need for manual installation of
application support on the TEPS or TEMS. In addition, the updated components do not require restart,
making the infrastructure more available. The only components that must be restarted are any TEP
clients that are active when the updates occur. The TEP client will receive a visual notification that an
update has occurred, and the user will have to log the client off then back on for it to be updated.
Enabling Self-Describing Agent support
For SDA to work, the following items must be in place:
•
The ITM Infrastructure (TEPS and TEMS) must be at ITM 6.23 or higher. The OMEGAMON
XE 5.1 z/OS and CICS agents require ITM 6.23 fixpack 1.
•
For agents that connect to a Remote TEMS, both the Hub and Remote TEMS must have SDA
enabled for the application support process to automatically work. If only the Hub is enabled,
agents with SDA support enabled that connect to any Remote TEMS that is not enabled will
not have their application support files added or updated. If the Hub is not enabled, no agents
with have their application support files added or updated.
•
The z/OS TEMS requires space in the z/OS Unix® System Services (USS) filesystem to store
and process the agent SDA packages. The appropriate folder structure must be created in USS;
the steps to do this are within the ICAT or PARMGEN configuration of the TEMS. For
planning purposes a Hierarchical File System (HFS) or zSeries File System (zFS) dataset at
least 50MB in size should be allocated for this purpose.
•
The z/OS TEMS requires access to a Java® runtime environment running under the IBM 31bit or 64-bit Java SDK Version 5 (or higher). The location of the runtime environment is
specified in the TEMS ICAT or PARMLIB configuration steps.
© IBM Copyright, 2012
(www.ibm.com/support/techdocs)
IBM Tivoli Monitoring Self-Describing Agent Feature: z/OS Considerations
May 2012
Page 3 of 8
•
The TEMS must be customized to enable the SDA function. The Hub TEMS, and the remote
TEMS if the agent connects to a remote TEMS, must have the following statement in their
configuration file (on z/OS it is the KDSENV file in the RKANPARU dataset):
KMS_SDA=Y
•
The agent must support the SDA feature. OMEGAMON XE for z/OS 5.1 and OMEGAMON
XE for CICS 5.1 are the first agents running on z/OS with this support. Agents with SDA
support must have the following statement in their configuration file to enable it:
TEMA_SDA=Y
For agents that run within a TEMS (such as the z/OS agent), that statement must be in the
TEMS KDSENV configuration file.
For TEMS and agents running on z/OS the PARMGEN or ICAT customization procedures will
add these statements to the proper configuration member (it can be added manually but then
will not be preserved if the agent or TEMS is reconfigured). The following example is for a
TEMS. For ICAT, a new option is added to the initial TEMS configuration panel:
Selecting that option provides access to configuring the parameters to enable SDA support:
© IBM Copyright, 2012
(www.ibm.com/support/techdocs)
IBM Tivoli Monitoring Self-Describing Agent Feature: z/OS Considerations
May 2012
Page 4 of 8
PARMGEN configuration will enable SDA in the TEMS by specifying the values as part of the
configuration profiles customization step:
000839
000840
000841
000842
000843
000844
000845
000846
000847
000848
000849
000850
000851
000852
000853
000810
•
** Enable TEMS Self-Describing Agent (SDA) processing:
** This is required if you are enabling the Self-Describing
** Agent (SDA) functionality in the z/OS TEMS and Agents:
** Note: By default, the KMS_SDA KDSENV parameter is:
** - initially disabled @ the Hub TEMS (KMS_SDA=N)
** - initially enabled @ the Remote TEMS (KMS_SDA=Y)
** Customize the parameter accordingly by uncommenting out the
** parameter and specifying the applicable value.
** Related PARMGEN CONFIG profile parameters:
**
- GBL_HFS_JAVA_DIRn
**
- GBL_DSN_SYS1_SBPXEXEC
**
- RTE_USS_RTEDIR
**
- KDS_KMS_SDA
**
- KDS_TEMA_SDA
**
- Kpp_AGT_TEMA_SDA (per Kpp Agent exploiting SDA)
KDS_KMS_SDA
"Y"
* Y, N
The TEPS must have the following statement in its configuration file:
TEPS_SDA=Y
This is added during TEPS configuration, if SDA support is selected.
Validating Self-Describing Agent activity
The agent and TEMS logs can be checked to verify the SDA status. The following messages will be
found in the TEMS log if the feature is enabled):
Self-Describing Agent feature enabled on local TEMS.
If the TEMS is enabled, these messages will be seen indicating that SDA updates are occurring:
Self-Describing Agent Installation started for PRODUCT "M5 ", with TEMS
"RTE02:CMS", VERSION_INFO "product_vrmf=05100000;tms_package_vrmf=05100000;
tps_package_vrmf=05100000;tpw_package_vrmf=05100000;".
KFASD100
Self-Describing Install Started for PRODUCT <M5 >, VER
<05100000>, ID <TMS>, IDVER <05100000>.
KFASD101
Self-Describing Install Completed Successfully for PRODUCT <M5>,
VER <05100000>, ID <TMS>, IDVER <0 5100000>.
Based on the level of auditing, The TEPS log and/or TEPS audit log will contain many messages
showing the download, extraction, and installation of the application support components. The
© IBM Copyright, 2012
(www.ibm.com/support/techdocs)
IBM Tivoli Monitoring Self-Describing Agent Feature: z/OS Considerations
May 2012
Page 5 of 8
following are a subset of the full messages showing the installation of the TEP (TPS) and client (TPW)
application support for OMEGAMON XE on z/OS:
<Msg Text="Self-Describing Agent processing started for: pc=KM5 version=05100000
and type=TPS." RBKey="KFW2000I" >
<Msg Text="Begin retrieving KM5MSMAN.txt from the TEMS." RBKey="KFW2002I" >
<Msg Text="Completed retrieval of KM5MSMAN.txt from the TEMS." RBKey="KFW2003I" >
<Msg Text="Begin retrieving KM5JSTPS.jar from the TEMS." RBKey="KFW2002I" >
<Msg Text="Completed retrieval of KM5JSTPS.jar from the TEMS." RBKey="KFW2003I" >
<Msg Text="Begin extracting TPS application support files for pc=KM5."
RBKey="KFW2004I" >
<Msg Text="Completed extraction of TPS application support files for pc=KM5."
RBKey="KFW2005I" >
<Msg Text="Begin loading TEPS application support for pc=km5." RBKey="KFW2006I" >
<Msg Text="Completed loading TEPS application support files for pc=km5."
RBKey="KFW2007I" >
<Msg Text="Self-Describing Agent processing completed for: pc=KM5 version=05100000
and type=TPS." RBKey="KFW2001I" >
<Msg Text="Self-Describing Agent processing started for: pc=KM5 version=05100000
and type=TPW." RBKey="KFW2000I" >
<Msg Text="Begin retrieving KM5MSMAN.txt from the TEMS." RBKey="KFW2002I" >
<Msg Text="Completed retrieval of KM5MSMAN.txt from the TEMS." RBKey="KFW2003I" >
<Msg Text="Begin retrieving KM5JSTPW.jar from the TEMS." RBKey="KFW2002I" >
<Msg Text="Completed retrieval of KM5JSTPW.jar from the TEMS." RBKey="KFW2003I" >
<Msg Text="Begin extracting TPW application support files for pc=KM5."
RBKey="KFW2004I" >
<Msg Text="Completed extraction of TPW application support files for pc=KM5."
RBKey="KFW2005I" >
<Msg Text="Self-Describing Agent processing completed for: pc=KM5 version=05100000
and type=TPW." RBKey="KFW2001I" >
For any logged on TEPS users the following indicator will appear just above the navigation tree.
Selecting it will display a detailed message:
© IBM Copyright, 2012
(www.ibm.com/support/techdocs)
IBM Tivoli Monitoring Self-Describing Agent Feature: z/OS Considerations
May 2012
Page 6 of 8
The agent will also appear in the navigation tree, but since the TEP client has not been restarted its
navigation tree and workspaces will contain the Kxx:<string> labels. Logging off then logging back
on will show the agent navigation tree correctly.
Planning Considerations
Although ITM 6.23 provides the SDA support for the infrastructure components, each agent must also
have the support to take advantage of the automatic installation process. Agents that do not have the
support will still have to use the manual procedures described above to keep the application support
files synchronized.
The best practice is to control the self-describing agent capability from the hub monitoring server. The
capability can be disabled individually at a remote monitoring server, portal server, or agent.
Once an instance of a self-describing agent is installed or updated, all agents of the same type will use
the updated application support files before they are updated. Normally this should not cause a
problem since the application support files are downward compatible. However, any data elements
added for the new agent version will not be provided by the old agent version. Data for some rows or
columns in the affected workspaces may be empty due to the older agent version instances not
providing that data.
© IBM Copyright, 2012
(www.ibm.com/support/techdocs)
IBM Tivoli Monitoring Self-Describing Agent Feature: z/OS Considerations
May 2012
Page 7 of 8
For more detailed SDA planning, customization, and troubleshooting information, the following
documented should be reviewed (all are available in the IBM Tivoli Monitoring and OMEGAMON
XE Information Center at
http://publib.boulder.ibm.com/infocenter/tivihelp/v15r1/index.jsp?toc=/com.ibm.itm.doc/toc.xml :
•
•
•
•
IBM Tivoli® OMEGAMON® XE and IBM Tivoli Management Services on z/OS® Common
Planning and Configuration Guide
IBM® Tivoli® Management Services on z/OS®: Configuring the Tivoli Enterprise Monitoring
Server on z/OS
IBM Tivoli Monitoring, Version 6.2.3 Fix Pack 1
IBM Tivoli Monitoring Troubleshooting Guide
© IBM Copyright, 2012
(www.ibm.com/support/techdocs)
IBM Tivoli Monitoring Self-Describing Agent Feature: z/OS Considerations
May 2012
Page 8 of 8