Deploying and Managing Apama Applications > Event Correlator Utilities Reference > Watching correlator runtime status
Watching correlator runtime status
The engine_watch tool lets you monitor the runtime operational status of a running event correlator. The executable for this tool is located in the bin directory of the Apama installation. Running the tool in the Apama Command Prompt ensures that the environment variables are set correctly.
Synopsis
To monitor the operation of an event correlator:
*On Windows, run engine_watch.exe.
*On UNIX, run engine_watch.
To obtain the following usage message, run the command without any options or with the –h option:
Usage: engine_watch [ options ]
To periodically poll status from a remote correlator.
Where options include:
  -h | --help              This message
  -n | --hostname <host>   Connect to an engine on <host>
  -p | --port <port>       Engine is listening on <port>
  -i | --interval <ms>     Poll every <ms> milliseconds
  -f | --filename <file>   Write to <file> instead of to standard out
  -r | --raw               Raw (i.e. parser friendly) output
  -t | --title             Add header to output (Raw mode only)
  -o | --once              Poll once then exit
  -v | --verbose           Be more verbose
  -V | --version           Print program version info
Description
This tool periodically polls an event correlator for status information, writing the returned status data to stdout. For additional progress information use the –v option.
The engine_watch tool returns the following information:
Status message
Meaning
Uptime (ms)
The time in milliseconds since this correlator was started. This figure is unaffected if the state of the correlator is restored from a checkpoint file.
Number of monitors
The number of EPL monitor definitions injected into the correlator. This figure changes upwards and downwards as monitors are injected, deleted or just expire. A monitor expires when each of its instances dies, or it has no listeners or streams left, or it causes a runtime error.
Number of sub-monitors
The number of EPL monitor instances across all contexts in the correlator. In monitors, spawn actions create monitor instances. This figure changes upwards and downwards as monitor instances are spawned, killed or just expire.
Number of contexts
The number of contexts in the correlator. This includes the main context plus any user-defined contexts.
Number of Java applications
The number of Java applications loaded in the correlator. Java applications do not expire, so this value only decreases when you explicitly unload a Java application.
Number of listeners
This is the sum of listeners in all contexts. This includes each on statement and each stream source template, for example, all Tick(symbol=”APMA”) in the following:
stream<Tick> ticks := all Tick(symbol=”APMA”);
Number of sub-listeners
The number of sub-listeners that have been created by listeners across all contexts. A stream source template always has exactly one sub-listener. An on statement can have multiple sub-listeners.
Number of event types
The total number of event types defined within the correlator. This figure decreases when you delete event types from the correlator.
Events on input queue
Total number of events waiting to be processed on all input queues. The main context has its own input queue and any user-defined contexts each have an input queue.
Events received
The total number of events ever received by the correlator. A checkpoint preserves this value. If you restore the state of the correlator from a checkpoint file, this number reflects the total number of the events seen by the correlator from which the checkpoint was originally made.
Note that if an event is on an input queue, it has been received but not processed.
Events processed
The total number of events processed by the correlator in all contexts. This includes external events and events routed to contexts by monitors. An event is considered to have been processed when all listeners and streams that were waiting for it have been triggered, or when it has been determined that there are no listeners for the event.
Events on internal queue
Total number of routed events waiting to be processed across all contexts. The internal routing queue in each context is a high priority queue for events that you internally routed with the route instruction in EPL. The correlator always processes events on the internal queue before any events on the normal input queue.
Events routed internally
The total number of events ever routed internally to the internal queues on this correlator. A checkpoint preserves this value. If you restore the state of a correlator from a checkpoint file, this number reflects the total number of the events routed to the internal queues for the correlator from which the checkpoint was originally made.
Number of consumers
The number of event consumers registered with the correlator. Event consumers receive events emitted by the correlator.
Events on output queue
The number of events waiting on the correlator’s output queue to be dispatched to any registered event consumers.
Output events created
The total number of output events created by the correlator. A checkpoint preserves this value. If you restore the state of a correlator from a checkpoint file, this number reflects the total number of output events created by the correlator from which the checkpoint was originally made.
Output events sent
The total number of output events that the correlator has sent to event consumers. For example, suppose the correlator created 10 output events and sent each event to two consumers. The number of output events sent is 20. A checkpoint preserves this value. If you restore the state of a correlator from a checkpoint file, this number reflects the total number of output events sent by the correlator from which the checkpoint was originally made.
Event rate over last interval (ev/s)
The number of events per second currently being processed by the correlator across all contexts. This value is computed with every status refresh and is only an approximation.
Options
The tool engine_watch.exe (on Windows) or engine_watch (on UNIX) takes a number of command line options. These are:
Option
Description
-h
Displays usage information. Optional.
-n host
Name of the host on which the event correlator is running. Optional. The default is localhost.
Note: Non-ASCII characters in host names are not supported.
-p port
Port on which the event correlator is listening. Optional. The default is 15903.
-i ms
Specifies the poll interval in milliseconds. Optional. The default is 1000.
-f file
Writes status output to the named file. Optional. The default is to send status information to stdout.
-r
Indicates that you want raw output format, which is more suitable for machine parsing. Raw output format consists of a single line for each status message. Each line is a comma-separated list of status numbers. This format can be useful in a test environment.
If you do not specify that you want raw output format, the default is a multi-line, human-readable format for each status message.
-t
If you also specify the --raw option, you can specify the --title option so that the output contains headers that make it easy to identify the columns.
-o
Outputs one set of status information and then quits. Optional. The default is to indefinitely return status information at the specified poll interval.
-v
Displays process names and versions in addition to status information. Optional. The default is to display only status information.
-V
Displays version information for the engine_watch tool. Optional. The default is that the tool does not output this information.
Exit status
The engine_watch tool returns the following exit values:
Status
Description
0
All status requests were processed successfully.
1
No connection to the event correlator was possible or the connection failed.
2
Other error(s) occurred while requesting/processing status.
Copyright © 2013 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or Terracotta Inc., San Francisco, CA, USA, and/or Software AG (Canada) Inc., Cambridge, Ontario, Canada, and/or, Software AG (UK) Ltd., Derby, United Kingdom, and/or Software A.G. (Israel) Ltd., Or-Yehuda, Israel and/or their licensors.