Inspecting correlator state

The engine_inspect tool lets you inspect the state of a running correlator. This means you can review the applications loaded and running on a correlator. The executable for this tool is located in the Apama/bin directory.

Synopsis

To inspect applications on a running correlator, run the following command:

engine_inspect [ options ]

When you run this command with the –h option, the usage message for this command is shown.

Description

The engine_inspect tool retrieves state information from a running correlator and sends it to stdout. By default, the tool outputs information on the monitors, event types and container types currently injected in a correlator.

You can filter this list by specifying command-line options. When you specify one or more of the -m, -j, -e, -t, -x, -P, or -R options, the engine_inspect tool displays only the information indicated by the option(s) you specify. See the table below for more information on these options.

Options

The engine_inspect tool takes the following options:

Option	Description
`-m \| --monitors`	Displays the names of all EPL monitors in the correlator and the number of monitor instances each monitor has spawned.
`-j \| --java`	Displays the names of all Java plug-in application JARs in the correlator.
`-e \| --events`	Displays the names of all event types in the correlator and the number of templates of each type, as defined in listener specifications. This includes each event template in an `on` statement and each stream source template, for example, `stream<A> := all A()`. For more information about event types and listeners, see Introduction to Apama Event Processing Language.
`-t \| --timers`	Displays the current EPL timers active within the system. The four types of timers which may be displayed here are `wait`, `within`, `at`, and `stream`. The `stream` timers are those set up to support the operation of a stream network.
`-x \| --contexts`	Displays the names of any user-defined contexts, how many monitor instances are running in each context, what channels each context is subscribed to, and how many entries are on each context’s input queue.
`-a \| --aggregates`	Displays a list of the custom (user-defined) aggregate functions that have been injected. You use aggregate functions in stream queries. Apama built-in aggregate functions are not listed.
`-P \| --pluginReceivers`	Displays the names of any plug-in receivers, the channels the plug-in is subscribed to, and the number of items on the plug-in’s input queue. A plug-in receiver is an EPL plug-in that is subscribed to one or more channels.
`-R \| --receivers`	Displays the names of any external receivers, each receiver’s address, the channels each receiver is subscribed to, and the number of entries on each receiver’s output queue.
`-r \| --raw`	Indicates that you want raw output, which is more suitable for machine parsing. Raw output provides the name of each entity in the correlator followed by the number of instances associated with that entity. For a monitor, you get the number of its monitor instances. For an event type, you get the number of its templates. For example: `com.apama.samples.stockwatch.StockWatch 1 Tick 1`
`-h \| --help`	Displays usage information.
`-n host \| --hostname host`	Name of the host on which the correlator is running. The default is `localhost`. Non-ASCII characters are not allowed in host names.
`-p port \| --port port`	Port on which the correlator is listening. The default is `15903`.
`-v \| --verbose`	Displays process names and versions in addition to application information. Optional. The default is to display only application information.
`-V \| --version`	Displays version information for the `engine_inspect` tool.

Exit status

The engine_inspect tool returns the following exit values:

Value	Description
`0`	All status requests were processed successfully.
`1`	No connection to the correlator was possible or the connection failed.
`2`	Other error(s) occurred while requesting/processing status.