Introduction
The JITL MonitoringJob template can be used to perform health checks of JS7 JOC Cockpit, Controller and Agents. Health check results can be forwarded, for example by mail.
- Users can use health status results for integration with their monitoring system.
- SOS offers a 24/7 Monitoring Service to receive health status results of customers using a commercial license who subscribe to this support option, see JS7 - License.
The JITL MonitoringJob template can be used as a building block in a monitoring solution to
- repeatedly running the MonitoringJob template using a JS7 - Cycle Instruction,
- forwarding health check results to a monitoring solution.
- this can include to forward health check report files when used with a user's monitoring solution.
- this can include to send e-mail indicating a notice or an alert to SOS. Such notices do not include any data related to the user's JS7 environment, they indicate a notice or alert only
- Alert mails are simplistic like this
The job template makes use of the JS7 - REST Web Service API to retrieve information from the JOC Cockpit.
- The job template authenticates with the JS7 - REST Web Service API by use of user account/password and/or by use of a certificate, for details see JS7 - Authentication.
- For details about configuration items see JS7 - JITL Common Authentication.
FEATURE AVAILABILITY STARTING FROM RELEASE 2.4.1
Usage
When defining the job either:
- invoke the Wizard that is available from the job properties tab in the Configuration view and select the JITL MonitoringJob and relevant arguments from the Wizard
or
- specify the
JITL
job class andcom.sos.jitl.jobs.monitoring.MonitoringJob
Java class name and add arguments specifying the variables that are expected to be carried by incoming files.
Example
Download (upload .json): pdmMonitoring.workflow.json
Using the Example
It is recommended to start from the example and to adjust the parameterization:
Explanation:
- A JS7 - Cycle Instruction is used in order to repeatedly perform health status checks.
- Users should adjust cycles to their monitoring needs.
- A JS7 - Retry Instruction is used in order to retry execution, for example of the MailJob included in case that e-mail cannot be sent.
- The MonitoringJob is used to perform the health status check.
- The MailJob is used to send notices and alerts by mail. This is an option, users might apply other means to forward notices and alerts.
The Cycle Instruction is configured like this:
Explanation:
- A ticking cycle is used in order to perform health status checks precisely at the given hour and minute.
- The cycle runs in hourly intervals for any days of week.
- The cycle period starts at midnight and lasts 24 hours.
- This example results in 24/7 coverage with the health status check being performed every hour.
The Retry Instruction is configured like this:
Explanation:
- If any of the jobs included in the Retry Instruction fails then execution is resumed starting from the first job.
- Execution is repeated up to 3 times unless successful. The same interval of 1 minute is applied for each retry.
The MonitoringJob makes use of arguments that are explained with chapter Using the Job Wizard for the MonitoringJob.
The MailJob is explained from the JS7 - JITL MailJob article.
Using the Job Wizard for the MonitoringJob
You can use the job wizard like this:
Explanation:
- Add an empty job from the instruction panel.
- Specify a name and a label for the job.
- Select an Agent.
In a next step invoke the job wizard that you find in the upper right corner of the job property editor. The wizard brings up the following popup window:
Explanation:
- From the list of available job templates select the MonitoringJob.
Then hit the "Next" button to make the job wizard display available arguments:
Explanation:
controller_id
: Optionally specifies the identification of the Controller to be checked. By default the current Controller is used.monitor_report_dir
: Specifies the directory to which the job will store health status report files (.json). The directory has to exist prior to running the job and has to be in reach of the Agent that runs the job.- An absolute or relative path can be specified.
- An expression can be used. The example makes use of
env('JS7_AGENT_DATA') ++ '/monitor'
which translates to use of theJS7_AGENT_DATA
environment variable created by the Agent's start script, see JS7 - Job Environment Variables. The environment variable can for example evaluate to/var/sos-berlin.com/js7/agent
. The ++ operator indicates concatenation and is followed by the name of a sub-directory. In this example the report directory will be/var/sos-berlin.com/js7/agent/monitor
.
monitor_report_max_files
: The number of report files created will be limited to this value. Older report files will be removed when this value is exceeded.from
: Specifies the e-mail address that is used to send mail for notices and alerts. The argument is used by the job to create thesubject
andbody
return variables for use with a later MailJob.- Select the check box provided with each argument if you want this argument to be added to the arguments of the MonitoringJob template.
When hitting the Submit button the wizard adds the required arguments to the job which should look like this:
Using the Job Wizard for the MailJob
Find instructions from the JS7 - JITL MailJob article.
Use of JS7 - Job Resources to specify mail parameterization is encouraged.
Documentation
The Job Documentation including the full list of arguments can be found under: https://www.sos-berlin.com/doc/JS7-JITL/MonitoringJob.xml
The MonitoringJob class accepts the following arguments:
Arguments
Name | Required | Default Value | Purpose | Example |
---|---|---|---|---|
controller_id | no | Optionally specifies the identification of the Controller to be checked. By default the current Controller is used. | controller_prod | |
| yes | Specifies the directory to which the job will store health status report files (.json). The directory has to exist prior to running the job and has to be in reach of the Agent that runs the job.
|
| |
monitor_report_max_files | yes | The number of report files created will be limited to this value. Older report files will be removed when this value is exceeded | 25 | |
from | yes | Specifies the e-mail address that is used to send mail for notices and alerts. The argument is used by the job to create the | js7@example.com |
Return Variables
Name | Data Type | Purpose | Example |
---|---|---|---|
monitor_report_date | String | The date and time for which the health status check has been performed. The date format is | controller_prod |
monitor_report_file | String | The path to the report file created for the health status check. | /var/sos-berlin.com/js7/agent/monitor/monitor.2022-08-15.17-35-36.5.json |
subject | String | The subject of an e-mail for use with a later MailJob. | JS7 Monitor: Notice from: js7@sos-berlin.com at: 2022-08-15.17-35-36.5 |
body | String | The body of an e-mail for use with a later MailJob, by default the value is the same as for the | JS7 Monitor: Notice from: js7@sos-berlin.com at: 2022-08-15.17-35-36.5 |
result | Number | The number of problems identified during the health status check. A value 0 indicates absence of problems, other values indicate existence of problems. | 0 |