Package apama :: Module correlator :: Class CorrelatorHelper
[hide private]
[frames] | no frames]

Class CorrelatorHelper

source code

Helper class for the Software AG Apama Event Correlator.

The Correlator Helper class has been designed for use as an extension module to the PySys System Test Framework, offering the ability to configure, start and interact with an Event Correlator. The usage pattern of the class is to create an instance per Correlator, and to then make method calls onto the instance to perform operations such as the injection of monitorscript or java JMON applications, the sending of events, deletion of named objects etc. For example:

       correlator = CorrelatorHelper(self)
       correlator.start(logfile="correlator.log")
       correlator.inject(filenames=["simple.mon"])

Process related methods of the class declare a method signature which includes named parameters for the most frequently used options to the method. They also declare the **xargs parameter to allow passing in of additional supported arguments to the process. The additional arguments that are currently supported via **xargs are:

       workingDir: The default value for the working directory of a process
       state: The default state of the process (pysys.constants.BACKGROUND | pysys.constants.FOREGROUND)
       timeout: The default value of the process timeout
       stdout: The default value of the process stdout
       stderr: The default value of the process stderr
       arguments: List of extra arguments to be passed to the process

This means that legitimate calls to the start method include:

       correlator.start(logfile="correlator.log")
       correlator.start(logfile="correlator.log", stdout="correlator1.out")
       correlator.start(state=FOREGROUND, timeout=5)
Instance Methods [hide private]
 
__init__(self, parent, port=None, host=None)
Create an instance of the CorrelatorHelper class.
source code
 
addToClassPath(self, path)
Add the supplied path to the CLASSPATH environment variable for starting this instance.
source code
 
addToPath(self, path)
Add the supplied path to the PATH (win32) or LD_LIBRARY_PATH (unix) environment variable for starting this instance.
source code
 
start(self, logfile=None, verbosity=None, java=None, Xclock=None, environ=None, **xargs)
Start the Correlator.
source code
 
receive(self, filename=None, filedir=None, channels=[], suppressBatch=True, zeroAtFirstBatch=None, utf8=False, **xargs)
Attach a receiver to the Correlator.
source code
 
watch(self, filename=None, filedir=None, raw=False, interval=None, **xargs)
Obtain runtime operational status from the Correlator.
source code
 
injectMonitorscript(self, filenames=[], filedir=None, utf8=False, **xargs)
Inject MonitorScript into the Correlator.
source code
 
injectJMON(self, filename, filedir=None, **xargs)
Inject a JMON java application into the Correlator.
source code
 
injectScenario(self, filename, filedir=None, debug=False, blocks=None, functions=None, **xargs)
Inject a Scenario into the Correlator.
source code
 
send(self, filenames=[], filedir=None, loop=None, utf8=False, doNoBatch=False, **xargs)
Send events into the Correlator.
source code
 
delete(self, names=[], filename=None, filedir=None, force=False, kill=False, all=False, utf8=False, **xargs)
Delete named objects from the Event Crrelator.
source code
 
manage(self, **xargs)
Execute management operations against the Correlator.
source code
 
connect(self, source, channel=None, **xargs)
Connect a Correlator to this instance as a source.
source code
 
disconnect(self, source, channel=None, **xargs)
Disconnect a correlator to this instance as a source correlator.
source code
 
applicationEventLogging(self, enable=True)
Enable and disable application event logging.
source code
 
setApplicationLogFile(self, filename=None, filedir=None)
Set the application log file name.
source code
 
setApplicationLogLevel(self, verbosity)
Set the application log level.
source code
 
profilingOn(self)
Inform the Event Correlator to start collecting profiling statistics.
source code
 
profilingOff(self)
Inform the Event Correlator to stop collecting profiling statistics.
source code
 
profilingReset(self)
Inform the Event Correlator to reset it's collection of profiling statistics.
source code
 
profilingGet(self, filename, filedir=None)
Obtain the latest profiling statistics from the Event Correlator.
source code
 
toStringAll(self, filename, filedir=None)
Obtain a stringified representation of the current application state from the Event Correlator.
source code
 
waitForCorrelatorUp(self, timeout=20)
Block until the Correlator declares itself to be ready for processing.
source code
 
