Using the Management interface

To use the Management interface, add the Correlator Management EPL bundle to your Apama project (see Adding EPL bundles to projects or Creating and managing an Apama project from the command line). Alternatively, you can directly use the EPL interfaces provided in APAMA_HOME\monitors\Management.mon.

The Management interface provides actions for obtaining information about the correlator that the Management interface is being used in. These actions are defined in the com.apama.correlator.Component event.

There are also options of the engine_management tool that you can specify (see also Shutting down and managing components):

The correlator also logs all of these values to its log file at startup.

The com.apama.correlator.Component event provides actions that allows EPL to create connections to another component, in the same way as the engine_connect tool (see Configuring pipelining with engine_connect).

You can configure logging using the Management interface. The com.apama.correlator.Logging event provides actions such as setApplicationLogFile, setLogFile and setApplicationLogLevel. These actions are the equivalent of using the engine_management options to configure logging (see also Shutting down and managing components).

The rotateLogs() action, which is also defined in the com.apama.correlator.Logging event, is used for closing the log files in use, opening new log files, and then sending messages to the new log files. This action applies to:

For details about log file rotation, see Rotating correlator log files and Rotating all correlator log files.

You can write an EPL monitor that triggers log rotation on a schedule. For example, the code below rotates logs every 24 hours at midnight:

In a persistence-enabled correlator, you can use the Management interface to request a snapshot to occur as soon as possible, and be notified of when that snapshot has been committed to disk. The Management interface lets persistent and non-persistent monitors create instances of Persistence events and then call the persist() action on those events.

When the correlator processes the persist() call it takes and commits a snapshot and executes the specified callback action at some point after the snapshot is committed. There are no guarantees about the elapsed time between the persist() call, the snapshot and the callback, especially when large amounts of correlator state are changing. Your code resumes executing immediately after the call to the persist() action. See Using Correlator Persistence.

The Management interface defines the Persistence event:

Consider the following sample code:

using com.apama.correlator.Persistence;
event Number {
integer i;
}

persistent monitor MyApplication {
integer counter := 0;
sequence<integer> myNumbers;

action onload() {
on all Number(*) as n {
myNumbers.append(n.i);
counter := counter + 1;
if(counter % 10 = 0) {
doCommit();
}
}
}

action doCommit() {
Persistence.persist(logCommit);
}

action logCommit() {
log "Commit succeeded";
}
}

Because MyApplication is a persistent monitor the correlator copies its state to disk as that state changes. This monitor listens for Number events and stores their content in the myNumbers sequence. After every tenth Number event, the code executes the doCommit() action, which uses the Persistence event in the Management interface to request that the correlator commits persistent state to disk. When that commit has succeeded, the Management interface calls the action variable that was passed to the persist() action. This action writes "Commit succeeded" to the correlator log.

The Management interface guarantees that at the moment the callback action (logCommit() in this example) is executed, the state of all persistent monitors at a particular point in time will have been committed. The particular point in time is guaranteed only to be between the point at which persist() was called and the point at which the callback action was executed. For example, suppose the following event stream is being sent into the correlator:

At the point that Number(10) is received, the myNumbers sequence contains the ten items 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 and so the application initiates a snapshot commit. Suppose that the correlator suddenly terminates after notification of success appears in the log. When the correlator recovers, MyApplication has a myNumbers sequence that contains at least ten items. However, the sequence might contain 11 or even 12 items, if more Number events were received after the commit was requested but before the snapshot was actually taken. The correlator also persists state periodically, or as directed by other monitors that call the Management interface, so the sequence can be persisted at other points as well.

The Management interface provides actions for managing (set and return) the user-defined status values. These actions are defined in the com.apama.correlator.Component event and in the com.apama.correlator.EngineStatus event.

Status keys will have leading and trailing whitespace stripped. Keys may not be empty.

A user-defined status will only be changed if the new value differs from the current value when set using setUserStatus.

Note that the correlator status statements that appear in the log files will not have the user-defined status values, and will remain unaffected.

You can monitor the status of each component of your application using Prometheus or REST. For more information, see Monitoring with Prometheus and Managing and Monitoring over REST.