Exposing metrics to monitor your workload

To control and monitor your workload, you can have HCL Workload Automation for Z expose a number of metrics about the status of your jobs. By further analyzing these values through a data analytics tool, such as AI Data Advisor (AIDA), you detect anomalies and anticipate failure or degradations.

For more information about AIDA and how to use it, see AI Data Advisor (AIDA) User's Guide.

To enable the product REST APIs to retrieve and expose the metrics data, uncomment and set the following properties in the following file, then restart the Dynamic Workload Console server.
On Windows operating systems
<DWC_home>\usr\servers\dwcServer\resources\properties\TWSZOSMetricsConfig.properties
On UNIX operating systems
<DWC_DATA_dir>/usr/servers/dwcServer/resources/properties/TWSZOSMetricsConfig.properties
#com.hcl.hwa.zconn.metrics.jobcount.time = n 
#com.hcl.hwa.zconn.metrics.critical.time = n
#com.hcl.hwa.zconn.metrics.engine.list = engine_1 engine_2 ... engine_n
#com.hcl.hwa.zconn.metrics.count.delay = ss
#com.hcl.hwa.zconn.metrics.count.repeat = ss
com.hcl.hwa.zconn.metrics.jobcount.time
Specify a number higher than 0 to enable HCL Workload Automation to expose the metrics data about the jobs' statuses (application_wa_JobsByWorkstation_jobs and application_wa_JobsInPlanCount_jobs). The default is 0, meaning that the feature is not enabled.
com.hcl.hwa.zconn.metrics.critical.time
Specify a number higher than 0 to expose the metrics data about the critical jobs' statuses:
  • application_wa_criticalJob_potentialRisk
  • application_wa_criticalJob_highRisk
  • application_wa_criticalJob_confidence
  • application_wa_criticalJob_uncompletedPredecessor
  • application_wa_criticalJob_estimateEnd
The default is 0, meaning that the feature is not enabled.
com.hcl.hwa.zconn.metrics.engine.list
Specify the name of the HCL Workload Automation for Z engines, separated by spaces, whose jobs' statuses you want to monitor. The engine names must be coincident with those specified in the connectionFactory.xml file.

If you uncomment this property without specifying any name, all the z/OS engines connected to the Z connector are considered.

com.hcl.hwa.zconn.metrics.count.delay
Specify the delay, in seconds, before the Z connector starts the monitoring process. The default is 2.
com.hcl.hwa.zconn.metrics.count.repeat
Specify the frequency, in seconds, with which the monitoring process is to be repeated and the metrics exposed are updated. The default is 30.
The Z connector exposes the metrics data at the following address: 
https://DWC_hostname:DWC_port/metrics/
Metrics name and description shows a list of the metrics retrieved, along with their description.
Table 1. Metrics name and description
Metric Name Description
application_wa_JobsByWorkstation_jobs Jobs with a specific status on each workstation connected to the z/OS engine. The statuses monitored are: WAITING, READY, RUNNING, SUCCESSFUL, ERROR, CANCELED, HELD, UNDECIDED, BLOCKED, and SUPPRESS.
application_wa_JobsInPlanCount_jobs Jobs with a specific status in the Current Plan.
application_wa_criticalJob_potentialRisk Critical jobs whose risk level is Potential
application_wa_criticalJob_highRisk Critical jobs whose risk level is High
application_wa_criticalJob_confidence Confidence factor of the critical job
application_wa_criticalJob_uncompletedPredecessor Uncompleted predecessors of the critical job
application_wa_criticalJob_estimateEnd Estimated end of a critical job (seconds until estimated end time)
The following example shows the number of jobs that had a certain status on the following workstations connected to the Z controller twsw:
On workstation GEN1
12 jobs are SUCCESSFUL, 2 are CANCELED
On workstation CPU2
13 jobs are CANCELED
On workstation CPU1
10 jobs are SUCCESSFUL, 266 jobs are WAITING, 4 jobs are in ERROR
application_wa_JobsByWorkstation_job (engine="twsw", jobstatus="SUCCESSFUL",workstation="GEN1"} 12
application_wa_JobsByWorkstation_job (engine="twsw", jobstatus="CANCELED",workstation="GEN1"} 2
application_wa_JobsByWorkstation_job (engine="twsw", jobstatus="CANCELED",workstation="CPU2"} 13
application_wa_JobsByWorkstation_job (engine="twsw", jobstatus="SUCCESSFUL",workstation="CPU1"} 10
application_wa_JobsByWorkstation_job (engine="twsw", jobstatus="WAITING",workstation="CPU1"} 266
application_wa_JobsByWorkstation_job (engine="twsw", jobstatus="ERROR",workstation="CPU1"} 4
To connect to the database of the engine where the metrics are collected, perform the following steps:
  1. Browse to the zosEngineDatasource.xml template, which is located in:
    On Windows operating systems
    <DWC_home>\usr\servers\dwcServer\configDropins\templates\zconnectors
    On UNIX and z/OS operating systems
    <DWC_home>/usr/servers/dwcServer/configDropins/templates/zconnectors
  2. Copy the zosEngineDatasource.xml file to the following path:
    On Windows operating systems
    <DWC_home>\usr\servers\dwcServer\configDropins\overrides
    On UNIX operating systems
    <DWC_DATA_dir>/DWC_DATA/usr/servers/dwcServer/configDropins/overrides
    On z/OS operating system
    Ensure that you copy the file in binary mode. <DWC_DATA_dir>/DWC_DATA/usr/servers/dwcServer/configDropins/overrides.
    The content of the original zosEngineDatasource.xml file, as it is created in the zconnectors folder at installation time, is as follows:
    <!-- replace all variables with the proper connection property values -->
<server>
<dataSource id="$(zconnName)" jndiName="jdbc/zconndb/$(zconnName)" statementCacheSize="400" isolationLevel="TRANSACTION_READ_COMMITTED">
<jdbcDriver>
<library id="DBDriverZconnLibs">
<fileset dir="$(dbDriverPath)" includes="*" scanInterval="5s"/>
</library>
</jdbcDriver>
<connectionManager connectionTimeout="180s" maxPoolSize="300" minPoolSize="0" reapTime="180s" purgePolicy="EntirePool"/>
<properties.db2.jcc
driverType="4"
serverName="$(dbHostName)"
portNumber="$(dbPort)"
sslConnection="$(dbUseSsl)"
databaseName="$(dbName)"
user="$(dbUser)"
password="$(dbPassword)"
currentSchema="$(dbSchema)"
/>
</dataSource>
</server>
  3. Edit the file as necessary, specifying the following connection details:
    zconnName
    Name of the z/OS engine whose metrics you want to collect. This is coincident with the zconnName that you set in the connectionFactory.xml file.
    dbDriverPath
    Path where the database drivers are stored, by default <DWC_home>/jdbcdrivers. The supported databases are DB2 and DB2 for z/OS. This parameter is optional.
    dbHostName
    Host name or IP address of the database server.
    dbPort
    Port of the database server.
    dbUseSsl
    Enables or disables the SSL communication to the database. This value must always be false when the database is DB2 for z/OS. The default is false.
    dbName
    Name of the database.
    dbPassword
    Password of the database.
    dbSchema
    Schema of the database.

    Changes are effective immediately.