Apama Documentation : Deploying and Managing Apama Applications : 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 (see Setting up the environment using the Apama Command Prompt) ensures that the environment variables are set correctly.
Synopsis
To monitor the operation of an event correlator, run the following command:
engine_watch [ options ]
When you run this command with the –h option, the usage message for this command is shown.
Description
This tool periodically polls an event correlator for status information, writing the standard status messages to stdout (see the status messages listed further below). When you also specify the -a option, any user-defined status values are appended to the standard status messages. For additional progress information, use the –v option.
Options
The engine_watch tool takes the following options:
Option
Description
-h | --help
Displays usage information. Optional.
-n host | --hostname host
Name of the host on which the event correlator is running. The default is localhost. Non-ASCII characters are not allowed in host names.
-p port | --port port
Port on which the event correlator is listening. Optional. The default is 15903.
-i ms | --interval ms
Specifies the poll interval in milliseconds. Optional. The default is 1000.
-f filename | --filename filename
Writes status output to the named file. Optional. The default is to send status information to stdout.
-r | --raw
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.
-a | --all
Outputs all user-defined status values after the standard status messages. Optional. The default is to output only the standard status messages.
-t | --title
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 | --once
Outputs one set of status information and then quits. Optional. The default is to indefinitely return status information at the specified poll interval.
-v | --verbose
Displays process names and versions in addition to status information. Optional. The default is to display only status information.
-V | --version
Displays version information for the engine_watch tool. Optional. The default is that the tool does not output this information.
Standard status messages
The engine_watch tool returns the following standard status messages:
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
The 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. This includes private contexts as well as public contexts.
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 (also called "receivers" here) registered with the correlator. Receivers 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 receivers.
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 receivers. For example, suppose the correlator created 10 output events and sent each event to two receivers. 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.
Events on input context queues
The total number of events on all input context queues. This is the sum of the queue size of main context and any context marked as input by passing true as the second parameter to the context constructor.
Slowest context name
The context which is the slowest - most behind in time or number of events.
Slowest context queue size
The number of events on the slowest context's input queue.
Slowest receiver name
The receiver with the largest number of incoming events waiting to be processed.
Slowest receiver queue size
For the receiver with the largest number of incoming events waiting to be processed, this is the number of events that are waiting.
Types of receivers
The term "receiver" which is used in the above table refers to any of the following:
*EPL, Java or C++ plug-ins using the Correlator.subscribe method.
*Connectivity plug-ins for "towards" transport events.
*JMS or UM connections sending events out of the correlator.
*Client library connections, including other correlators that have been connected with the engine_connect, iaf or engine_receive tools.
Exit status
The engine_watch tool returns the following exit values:
Value
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-2016 Software AG, Darmstadt, Germany.

Product LogoContact Support   |   Community   |   Feedback