Article

Overview of the new 11.7.3 PAS for OE Watcher monitoring tool

« Go Back

Information

 
Article Number000090050
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
Cause
Resolution

Overview:

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, oewatcher.sh 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>:

$   oewatcher.sh start <script-name.oew>

Stopping Watcher:

$   oewatcher.sh 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/oewatcher.sh 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>
Example:
  • 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
Workaround
Notes
Progress Article:

000093193, How to enable Swagger for PASOE instance  
 
Attachment 
Last Modified Date4/17/2019 11:34 AM


Feedback
 
Did this article resolve your question/issue?

   

Your feedback is appreciated.

Please tell us how we can make this article more useful. Please provide us a way to contact you, should we need clarification on the feedback provided or if you need further assistance.

Characters Remaining: 1025