flush(self, timeout=60, count=1, **xargs)
Make sure all events have been flushed through the correlator.
source code
 
__inject(self, filenames=[], filedir=None, utf8=False, java=False, **xargs)
Inject an application into the correlator.
source code
 
__createScenarioManagerConfig(self, blocks=None, functions=None)
Create the Scenario Manager configuration file for the location of all blocks and functions.
source code
Instance Variables [hide private]
dictionary environ
The environment for running the Correlator
string host
Hostname for interaction with a remote Correlator
pysys.basetest parent
Reference to the PySys testcase instantiating this class instance
integer port
Port used for starting and interaction with the Correlator
Method Details [hide private]

__init__(self, parent, port=None, host=None)
(Constructor)

source code 

Create an instance of the CorrelatorHelper class.

If no port parameter is used in the argument list an available port will be dynamically found from the OS and used for starting the Correlator, and performing all operations against it. The host parameter is only used to perform operations against a remote Correlator started external to the PySys framework - the class does not support the starting of a Correlator remote to the localhost.

Parameters:
  • parent - Reference to the parent PySys testcase
  • port - The port used for starting and interacting with the Correlator
  • host - The hostname used for interaction with a remote Correlator

start(self, logfile=None, verbosity=None, java=None, Xclock=None, environ=None, **xargs)

source code 

Start the Correlator.

Parameters:
  • logfile - Name of the Correlator log file
  • verbosity - The verbosity level of the Correlator logging
  • java - If pysys.constants.False then the Correlator will be started with support for JMON applications
  • Xclock - If pysys.constants.True then the Correlator will be started in externally clocked mode
  • xargs - Variable argument list for the additional supported process parameters

receive(self, filename=None, filedir=None, channels=[], suppressBatch=True, zeroAtFirstBatch=None, utf8=False, **xargs)

source code 

Attach a receiver to the Correlator.

Parameters:
  • filename - The basename of the file to write events received from the Correlator to
  • filedir - The directory to write filename to (defaults to testcase output subdirectory)
  • channels - List of channel names to subscribe to
  • suppressBatch - Do not include BATCH timestamps in the output
  • zeroAtFirstBatch - Measure BATCH timestamps from when the first batch arrived
  • utf8 - Write output in UTF8
  • xargs - Variable argument list for the additional supported process parameters

watch(self, filename=None, filedir=None, raw=False, interval=None, **xargs)

source code 

Obtain runtime operational status from the Correlator.

Parameters:
  • filename - The basename of the file to write the runtime operational status to
  • filedir - The directory to write filename to (defaults to testcase output subdirectory)
  • raw - Obtain csv format data when logging to file
  • interval - The polling interval (seconds) between logging to file
  • xargs - Variable argument list for the additional supported process parameters

    Note that when outputing data in the raw (csv) format, the column identifiers and their positions are defined by:

           Uptime = 0
           Number of monitors = 1
           Number of mthreads = 2
           Number of java applications = 3
           Number of listeners = 4
           Number of sub-listeners = 5
           Number of event types = 6
           Number of events on input queue = 7
           Number of events received = 8
           Number of events on the route queue = 9
           Number of events routed = 10
           Number of attached consumers  = 11
           Number of events on output queue = 12
           Number of output events created = 13
           Number of output events sent = 14
           Number of events processed = 15
    

injectMonitorscript(self, filenames=[], filedir=None, utf8=False, **xargs)

source code 

Inject MonitorScript into the Correlator.

Parameters:
  • filenames - List of the basename of monitorscript files to inject into the Correlator
  • filedir - Directory containing the input monitorscript files (defaults to testcase input directory)
  • utf8 - Assume input is in UTF8
  • xargs - Variable argument list for the additional supported process parameters

injectJMON(self, filename, filedir=None, **xargs)

source code 

Inject a JMON java application into the Correlator.

Parameters:
  • filename - The basename of the jar file to inject into the Correlator
  • filedir - The directory containing filename (defaults to testcase input subdirectory)
  • xargs - Variable argument list for the additional supported process parameters

injectScenario(self, filename, filedir=None, debug=False, blocks=None, functions=None, **xargs)

