How to configure an Enforced Monitor

Scope

Monitors are JobScheduler configuration objects that carry out job pre- and post-processing operations:
- A typical pre-processing operation would be checking for the presence of files.
- A typical post-processing operation would be starting an error handling job chain.
Enforced Monitors are Monitors that are applied to jobs by the JobScheduler, independently of the configuration of the individual jobs. This is in contrast with Named Monitors, which are specified for individual jobs.
Filters are available for both the Enforced Monitors themselves and the jobs the Monitors are applied to.

Use Case

Enforced Monitors allow the centralized configuration of pre- and post-processing operations to be configured and applied independently of the jobs being executed.
Typical applications for this feature could be:
- checking the availability of data and configuration files before processing is started and
- the implementation of error handling procedures.

Feature Availability

FEATURE AVAILABILITY STARTING FROM RELEASE 1.9

Related Issues

JS-1324 - Getting issue details... STATUS
JS-1323 - Getting issue details... STATUS
JS-1322 - Getting issue details... STATUS

Implementation

Enforced Monitors are implemented in two stages:

Configuration of the so-called GlobalMonitorPlugin, which is included by default in JobScheduler installations. This plugin is activated and configured in JobScheduler's scheduler.xml file.
The JobScheduler's scheduler.xml file is located in the $SCHEDULER_DATA/config folder, where $SCHEDULER_DATA is the directory used for JobScheduler's configuration and log files.
- The GlobalMonitorPlugin takes temporary control of the processing of jobs as soon as either the JobScheduler is started or jobs are added or modified in the live folder. The JobScheduler then adds the Monitors that are to be applied to jobs to the job configurations.
  - The JobSCheduler Operating Center, JOC, has a "show configuration" function that can be used to verify whether the plugin has added a Monitor. This is useful as the configuration of Enforced Monitors is neither shown in the JobScheduler Object Editor, JOE, nor in the 'standard' JOC interface.
- The GlobalMonitorPlugin can be configured to allow filtering of both the jobs which Monitors are applied to and the Monitors that are applied to these jobs.
- The folder structure in the live folder can be also be used to determine whether or not a particular Monitor is applied to a particular job:
  - Monitors can be applied to jobs in the same folder as the Monitor or recursively in all child folders.
  - Enforced Monitors cannot be specified for sibling folders.

Configuration of the Monitors themselves, which are JobScheduler objects that are saved in the JobScheduler's live folder.
- Enforced implementation of Monitors occurs when Monitors are identified by the GlobalMoitorPlugin - i.e.when their name matches the filter criteria configured for the plugin.
- The use of Monitors is described in detail in How to Configure a Named Monitor article.
- Both Enforced Monitors and Named Monitors can be specified together in a JobScheduler live folder. The interplay between both types of Monitors, i.e. order in which the different Monitors are applied to jobs, will be described later in this article.

Enforced Monitor Examples

Download the example configuration

Download JobScheduler_Examples_Monitors.zip
Unpack the contents of the folder to a folder in the JobScheduler's live folder.

Example description and use

The example configuration allows the use of Enforced Pre-/Post-Processing Monitors to be shown as well as their interaction with Named Monitors.

The following screenshot shows the configuration of the example folders, orders, job chains and jobs in the JobScheduler Operations Center, JOC.

Not directly visible in JOC are the Monitors themselves, which will be described in the next section.

Example File Object Structure

The following list shows the example's folder and Monitor structure. (Folders are in bold, jobs and Monitors in normal text)

Examples
global_show_all_order_parameters_pre_top.monitor.xml
- Monitors
  global_show_all_order_parameters_pre.monitor.xml
  global_show_all_order_parameters_post.monitor.xml
  - Monitor_Folder_1
    Job_1_1
    Job_1_2
    show_all_order_parameters_pre.monitor.xml show_all_order_parameters_post.monitor.xml
  - Monitor_Folder_2
    Job_2_1
    global_show_all_order_parameters_pre_folder2.monitor.xml

The example is configured with a number of similar Monitor elements:

