Changes to correlator utilities in 5.2

The engine_connect utility has a new parallel mode (-m parallel or --mode parallel) that uses a connection per channel between correlators and delivers events to the target correlator on the channel the events were sent from in the source correlator. Previous behavior of engine_connect is preserved in legacy mode (-m legacy or --mode legacy), which uses one connection between two correlators and delivers all events to the default channel.

All connections to the correlator are now persistent. Consequently, the engine_connect utility no longer needs to provide the --persistent option and this option has been removed.

The change in behavior of engine_connect switching to persistent connections and other changes in Apama messaging means that two connections for the same component and channel but using different hostnames for the connections (for example, some combination of full hostname, short hostname or IP address, or multiple different addresses or hostnames) will create multiple connections, potentially duplicating events. Apama recommends ensuring all correlators are named consistently. In default (not parallel) mode, multiple connections using the same hostname will be flattened to a single connection, avoiding duplicate events.

There is a change in behavior when disconnecting. Previously, when you specified the -x option without also specifying the -c option the two correlators remained connected even though the source correlator stopped sending events to the target correlator. In this release, specification of the -x option without also specifying the -c option disconnects the two correlators.

When you plan to run this utility you must specify the -g (or --nooptimize) option when you start the correlator. This option disables optimizations that hinder debugging. In previous releases, you could run engine_debug even if -g was not specified when the correlator was started. Apama Studio automatically uses the -g option when it starts a correlator from a debug launch configuration. However, if you connect Apama Studio to an externally started correlator and you want to debug in that correlator then you must ensure that -g was specified when the externally-started correlator was started.

The new -P option displays the name of any plug-in receivers, what channels each plug-in receiver is subscribed to, and the number of entries on the input queue of each plug-in receiver. A plug-in receiver is a correlator plug-in that is subscribed to at least one channel.

The new -R option displays the names of any external receivers, their addresses, what channels each external receiver is subscribed to, and the number of entries in the output queue of each external receiver.

The -x option now also lists the channels each context is subscribed to.

When you specify the -xr or -xs option, you must now specify the component ID as physical_ID/logical_ID.

The new -C or --logChannels option causes the engine_receive utility to include the channel on which an event is received in engine_receive output. If you then use engine_receive output as input to the engine_send utility the events will be delivered back to their channels.

It is now possible to prefix an event with a quoted string that denotes the channel that event is to be sent on. The prefix string follows the same escaping rules as string in events. For example, an entry in a .evt file might be: "MyChannel",Tick("SOW", 35).

The new -c channel option identifies the delivery channel for events for which a delivery channel is not specified.

This utility now provides the following information:

Events on input context queues	The total number of events on the input queues of all public contexts in the correlator.
Most backed up input queue	The input queue that has the most events waiting to be processed.
Most backed up queue size	The number of events on the input queue that has the most events waiting to be processed.
Slowest receiver	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.

When you run this script on a correlator input log you can specify the -c or --correlator option. This option specifies that the script that extract_replay_log generates should include the command line for starting a correlator. When you run the generated script, the correlator will be started with all of the command-line options needed to replay the input log. While this option is not new in this release, it was previously undocumented.