source code 

Inject a Scenario into the Correlator.

Parameters:
  • filename - The basename of the scenario definition file to inject into the Correlator
  • filedir - The directory containing filename (defaults to testcase input subdirectory)
  • debug - Generate debug monitorscript
  • blocks - Sequence of tuples, where each tuple contains a block catalog name and location
  • functions - Sequence of tuples, where each tuple contains a function catalog name and location
  • xargs - Variable argument list for the additional supported process parameters

send(self, filenames=[], filedir=None, loop=None, utf8=False, doNoBatch=False, **xargs)

source code 

Send events into the Correlator.

Parameters:
  • filenames - List of the basename of event files to send into the Correlator
  • filedir - Directory containing the input event files (defaults to testcase input directory)
  • loop - Number of times to loop through the input file
  • utf8 - Assume input is in UTF8
  • doNoBatch - Do not automatically batch events
  • xargs - Variable argument list for the additional supported process parameters

delete(self, names=[], filename=None, filedir=None, force=False, kill=False, all=False, utf8=False, **xargs)

source code 

Delete named objects from the Event Crrelator.

Parameters:
  • names - List of names to delete from the Correlator
  • filename - The basename of a file containing a set of names to delete
  • filedir - The directory containing filename (defaults to testcase input subdirectory)
  • force - Force deletion of names even if they are in use
  • kill - Kill name even if it is a running monitor
  • all - Delete everything in the Correlator
  • utf8 - Assume input is in UTF8
  • xargs - Variable argument list for the additional supported process parameters

manage(self, **xargs)

source code 

Execute management operations against the Correlator.

Parameters:
  • xargs - Variable argument list for the additional supported process parameters

connect(self, source, channel=None, **xargs)

source code 

Connect a Correlator to this instance as a source.

Parameters:
  • source - An instance of the CorrelatorHelper class to act as the source
  • channel - The channel to make the connection on
  • xargs - Variable argument list for the additional supported process parameters

disconnect(self, source, channel=None, **xargs)

source code 

Disconnect a correlator to this instance as a source correlator.

Parameters:
  • source - An instance of the CorrelatorHelper class acting as the source
  • channel - The channel to be disconnected
  • xargs - Variable argument list for the additional supported process parameters

applicationEventLogging(self, enable=True)

source code 

Enable and disable application event logging.

Provides a wrapper around the engine_management command line tool to enable and disable application event logging. Once enabled, application event logging will log to the correlator log file information specific processing occurrences, e.g. the receipt of events for processing, the triggering of listeners, execution of the garbage collector etc.

Parameters:
  • enable - Set to True to enable, set to False to disable event logging

setApplicationLogFile(self, filename=None, filedir=None)

source code 

Set the application log file name.

On setting the application log file details, the output of all native log commands within MonitorScript will be logged to the designated log file. This allows seperation between the log statements written by the Event Correlator i.e. for status, errors etc, and those generated by the actual application.

Parameters:
  • filename - The basename of the file to write the application log file to
  • filedir - The directory to write filename to (defaults to testcase output subdirectory)

setApplicationLogLevel(self, verbosity)

source code 

Set the application log level.

Parameters:
  • verbosity - The verbosity level of the application logging

profilingGet(self, filename, filedir=None)

source code 

Obtain the latest profiling statistics from the Event Correlator.

Parameters:
  • filename - The basename of the file to write the profiling statistics to
  • filedir - The directory to write filename to (defaults to testcase output subdirectory)

toStringAll(self, filename, filedir=None)

source code 

Obtain a stringified representation of the current application state from the Event Correlator.

Parameters:
  • filename - The basename of the file to write the dump of application state to
  • filedir - The directory to write filename to (defaults to testcase output subdirectory)

flush(self, timeout=60, count=1, **xargs)

source code 

Make sure all events have been flushed through the correlator.

Currently implemented by using the flushAllQueues management request. Will initate a cycle where each queue in the correlator is drained, optionally repeated count times. This is useful when you have a multi-context application.

Parameters:
  • timeout - The amount of time to wait
  • count - The number of times to ensure queues are flushed
  • xargs - Variable argument list for the additional supported process parameters