Versioning and upgrading monitors
If an application requires functionality to upgrade its monitor instances while still running, there are architectural patterns that must be used during application design. A monitor must contain code that enables its state to be transferred to a new version and for it to terminate upon request. If a deployed monitor does not contain such code, it is not possible to upgrade while transferring its state.
The sample application in the
samples/epl/hot-redeploy/StoreState directory of the Apama installation shows how to transfer monitor state using the MemoryStore (see also
Using the MemoryStore). This sample takes the following steps to upgrade monitor instances:
1. Injects version 1 of the Counter application.
2. Processes version 1 until an upgrade is required.
3. Stops the input events and flushes all queues to ensure that all current events have been processed.
4. Injects version 2 of the Counter application which sends an Upgrade event. This informs the version 1 monitor that an upgrade is happening and it should save its state and its listeners should be destroyed.
5. Once version 1 has finished processing the Upgrade event, the version 2 monitor iterates the MemoryStore table and loads the state of each monitor. The version 2 monitors take over the processing of the input events from version 1.
6. Starts the input events.
7. Processes version 2.
The monitor state that is stored is limited to a small number of required variables contained in a State event that can easily be stored in the MemoryStore. Complex types (such as chunks, listeners or action references) cannot be stored in the MemoryStore and should not be included in a monitor's state. The application monitor supplies a callback to handle the old state, which is typically done by converting the old State object to a new State object. This can be done automatically for fields of the State object that are the same type and name. Added fields or fields whose type is changed, however, need to be handled explicitly by upgrade code. The application monitor can then spawn to handle the upgraded instances. For more information, see the README.txt file and the source code files of the sample application.
This sample is deliberately simple to only show the concept of storing and retrieving a monitor instance state. An application may require more functionality. For example, you can enhance the sample as follows:
Use the distributed MemoryStore to transfer monitor instances between correlators (with the same input).
Spawn to other contexts. This sample only spawns instances to the main context. It could spawn to other contexts, but you need to take care if instances need to be restored to the same context. You would need some form of context store and lookup.
Add a dedicated channel for the
Upgrade events that all monitors in any context could subscribe to.
Modify the sample to work with correlator persistence by marking the monitors as persistent and using
prepareCorrelatorPersistent().
Only kill the monitor factory on
Upgrade events and allow all partially evaluated event expressions to run with the old version, but all new instances will use the new version.
Note:
This sample only transfers global monitor instance state. It does not transfer event expressions; these will be lost. It is possible to allow partially evaluated event expressions to complete (by not explicitly killing or deleting them) but have all new event expressions created by the new version.