Apama 10.15.0 | Developing Apama Applications | Developing Apama Applications in EPL | Using Correlator Persistence | Enabling correlator persistence
 
Enabling correlator persistence
Before you enable persistence, you should design and develop your application to handle persistence and recovery. See Designing applications for persistence-enabled correlators.
Note: 
If a license file cannot be found, the number of persistent monitors that the correlator allows is limited. See Running Apama without a license file.
To enable correlator persistence, you must proceed as follows:
*Insert the word persistent before the monitor declaration for each monitor written in EPL that you want to be persistent. For example:
persistent monitor Order {
action onload() {
...
}
}
For a monitor declared as persistent, the correlator persists the state of all monitor instances of that name, and all instances of events that the monitor instances create.
You do not mark event types as persistent. Whether or not an event is persisted depends on whether it is used from a persistent or non-persistent monitor. If an event is on a context queue when the correlator takes a snapshot, the event is persisted.
*Optionally, define onBeginRecovery() and onConcludeRecovery() actions in your persistent monitors. The correlator executes any such actions as part of the recovery process. To determine whether you need to define these actions, see  Designing applications for persistence-enabled correlators, Defining recovery actions and Sample code for persistence applications.
*Specify one or more persistence options when you start the correlator. To enable correlator persistence, you specify one of the following:
*the -P or -Penabled=true option, or
*the --config option together with the name of a YAML configuration file that contains the following definition:
correlator:
persistence:
enabled: true
Specify just one of the above options (without any additional persistence options) to implement the default behavior for correlator persistence.
To change the default behavior, also specify one or more of the options described in the table below. The correlator uses the default when you do not specify an option that indicates otherwise. For example, if you specify -P, -PsnapshotIntervalMillis and -PstoreLocation (or --config with a YAML configuration file that contains the corresponding options), the correlator uses the values you specify for the snapshot interval and the recovery datastore location and uses the default settings for all other persistence behavior.
For more information on the different -P options and the --config option, see Starting the correlator.
For information on all of the persistence options that you can specify in a YAML configuration file, see Configuring persistence in a YAML configuration file.
Note: 
During development of a persistence application, it varies whether you want to specify a persistence option when you start the correlator. In the earlier stages of development, you might choose not to specify a persistence option since you might make many and frequent changes to early versions of your program, thereby making recovery of a previous version impossible. For example, you might have changed the structure and perhaps added new variables. Once your program structure becomes relatively stable, you must take into account what happens during recovery and you will want to define onBeginRecovery() and onConcludeRecovery() actions. These actions never get called in a correlator that was not started with a persistence option. To deploy a persistence application, the correlator must be started with a persistence option.
*If you are using both correlator persistence and the compiled runtime (--runtime compiled option), we recommend the use of the --runtime-cache option to improve recovery times. For more information on these options, see Starting the correlator.
The following table describes correlator persistence behavior, the default behavior, and the options you can specify to change default behavior.
Correlator Persistence Behavior
Default
Option for Changing
The correlator waits a specified length of time between snapshots.
200 milliseconds
-PsnapshotIntervalMillis=interval
Or the corresponding option in a YAML configuration file:
snapshotIntervalMillis: interval
Specify an integer that indicates the number of milliseconds to wait.
The correlator can automatically adjust the snapshot interval according to application behavior.
It can be useful to set this to false to diagnose a problem or test a new feature.
true. The correlator automatically adjusts the snapshot interval.
-PadjustSnapshot=boolean
Or the corresponding option in a YAML configuration file:
adjustSnapshot: boolean
The correlator puts the recovery datastore in a specified directory.
The directory in which the correlator was started. That is, the current directory.
-PstoreLocation=path
Or the corresponding option in a YAML configuration file:
storeLocation: path
You can specify an absolute or relative path. The directory must exist.
The correlator copies the snapshot into a specified file. This is the recovery datastore.
persistence.db
-PstoreName=filename
Or the corresponding option in a YAML configuration file:
storeName: filename
Specify a filename without a path.
For correlators that use an external clock, the correlator uses a specified time of day as its starting time when it restarts.
This behavior is useful only for replaying input logs that contain recovery information.
The time of day captured in the last committed snapshot.
-XrecoveryTime num
To change the default, specify an integer that indicates seconds since the epoch.
The correlator can automatically copy the recovery datastore to the input log when a persistence-enabled correlator restarts.
The correlator copies the recovery datastore to the input log.
-noDatabaseInReplayLog
Or the corresponding option in a YAML configuration file:
includeDatabaseInInputLog
You might set this option if you are using an input log as a record of what the correlator received. The recovery datastore is a large overhead that you probably do not need. Or, if you maintain an independent copy of the recovery datastore, you probably do not want a copy of it in the input log.
Important: 
If an option is specified both with one of the -P options on the command line and in a YAML configuration file, the value on the command line takes precedence and a warning is logged.