Deploying and Managing Apama Applications > Tuning Correlator Performance > Event correlator pipelining
Event correlator pipelining
To implement engine topologies comprising multiple event correlators requires a method of connecting correlator instances in pipelined configurations. This can be achieved in the following ways:
*Directly using the engine_connect tool, see Configuring pipelining with engine_connect.
*Programmatically via the C++ client API, see Configuring pipelining through the client API.
*Using the Enterprise Monitoring and Management console (EMM). The easiest way to connect components together is to add the components to an EMM configuration and set up connections using the Connections tab; see Connections tab.
Configuring pipelining with engine_connect
The engine_connect tool allows direct connection and disconnection of running correlator instances.
The tool is located in the bin folder of the Apama installation, as engine_connect.exe (on Windows) or engine_connect (on UNIX). Note that before you run it you either need to ensure that the environment variables described in the Installation Guide have been set, or else run it from within the Apama Command Prompt.
Synopsis
Usage: engine_connect [ options ]
To connect a correlator, as an event receiver, to another correlator.
Where options include:
-h | --help This message
-sn | --sourcehost <host> Source engine on <host>
-sp | --sourceport <port> Source engine is listening on <port>
-tn | --targethost <host> Target engine on <host>
-tp | --targetport <port> Target engine is listening on <port>
-c | --channel <channel> Listen on output channel <channel>
-x | --disconnect Destroy rather than create connections
-s | --qdisconnect Disconnect if slow (only takes effect on
first connection)
-f | --filename <file> Read config data from a file
-u | --utf8 Assume config file is in UTF8
-p | --persistent         Receiver will reconnect on being disconnected
-v | --verbose Be more verbose
-V | --version Print program version info
The target is connected as an event consumer to the source
Multiple -c options may be given
To read from stdin use -f -
Description
engine_connect connects a single target correlator (the receiver) to a single source correlator (the sender) on one or more named channels. Source and target correlators must already be running. Alternatively, if the –f option is specified, engine_connect reads connection information from the specified file and sets up each connection found therein (see Configuring pipelining through the client API for details of the file format).
The engine_connect utility expects the specified file to be in the local character set. If the configuration file is in UTF-8, specify the -u option in addition to the -f option.
If the filename provided to -f is ‘-’ then connection information is read from the standard input device (stdin) until end-of-file.
If the –x option is specified, engine_connect will disconnect any existing connection between source and target correlator(s) on the specified channels.
The tool is silent by default unless an error occurs – for verbose progress information use the –v option.
Options
Option
Description
-h
Display usage information
-sn
Name of the host on which the source (event sending) correlator is running. The default is localhost. However, you can use the default or specify localhost only when the source correlator and the target correlator are running on the same host. In all other situations, you must specify the public IP address or the name of the host. This ensures that the host of the target correlator can resolve the name/address of the source correlator host. Non-ASCII characters are not allowed in host names.
-sp
Port on which the source (event sending) correlator is listening (default is 15903)
-tn
Name of the host on which the target (event receiving) correlator is running. The default is localhost. However, you can use the default or specify localhost only when the source correlator and the target correlator are running on the same host. In all other situations, you must specify the public IP address or the name of the host. This ensures that the host of the source correlator can resolve the name/address of the target correlator host. Non-ASCII characters are not allowed in host names.
-tp
Port on which the target (event receiving) correlator is listening (default is 15903)
-c
Named channel to connect/disconnect on – if -c is not specified then: a) if -x is specified the target will receive no events emitted by the source – any existing connection will be removed b) if -x is not specified the target will receive all events emitted by the source, regardless of channel
-x
Disconnect the source/target correlator(s) on the named channels only
-s
Disconnect if slow (only takes effect on first connection)
-f
Read connection information from the named file. If this option is specified, the options –sn –sp –tn –tp -c are all ignored.This file must be in the local character set or in UTF-8 format. If it is UTF-8, specify the -u option in addition to this option.
-u
Indicates that the connection information file is in UTF-8.
-p
Stores details of the connection in the receiving component. If the sender goes down or a network partition occurs, the receiver will attempt to reconnect. If the receiver is a correlator or IAF, the connection will have the same lifetime as the receiving process, so engine_connect should be re-sent when restarting the correlator. Persistent connections are stored in a correlator dump file, so there is no need to re-run engine_connect after engine_load.
-v
Requests verbose output
-V
Displays program name and version number
Operands
None.
Exit status
The following exit values are returned:
Status
Description
0
All connections were established successfully.
1
One or more source correlators could not be contacted
2
One or more target correlators could not be contacted
3
A problem occurred establishing the connection; request invalid
4
Target correlator failed to contact the Source
5
Some other error occurred
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.