Apama provides various command line tools that can be used to monitor and manage correlators. In this blog post, we will discuss some of them, focusing on how to use them and for what purposes. The command line tools provide various options which can be viewed by appending --help after the tool name, for example, correlator --help, engine_inject --help etc. We recommend using the Apama Command Prompt available from the Start Menu which ensures that the environment variables are set correctly. On Linux, you can source the shell script from a Bash shell. Use the source bin/apama_env command from within your Apama installation directory.
correlator
To start the correlator, use the correlator tool as shown below:
correlator
There are various options available with this tool. Let’s have a look at some of them.
If you want the correlator to print debug logs, start it with the -v or --loglevel option followed by DEBUG as shown below. The other values that you can specify are OFF, CRIT, FATAL, ERROR, WARN, INFO, DEBUG, TRACE. The default is INFO.
correlator --loglevel DEBUG
To specify a log file of your choice, you can use the -f or --logfile option followed by the file location. The default is stdout.
correlator --logfile LogFile.txt
To specify a different port on which the event correlator should listen for monitoring and management requests, use the -p or --port option. The default port is 15903.
correlator --port 10001
And if you want to enable support for Java applications, which is needed to inject a Java application or plug-in, start the correlator with the -j or --java option. Please note that Apama Core Community Edition does not provide the Oracle JRE and it must be already installed in order to enable support for Java applications. You can download it from here.
correlator --java
engine_inject
The engine_inject tool is used to inject event processing language (EPL) files or Java plug-ins into the correlator. While injecting the Java plug-in you must specify the -j option. Each file you inject with the -j option must be a Java archive file (JAR) that contains an EPL plug-in written in Java.
You can also specify multiple files for injection. The engine_inject tool injects all of them or terminates when it reaches the first file that contains an error. For example:
engine_inject 1.mon 2.mon 3.mon
If the 2.mon file contains an error, engine_inject successfully injects 1.mon and then terminates when it finds the error in 2.mon . In this case the tool does not attempt to inject 3.mon .
The engine_inject tool also provides various options to run the tool with. Let’s have a look at some of them.
If the correlator is running on a different host machine and you want to inject the file into it, then use the -n or --hostname option to specify the hostname. The default is localhost.
engine_inject 1.mon --hostname ABCD.eur.uk
To specify the port on which the correlator is listening, use the -p or --port option. The default is 15903.
engine_inject 1.mon --port 10001
Now let’s inject an EPL file into a correlator using the engine_inject tool. Create an EPL file as shown below and save it as Test.mon .
event MyEvent1 {
string a;
}
event MyEvent2 {
string b;
}
monitor Test {
action onload () {
on all MyEvent1() as evt1 {
log "Received MyEvent1 : " + evt1.a;
}
on all MyEvent2() as evt2 {
log "Received MyEvent2 : " + evt2.b;
}
}
Now start an Apama Command Prompt from the Start Menu and use the correlator tool to start a correlator. Open a new Apama Command Prompt and use the engine_inject tool to inject Test.mon as shown below:
engine_inject Test.mon
When it successfully injects, you will see the types from the Test.mon file in the correlator logs like this:
Added monitor Test
Added type MyEvent1
Added type MyEvent2
Injected MonitorScript from file Test.mon
engine_send
The engine_send tool is used to send Apama-format events into the correlator. You can specify whether to send the events in batches of one or more events or at set time intervals. The correlator reads events from one or more specified files, or you can specify a hyphen (-) or not specify a filename so that the correlator reads events from stdin until it receives an end-of-file signal (CTRL+D on UNIX and CTRL+Z on Windows). This is how you specify an event file:
engine_send Events.evt
Similar to the engine_inject tool options, you can use the -p or --port and -n or --host options to specify the hostname and port of the correlator. To send events multiple times, you can use the -l or the --loop option followed by the number of times to cycle through the file.
engine_send Events.evt --loop 10000
To end an indefinite cycle of sending events, press CTRL+C in the window in which you invoked the engine_send tool. The --loop option can be useful in test as well as production environments. In test environments, you can use the --loop option to simulate heartbeats. If you then kill the engine_send process, you can test your EPL code that detects when heartbeats stop. In production environments, you can use the engine_send tool to initialize a large data table in the correlator.
Now let’s try to send events into the correlator using the engine_send tool. Create two event files as shown below and save them as MyEvent1.evt and MyEvent2.evt :
//MyEvent1.evt
MyEvent1("Hello")
//MyEvent2.evt
MyEvent1("World")
In the Apama Command Prompt, use the engine_send tool to send these events into the correlator.
engine_send MyEvent1.evt MyEvent2.evt
When the correlator receives the events, it will trigger the listeners specified in the Test.mon file and print the log messages:
Received MyEvent1 : Hello
Received MyEvent2 : World
The events were sent successfully!
engine_receive
The engine_receive tool lets you connect to a running correlator and receive events from it. Again the format of these events is Apama-format, so it is possible to reuse the output of the engine_receive tool as input to the engine_send tool. Along with the options for the hostname and port that you are already familiar with, it also has various other options. Let’s have a look at some of them.
To dump all the received events into a file, you can use the -f or --filename option.
engine_receive --filename ReceivedEvents.txt
The -r or --reconnect option lets you automatically (re)connect to the server when available.
engine_receive --reconnect
You can also automatically disconnect from the correlator if the engine_receive tool cannot keep up with the events from the correlator by using the option -x or --qdisconnect .
engine_receive --qdisconnect
You can specify one or more channels on which to listen for events from the correlator using the -c or --channel option. If you want the engine_receive output to include the channel that an event arrives on, use the -C or --logChannels option.
engine_receive -c myChannel -C
Now let’s try to receive events from the correlator using the engine_receive tool. Update Test.mon as shown below so that the correlator sends the EventFromCorrelator event to the channel myChannel :
event MyEvent1 {
string a;
}
event MyEvent2 {
string b;
}
event EventFromCorrelator {
string c;
}
monitor Test {
action onload () {
on all MyEvent1() as evt1 {
log "Received MyEvent1 : " + evt1.a;
}
on all MyEvent2() as evt2 {
log "Received MyEvent2 : " + evt2.b;
}
send EventFromCorrelator("Foo Bar") to "myChannel";
}
}
Stop and re-start the correlator. From a separate Apama Command Prompt window, start the engine_receive tool with the -c myChannel and -C options. From another Apama Command Prompt window, inject Test.mon using the engine_inject tool. You will see the received event along with the channel name in the engine_receive tool window.
"myChannel",EventFromCorrelator("Foo Bar")
There are many other tools provided with Apama, for example:
engine_deletetool which lets you delete the EPL code and EPL plug-in written in Java from the correlator.engine_watchtool which lets you monitor the runtime operational status of a running correlator.engine_inspecttool which lets you inspect the state of a running correlator.
Feel free to take a look at the Apama documentation for more details on the available tools and their options.