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.