For the purpose of this example all Monitors contain similar scripts that
- identify the Monitor in the log file through a simple echo of the Monitor's name and
- prints information about the order parameters.
The most significant differences between the Monitors lie in their names and the script function that determines whether the Monitor is to be implemented as a Pre-Processing or Post-Processing Monitor.
- The name prefix global_ is used to identify those Monitors that will be used as Enforced Monitors.
The Enforced Monitors saved in the Examples and Monitors folders of the example are applied to all jobs in both folders and their child folders.
- As an Enforced Monitor its default use is that it is applied recursively to all jobs in its current folder and all sub-folders. Filters are available that can be used to restrict the jobs that the Monitor is applied to.
Job 1_1 in Monitor_Folder_1 and Job 2_1 in Monitor_Folder_2 have both been configured to use Named Monitors, which have been saved in the respective Monitor_Folder_1.
- These Monitors are functionally similar to the Monitors used as Enforced Monitors and have been configured for pre-processing.
- These Monitors will not be called as Enforced Monitors as they do not have the global_ prefix in their names.
- As Named Monitors these Monitor are only applied when specified in the individual jobs.

Running the Example

The example orders are started by clicking on the Order menu button as shown in the screenshot above and selecting Start order now. This should be carried out for the order in each folder (Order 1_0 and Order 2_0 respectively)

The log files for the two orders should then are opened by clicking on the Order ID links in the ID column in JOC's Order History panel for each order. (This panel is at the foot of the above screenshot when the Show order history checkbox is checked.)

Example Behavior

The behavior of the example orders can be followed in the log files:

Enforced Monitor Implementation:
- The Monitors saved in the Examples and Monitors folders are applied as Enforced Monitors due to their global_ name prefix.
- These Monitors will be applied to all jobs in both folders.
- The Monitor saved in the Monitor_Folder_2 folder is also applied as an Enforced Monitor but only to the job in the Monitor_Folder_2 folder (and to jobs in any child folders).
All jobs in both folders will be executed after the Enforced Pre-Processing Monitors have been carried out.
In addition, Job_1_1 in Monitor_Folder_1 and Job_2_1 in Monitor_Folder_2 will call the Named Pre-Processing Monitor saved in Monitor_Folder_1 .
Output from all example Monitors can be seen in the relevant order log files for the job chains in each folder.

Enforced Monitor plugin configuration

The block below shows the configuration of the Enforced Monitor plugin, which is specified in the scheduler.xml file and which itself can be found in the $SCHEDULER_DATA/config folder.

Enforced Monitor Plugin Configuration

<config>
    <plugins>
        <plugin java_class="com.sos.scheduler.plugins.globalmonitor.GlobalMonitorPlugin">
            <plugin.config>
                <jobparams>
                    <param name="configuration_directory" value="C:/ProgramData/sos-berlin.com/jobscheduler/jobscheduler_1.10/config"/>
                    <param name="regex_selector" value="^job_.*\.job.xml$"/>
                    <param name="exclude_dir" value="sos"/>                           
                    <param name="exlude_file" value="xxx"/>
                </jobparams>
                <monitorparams>
                    <param name="use_parent_folders" value="true"/>
                    <param name="recursive" value="true"/>
                    <param name="regex_selector" value="^global_.*$"/>
                </monitorparams>
            </plugin.config>
        </plugin>
        ...
    </plugins>
    ...
</config>

The plugin configuration can be seen to consist of two main blocks - <jobparams> and <monitorparams>. The purpose of both configuration blocks is broadly to define which Monitors will be applied to which jobs.
- Changes to the plugin configuration will only be applied after a restart of the JobScheduler.
- The configuration_directory parameter should always be set to the $SCHEDULER_DATA/jobschedulerID/config value as shown in the listing. It is not possible to use this parameter to restrict the directories that are considered by the plugin.
- Both the job and Monitor parameter blocks have regex_selector parameters that are used to filter Monitor files and job files according to their names.
  - The ^global_.*$ value shown for the <monitorparams><param name="regex_selector"> means that only Monitor files with the prefix global_ will be applied.
  - If this parameter was not so restrictive then other Monitors that were intended for use as Named Monitors could also be implemented, if the <monitorparams><param name="recursive"> parameter was set to true.
