Apama Advent Calendar - 05 Dec 2021 - Apama CLI tooling


Today we want to remind everyone about the basic CLI (Command Line Interface) tooling for Apama. Don’t worry if you are not a fan of the command line as we also have a comprehensive IDE in the form of Software AG Designer (based on eclipse), and simple web tooling in Cumulocity IoT, and even a community project providing a VS Code extension.

The full Apama installation ships with many different executables (nearly 30 on Windows), but we’re just going to cover the bare minimum in this intro article.

  • correlator - As mentioned on a previous day, the main event processing engine is called the “correlator”. It’s a native server process that listens on a TCP port and logs to a specified file (or stdout). Customer solutions (applications) can either be provided at startup or dynamically added to a running environment. Deploying as part of the startup configuration is the preferred option for production deployments, but being able to dynamically add and remove EPL files is extremely useful for development and investigations.

Then we have a collection of native client tools that connect to the correlator to perform specific functions. The first four here are kind of the basics and come in pairs inject/delete & send/receive.

  • engine_inject - To inject new EPL code into a correlator.
  • engine_delete - To delete named objects from a correlator.
  • engine_send - To send external events into a correlator.
  • engine_receive - To receive events that are emitted or sent out from a correlator

These next two help you find out more about what a running correlator is doing:

  • engine_watch - To monitor the runtime operational status (metrics) of the correlator
  • engine_inspect - To introspect the correlator and discover more about EPL applications that are injected and the clients that are connected

We also have engine_debug (yes, you guessed correctly it’s a debugger); engine_deploy helps create those production deployment configurations; finally, apama_project is a java tool that can create entire projects that are compatible with the Software AG Designer (and which can be deployed with engine_deploy) - future advent topics!

As described in the official documentation below there are numerous other CLI tools with more advanced specific purposes such as test coverage or documenting APIs, some of which we’ll likely cover in more detail in the coming days.

All of these different client tools have been built against the public APIs of the correlator, and customers are able to use those same APIs to build their own integrations. We’ll talk a little about other forms of integration for receiving and send events in future posts.

Fun fact - did you know that you can also point a web browser directly at a running correlator and see much of the same information? If you have a locally running correlator, on the default port, try pointing your browser to localhost:15903. (Note that the correlator port should not be exposed to untrusted networks.)

Related blog posts, videos, and official documentation:

This is Day #5 (bonus weekend post) of a short series of brief tips, tricks, hints, and reminders of information relating to the Apama Streaming Analytics platform, both from Software AG as well as from the community.
This series of articles will be published Monday-Friday only, with the occasional weekend bonus.