Progress KB - Overview of the new 11.7.3 PAS for OE Watcher monitoring tool

Did this article resolve your question/issue?



Overview of the new 11.7.3 PAS for OE Watcher monitoring tool

« Go Back


TitleOverview of the new 11.7.3 PAS for OE Watcher monitoring tool
URL NameOverview-of-the-new-11-7-3-PAS-for-OE-Watcher-monitoring-tool
Article Number000123954
EnvironmentProduct: OpenEdge
Version: 11.7.3 and later
OS: All Operating Systems
Other: Progress Application Server for OpenEdge, PASOE, oewatcher
Question/Problem Description
What is the PAS for OE Watcher tool?
What functionality does the new PASOE application CATALINA_HOME/bin/oewatcher provide?
How to use the PASOE Watcher tool CATALINA_BASE/bin/oewatcher?
How to execute the provided oewatcher .oew examples?
Steps to Reproduce
Clarifying Information
Error Message
Defect/Enhancement Number


OpenEdge 11.7.3 includes a prototype of Watcher for PAS for OpenEdge (a.k.a Watcher, a.k.a oewatcher) for Administrators to monitor and manage their instances using JMX (Java Management Extensions) queries.
  • Watcher is a script, on Linux/Unix and oewatcher.bat on Windows, installed in CATALINA_HOME/bin and copied to CATALINA_BASE/bin when an instance is created.
  • Watcher manages the scheduled execution of a JSON script (.oew file) which defines the JMX queries used to monitor a PASOE instance.

Packaged JSON example scripts:

Sample scripts are installed with the OpenEdge 11.7.3 Service Pack. These scripts are copied to any new instance’s bin/jmxqueries directory for customization when the instance is created. Information is written to:
  • logs/oewatcher-action-YYYY-MM-DD.log
  • logs/oewatcher-app-YYYY-MM-DD.log.
Additionally, a default.qry file is provided for use directly with the oejmx utility. 
  • AblObjectsReport.oew - Watches dynamically generated ABL Objects in application code.
  • RecycleAblAgents.oew - Watches agent's status and allows an Agent to be recycled when its age exceeds a threshold value.
  • AblMemcheckerReport.oew - Watches application general memory usage, helpful in identifying memory leaks in OpenEdge code. Intended for use by Technical Support and Engineering for complex memory usage code issues.
  • Default.qry - For use with the JMX Utility to run local JMX queries against an instance. Administrators can write custom queries. 

Using the oewatcher:

Watcher runs a single JSON based script at a time that runs JMX queries on a PASOE instance. Watcher overhead could affect performance; it should be used for as long as needed, and no longer. 

Before running Watcher:

Edit the target script (.oew) as described below in “How to use AblObjects” and “How to use RecycleAblAgents” sections.

Scheduling parameters are common to all scripts: "Schedule":{"StartDelay":3,"Interval":600}
  • StartDelay - Sets the number of seconds before the first execution of the script. 
  • Interval - Sets the number of seconds between the script executions. 
While default values are provided, these should be changed to match the duration of the application running on an instance. For example, the interval may need to be increased for long running transactions. 

Starting Watcher:

Watcher commands are limited to starting Watcher with a named script and stopping Watcher. Only one script can be run by Watcher at a time.

Starting Watcher requires <script-name.oew>:

$ start <script-name.oew>

Stopping Watcher:

$ stop

How to use AblObjects

The AblObjectsReport example script is useful for identifying memory leaks based on the objects created in the application code. 

1.    Edit <catalina_base>/bin/jmxqueries/AblObjectsReport.oew  
  • startTime: When to begin tracking, using American datetime format.
  • endTime: When to end tracking, using American datetime format.
2.    Start Watcher using the AblObjectsReport.oew script file. 
$   bin/ start bin/jmxqueries/AblObjectsReport.oew

3.    Allow the necessary time to pass between startTime and endTime to collect enough data.

4.    Manually stop Watcher.
$   bin/oewatcher stop
6.    Review the logs:
  • <catalina_base>/logs/oewatcher-action-YYYY-MM-DD.log -  Provides a summary of the items being watched. In this example lines 4-7 show no memory leaks and lines 9-18 show the occurrence.
User-added image
  • <catalina_base>/logs/oewatcher-app-YYYY-MM-DD.log - Provides complete details of the queries, including information about transports, URIs, Applications and ABLObjects and Source.
User-added image

How to use RecycleAblAgents

The RecycleAblAgents example script is useful for recycling Agents that have been running for longer than a specific time.

It can be helpful when a memory leak is detected. If the leak can’t be fixed immediately, Agents can be recycled based on how long they have been active, avoiding a crash and providing time to further diagnose and address the leak.

1.    Edit <catalina_base>/bin/jmxqueries/RecycleAblAgents.oew  
  • timeThreshold - Agent age in milliseconds, after which it will be stopped.
  • waitToFinish - Number of milliseconds the agent waits for current requests to finish before issuing a soft (trappable) STOP.
  • waitAfterStop - Number of milliseconds the agent waits after waitToFinish before issuing a hard STOP. After waiting waitToFinish milliseconds, if waitAfterStop is 0, the agent will not issue a soft STOP but instead immediately issue a hard STOP (untrappable).
2.    Start Watcher from the instance directory.
$   bin/oewatcher start bin/jmxqueries/RecycleAblAgents.oew
3.    Allow the necessary time to pass between startTime and endTime 

4.    Manually stop Watcher.
$   bin/oewatcher stop
6.    Review the logs:
  • <catalina_base>/logs/oewatcher-action-YYYY-MM-DD.log - To determine if Agents are being recycled.
  • <catalina_base>//logs/oewatcher-app-YYYY-MM-DD.log - Further details about the queries by reviewing the <instance>
  • The age on the first pass is 108.
  • As the log grows, the age gets closer to the threshold
  • When the age is 310639 ms, it exceeds the threshold and the STOP is executed.
  • Later as more requests are made a new Agent is created to handle those requests. 
User-added image
Progress Article:

000093193, How to enable Swagger for PASOE instance  
Last Modified Date4/17/2019 11:34 AM
Disclaimer The origins of the information on this site may be internal or external to Progress Software Corporation (“Progress”). Progress Software Corporation makes all reasonable efforts to verify this information. However, the information provided is for your information only. Progress Software Corporation makes no explicit or implied claims to the validity of this information.

Any sample code provided on this site is not supported under any Progress support program or service. The sample code is provided on an "AS IS" basis. Progress makes no warranties, express or implied, and disclaims all implied warranties including, without limitation, the implied warranties of merchantability or of fitness for a particular purpose. The entire risk arising out of the use or performance of the sample code is borne by the user. In no event shall Progress, its employees, or anyone else involved in the creation, production, or delivery of the code be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the sample code, even if Progress has been advised of the possibility of such damages.