- In addition the following optional parameters can be specified in both blocks:
  - exclude_dir
    - This parameter can be specified any number of times using comma-seperated list.
    - A directory will be excluded when the directory name ends with the given value in exclude_dir. E.g. the value sos will exclude the directory live/subfolder/sos and live/sos and live/subfolder2/subfolder3/sos
    - Monitor names should be specified without the ending .monitor.xml - i.e. exclude_file="/sos/subfolder/myMonitor" is translated to $SCHEDULER_HOME/config/live/sos/subfolder/myMonitor.monitor.xml
  - exclude_file
    - This parameter can be specified any number of times using comma-seperated list.
    - A file will be excluded when the job|monitor path ends is equal the given value in exclude_file. E.g. the value /myfolder/myjob will exclude the directory live/myfolder/myjob.job.xml
    - Job file names should be specified without the ending .job.xml - i.e. exclude_file="/sos/subfolder/myFile" is translated to $SCHEDULER_HOME/config/live/sos/subfolder/myFile.xml
  - recursive
    - This parameter can be specified using true/false.
    - The parameter has the default value true.
    - If true all files will be taken into consideration starting from the live folder
    - if false only file that are located in the live folder will be taken into consideration.

An Example Monitor Script

The next block shows a Pre-Processing Monitor where the Monitor script is embedded in a spooler_process_before() function:

An Example Monitor Script

    <monitors >
        <monitor  ordering="0" name="show_all_order_parameters">
            <script  language="java:javascript">
                <![CDATA[
function spooler_process_before(){

    spooler_log.info( ".. Start Monitor: global_show_all_order_parameters" );
    var parameters = spooler_task.order.params;
    spooler_log.info(".. Total number of order parameters: " + parameters.count());

    var names = parameters.names.split(";");
    for( i=0; i<parameters.count(); i++ ) {
        spooler_log.info( ".. parameter: " + names[i] + " = " + parameters.value( names[i] ) );
    }
    spooler_log.info( ".. End Monitor: global_show_all_order_parameters" );

    return true;
}
                ]]>
            </script>
        </monitor>

    </monitors>

The script in the above Monitor has been written for demonstrative purposes and lists the parameters for the current order in the order log file.
- In contrast to Named Monitors, changes to Enforced Monitors such as a name change will only be implemented after the JobScheduler has been restarted.
  Note that this does not apply for changes to the Monitor script, which are applied immediately after saving the files.
The scripts used for the Enforced Monitor and the Named Monitor in the example are practically identical - the only difference between the Monitors lying in their names, with the Enforced Monitors having the prefix global_.
- Note also that the global_ prefix is used in the regex_selector Monitor plugin configuration parameter to specify that the Monitor is to be used. Monitors without this prefix that may be located in the live folder and its sub-folders will be ignored.

Monitor script functions

Four functions are available for use with Monitor scripts:

Pre-Processing Monitors
- spooler_process_before()
- spooler_process_after(spooler_process_result)
Post-Processing Monitors
- spooler_task_before()
- spooler_task_after()

The most important difference between the spooler_process_after() and spooler_task_after() functions is that the spooler_task_after() function is able to handle return codes.

More detailed information about these functions can be found in the Monitors section of the JobScheduler reference documentation.

An example job script with Monitors

The next block shows a job configured to use Monitors through the monitor.use element. In this example it is a Named Monitor show_all_order_parameters_pre and a series of Enforced Monitors, as can be seen from the global_ name prefix, which matches the regex_selector monitor parameter specified for the GlobalMonitorPlugin and listed in the first block above.

Enforced Monitor elements are dynamically added to job configurations when jobs are loaded by JobScheduler.

An example job script with monitors

