Apama Tools Cheatsheet

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:

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.

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.

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.

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.

engine_inject

The engine_inject tool is used to inject event processing language (EPL) files, Apama applications in java (JMon applications), or Java plug-ins into the correlator. While injecting the JMon application or 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 a single JMon application or the Java plug-in.
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:

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.

To specify the port on which the correlator is listening, use the -p or --port option. The default is 15903.

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.

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:

When it successfully injects, you will see the types from the Test.mon file in the correlator logs like this:

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:

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.

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:

 

In the Apama Command Prompt, use the engine_send tool to send these events into the correlator.

When the correlator receives the events, it will trigger the listeners specified in the Test.mon file and print the log messages:

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.

The -r or --reconnect option lets you automatically (re)connect to the server when available.

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.

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.

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:

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.

There are many other tools provided with Apama, for example:

  • engine_delete tool which lets you delete the EPL code and JMon applications from the correlator.
  • engine_watch tool which lets you monitor the runtime operational status of a running correlator.
  • engine_inspect tool 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.

– Shruti Dogra