<job order="yes" stop_on_error="no" title="Shell Job 2_1">
    <script language="shell"><![CDATA[
        
        @echo .
        @echo %SCHEDULER_JOB_NAME% : job starting
        set /a number=%random% %%2 +1
        @echo .                                      
        @echo %SCHEDULER_JOB_NAME% : sleeping for %number% seconds.....
        @echo .                                      
        ping 127.0.0.1 -n %number% > nul
        @echo .                                      
        @echo %SCHEDULER_JOB_NAME% : job ending
        @echo .                                      
        
        ]]>
    </script>
    <monitor.use monitor="/Examples/Monitors/Monitor_Folder_1/show_all_order_parameters_pre" ordering="1"/>
    <monitor.use monitor="/Examples/global_show_all_order_parameters_pre_top"/>
    <monitor.use monitor="/Examples/Monitors/global_show_all_order_parameters_pre"/>
    <monitor.use monitor="/Examples/Monitors/Monitor_Folder_2/global_show_all_order_parameters_pre_folder2"/>
    <monitor.use monitor="/Examples/Monitors/global_show_all_order_parameters_post"/>
    <run_time/>
</job>

Note that as an Enforced Monitor the global_show_all_order_parameters_pre and global_show_all_order_parameters_post Monitors are specified using monitor.use elements that are added to the job by the Monitor plugin when the job is loaded.
- These monitor.use elements are not shown in JOE, as they are added by the GlobalMonitoringPlugin.
- monitor.use elements are, however, visible when the Show configuration operation is called for a relevant job in JOC, where the above listing was obtained.
  - The Show configuration function can be found by opening the Job node menu at the right hand side of the Job chain pane as shown in the screenshot of JOC above.
  - The order in which Monitors are listed in the example above will not determine the order in which the Monitors are implemented.
  - For example, Named Monitors, such as show_all_order_parameters_pre will be executed after the global Monitors although listed first.

Monitor Configuration in JOE

The screenshot below shows the configuration of an Enforced Monitor from the example in JOE:
- Both Enforced Monitor elements and Named Monitor elements can be configured using JOE.
  - The use of Named Monitors can also be specified in JOE as they are called from jobs.
  - The use of Enforced Monitors is configured
    - partly by the filter criteria specified as part of the GlobalMonitorPlugin configuration specified in the scheduler.xml file.
    - partly by their position in the file structure.
- The scripts used in the Monitors in the example are all written using the java:javascript language.
- The Monitor script shown uses the spooler_process_before() function to define the monitor as a Pre-Processing Monitor.
  - Post-Processing Monitors use a spooler_process_after() function.
  - The Monitor script itself has been written for demonstrative purposes and identifies the Monitor in the order log file and lists the order parameters.
- The sequence in which Monitors are executed is only partly regulated the Ordering parameter. In the example configuration the default value of 0 is used for all Monitors apart from the Named Monitor specified for the Job_2_1 job and shown in the the screenshot below.
  The sequence in which Monitors are executed also depends on:
  - the position of the Monitor in the file structure
  - whether the Monitor is a Pre-Processing or Post-Processing Monitor and
  - whether the Monitor is a Named Monitor or an Enforced Monitor.

The sequence in which Monitors are implemented is discussed below.

The Configuration of Named Monitors

The next screenshot shows how the use of a Named Monitor is specified for a job in the Job's Monitors Used tab..
- The Monitor is specified for using the Monitors used parameter and selecting the Monitor from a list of the Monitors in the same folder as the job.
- Again the Ordering is left with the default of 0.
The next screenshot shows how the same Named Monitor can be specified for another job in another folder:
As can be seen from the Pre-/Post-Processing element in the left hand panel of the screenshot, no other Monitor is defined in this folder.
In addition the Ordering has been set to 1. This will be discussed later.

Ordering the sequence of Enforced Monitor and Named Monitor execution

The order in which Enforced Monitors and Named Monitors are executed for a particular job depends on the following:

- the ordering parameter (default value 0)
- the position of the Monitor in the file structure
- whether the Monitor is a Pre-Processing or Post-Processing Monitor and
- whether the Monitor is a Named Monitor or an Enforced Monitor.

Ordering of Monitors through their position in the file structure

When a number of Enforced Monitors or Named Monitors are specified for a job then the position of these Monitors in the file structure determines the order in which these Monitors are executed:

Pre-Processing Monitors
- Monitors are in different folders:
  - Consider the job is in the folder a/b/c:
    - all spooler_process_before() Monitors in folder a will be executed before spooler_process_before() Monitors in folders b and c.
- Monitors in the same folder:
  - Monitors in the same folder will be executed according to the ordering attributes specified for the Monitors.
Post-Processing Monitors
- Monitors are in different folders:
  - Consider the job is in the folder a/b/c:
    - all spooler_process_after() Monitors in folder c will be executed before spooler_process_after() Monitors in folders b and a.
- Monitors in the same folder:
  - Monitors in the same folder will be executed according to the ordering attribute specified for the Monitors.

Ordering Monitors with the Ordering parameter

Monitors in the same folder:
- Monitors in the same folder will be executed according to the ordering attribute specified for the Monitors.
Monitors in different folders:
- The position of Monitors in the file structure will determine the order of execution as described above and will overwrite any ordering attributes.
Note that the Ordering field, which is located near the top right of JOE, and is shown in the screenshots above, is a property of the Monitor and is therefore not job-specific.

Ordering Enforced Monitors and Named Monitors with the Ordering parameter

When an Enforced Monitor and a Named Monitor are both run as Pre-Processing Monitors with ordering 0, the Named Monitor will be executed before the Enforced Monitor regardless of how much higher in the file order the Enforced Monitor is in the JobScheduler's file structure.

Log file output order

Note that the output from Post-Processing Monitors using the spooler_process_after() function may be listed before or partly before and partly after the output from a job shell script.
This is due to the shell script output, i.e. what is written to stdout, being logged after the script itself has been completed and this taking place after a Post-Processing Monitor has started.

This phenomenon should not occur when the spooler_task_after() function is used.

Modifying Monitors while Jobs are being executed (Monitor Tracking)

JobScheduler tracks changes to
- Monitor files and
- files included with Monitor files that make use of <include live_file="..."/> elements.
Adding, modifying and removing Monitor files or files included with Monitor files causes JobScheduler to
- terminate tasks that make use of the respective Monitor, i.e. the tasks are terminated with the current process step.
  The same behavior also applies for Schedules, Process Classes and Locks.
- reload the job.

Handling of result codes

Pre-Processing Monitors

If one of the Pre-Processing Monitors returns false then Monitor processing will be stopped.

Post-Processing Monitors

Return codes are handled after all Post-Processing Monitors have been executed, even if one of the Monitors returns false.
The return code of the last Üost-Processing Monitor sets the return code of the job
The value of spooler_process_result argument comes from the Monitor that was executed before the current Monitor.

References

Change Management References

T	Key	Linked Issues	Fix Version/s	Status	P	Summary	Updated

Loading...

Refresh

Documentation

The Monitors article
The How to configure a Named Monitor article
The How to add conditions for job execution with date calculation article
The How to use Job Post-processing to handle Exit Codes article
The Monitor XML Element in the JobScheduler Reference Documentation

Space shortcuts

Page tree

Scope

Use Case

Feature Availability

Related Issues

Implementation

Enforced Monitor Examples

Download the example configuration

Example description and use

Example File Object Structure

Running the Example

Example Behavior

Enforced Monitor plugin configuration

An Example Monitor Script

Monitor script functions

An example job script with Monitors

Monitor Configuration in JOE

The Configuration of Named Monitors

Ordering the sequence of Enforced Monitor and Named Monitor execution

Ordering of Monitors through their position in the file structure

Pre-Processing Monitors

Post-Processing Monitors

Ordering Monitors with the Ordering parameter

Ordering Enforced Monitors and Named Monitors with the Ordering parameter

Log file output order

Modifying Monitors while Jobs are being executed (Monitor Tracking)

Handling of result codes

Pre-Processing Monitors

Post-Processing Monitors

See also

References

Change Management References

Documentation