Make RetentionCritera evolvable, #26545
* allow combining snapshotWhen and RetentionCriteria * RetentionCritieria unit test * move retention and snapshot tests to separate EventSourcedBehaviorRetentionSpec * because EventSourcedBehaviorSpec is testing too many different things * Update Scaldoc and reference documentation * moved it to the snapshotting page
This commit is contained in:
Patrik Nordwall
parent
a2f65de599
commit
81f11c97dd
19 changed files with 1028 additions and 473 deletions
|
|
@ -7,7 +7,7 @@ prone to accumulating extremely long event logs and experiencing long recovery t
|
|||
may be to split out into a set of shorter lived actors. However, when this is not an option, you can use snapshots
|
||||
to reduce recovery times drastically.
|
||||
|
||||
Persistent actors can save snapshots of internal state every N events or when a given predicated of the state
|
||||
Persistent actors can save snapshots of internal state every N events or when a given predicate of the state
|
||||
is fulfilled.
|
||||
|
||||
Scala
|
||||
|
|
@ -46,7 +46,9 @@ events. This can be useful if snapshot serialization format has changed in an in
|
|||
not be used when events have been deleted.
|
||||
|
||||
In order to use snapshots, a default snapshot-store (`akka.persistence.snapshot-store.plugin`) must be configured,
|
||||
or the @scala[`PersistentActor`]@java[persistent actor] can pick a snapshot store explicitly by overriding @scala[`def snapshotPluginId: String`]@java[`String snapshotPluginId()`].
|
||||
or you can pick a snapshot store for for a specific `EventSourcedBehavior by
|
||||
@scala[defining it with `withSnapshotPluginId` of the `EventSourcedBehavior`]@java[overriding `snapshotPluginId` in
|
||||
the `EventSourcedBehavior`].
|
||||
|
||||
Because some use cases may not benefit from or need snapshots, it is perfectly valid not to not configure a snapshot store.
|
||||
However, Akka will log a warning message when this situation is detected and then continue to operate until
|
||||
|
|
@ -55,10 +57,71 @@ an actor tries to store a snapshot, at which point the operation will fail.
|
|||
## Snapshot failures
|
||||
|
||||
Saving snapshots can either succeed or fail – this information is reported back to the persistent actor via
|
||||
the `onSnapshot` callback. Snapshot failures are, by default, logged but do not cause the actor to stop or
|
||||
restart.
|
||||
the `SnapshotCompleted` or `SnapshotFailed` signal. Snapshot failures are logged by default but do not cause
|
||||
the actor to stop or restart.
|
||||
|
||||
If there is a problem with recovering the state of the actor from the journal when the actor is
|
||||
started, `onRecoveryFailure` is called (logging the error by default), and the actor will be stopped.
|
||||
started, `RecoveryFailed` signal is emitted (logging the error by default), and the actor will be stopped.
|
||||
Note that failure to load snapshot is also treated like this, but you can disable loading of snapshots
|
||||
if you for example know that serialization format has changed in an incompatible way.
|
||||
|
||||
## Snapshot deletion
|
||||
|
||||
To free up space, an event sourced actor can automatically delete older snapshots based on the given `RetentionCriteria`.
|
||||
|
||||
Scala
|
||||
: @@snip [BasicPersistentBehaviorCompileOnly.scala](/akka-persistence-typed/src/test/scala/docs/akka/persistence/typed/BasicPersistentBehaviorCompileOnly.scala) { #retentionCriteria }
|
||||
|
||||
Java
|
||||
: @@snip [BasicPersistentBehaviorTest.java](/akka-persistence-typed/src/test/java/jdocs/akka/persistence/typed/BasicPersistentBehaviorTest.java) { #retentionCriteria #snapshottingPredicate }
|
||||
|
||||
Snapshot deletion is triggered after saving a new snapshot.
|
||||
|
||||
The above example will save snapshots automatically every `numberOfEvents = 100`. Snapshots that have sequence
|
||||
number less than the sequence number of the saved snapshot minus `keepNSnapshots * numberOfEvents` (`100 * 2`) are automatically
|
||||
deleted.
|
||||
|
||||
In addition, it will also save a snapshot when the persisted event is `BookingCompleted`. Automatic snapshotting
|
||||
based on `numberOfEvents` can be used without specifying @scala[`snapshotWhen`]@java[`shouldSnapshot`]. Snapshots
|
||||
triggered by the @scala[`snapshotWhen`]@java[`shouldSnapshot`] predicate will not trigger deletion of old snapshots.
|
||||
|
||||
On async deletion, either a `DeleteSnapshotsCompleted` or `DeleteSnapshotsFailed` signal is emitted.
|
||||
You can react to signal outcomes by using @scala[with `receiveSignal` handler] @java[by overriding `receiveSignal`].
|
||||
By default, successful completion is logged by the system at log level `debug`, failures at log level `warning`.
|
||||
|
||||
Scala
|
||||
: @@snip [BasicPersistentBehaviorCompileOnly.scala](/akka-persistence-typed/src/test/scala/docs/akka/persistence/typed/BasicPersistentBehaviorCompileOnly.scala) { #retentionCriteriaWithSignals }
|
||||
|
||||
Java
|
||||
: @@snip [BasicPersistentBehaviorTest.java](/akka-persistence-typed/src/test/java/jdocs/akka/persistence/typed/BasicPersistentBehaviorTest.java) { #retentionCriteriaWithSignals }
|
||||
|
||||
## Event deletion
|
||||
|
||||
Deleting events in event sourcing based applications is typically either not used at all, or used in conjunction with snapshotting.
|
||||
By deleting events you will lose the history of how the system changed before it reached current state, which is
|
||||
one of the main reasons for using event sourcing in the first place.
|
||||
|
||||
If snapshot-based retention is enabled, after a snapshot has been successfully stored, a delete of the events
|
||||
(journaled by a single event sourced actor) up until the sequence number of the data held by that snapshot can be issued.
|
||||
|
||||
To elect to use this, enable `withDeleteEventsOnSnapshot` of the `RetentionCriteria` which is disabled by default.
|
||||
|
||||
Scala
|
||||
: @@snip [BasicPersistentBehaviorCompileOnly.scala](/akka-persistence-typed/src/test/scala/docs/akka/persistence/typed/BasicPersistentBehaviorCompileOnly.scala) { #snapshotAndEventDeletes }
|
||||
|
||||
Java
|
||||
: @@snip [BasicPersistentBehaviorTest.java](/akka-persistence-typed/src/test/java/jdocs/akka/persistence/typed/BasicPersistentBehaviorTest.java) { #snapshotAndEventDeletes }
|
||||
|
||||
Event deletion is triggered after saving a new snapshot. Old events would be deleted prior to old snapshots being deleted.
|
||||
|
||||
On async deletion, either a `DeleteEventsCompleted` or `DeleteEventsFailed` signal is emitted.
|
||||
You can react to signal outcomes by using @scala[with `receiveSignal` handler] @java[by overriding `receiveSignal`].
|
||||
By default, successful completion is logged by the system at log level `debug`, failures at log level `warning`.
|
||||
|
||||
Message deletion does not affect the highest sequence number of the journal, even if all messages were deleted from it after a delete occurs.
|
||||
|
||||
@@@ note
|
||||
|
||||
It is up to the journal implementation whether events are actually removed from storage.
|
||||
|
||||
@@@
|
||||
|
|
|
|||
|
|
@ -453,54 +453,3 @@ processed.
|
|||
|
||||
It's allowed to stash messages while unstashing. Those newly added commands will not be processed by the
|
||||
`unstashAll` effect that was in progress and have to be unstashed by another `unstashAll`.
|
||||
|
||||
## Retention - snapshots and events
|
||||
|
||||
Retention of snapshots and events are controlled by a few factors. Deletes to free up space is currently available.
|
||||
|
||||
### Snapshot deletion
|
||||
|
||||
To free up space, an event sourced actor can automatically delete older snapshots
|
||||
based on a user provided or default `RetentionCriteria` @scala[from `withRetention`] @java[by overriding `retentionCriteria`]
|
||||
combined with the `snapshotWhen` method.
|
||||
|
||||
Scala
|
||||
: @@snip [BasicPersistentBehaviorCompileOnly.scala](/akka-persistence-typed/src/test/scala/docs/akka/persistence/typed/BasicPersistentBehaviorCompileOnly.scala) { #retentionCriteria }
|
||||
|
||||
Java
|
||||
: @@snip [BasicPersistentBehaviorTest.java](/akka-persistence-typed/src/test/java/jdocs/akka/persistence/typed/BasicPersistentBehaviorTest.java) { #retentionCriteria }
|
||||
|
||||
On async deletion, either a `SnapshotCompleted` or `SnapshotFailed` is emitted. Successful completion is logged by the system at log level `debug`, failures at log level `warning`.
|
||||
You can leverage `EventSourcedSignal` to react to outcomes @scala[with `receiveSignal` handler] @java[by overriding `receiveSignal`].
|
||||
|
||||
Scala
|
||||
: @@snip [BasicPersistentBehaviorCompileOnly.scala](/akka-persistence-typed/src/test/scala/docs/akka/persistence/typed/BasicPersistentBehaviorCompileOnly.scala) { #retentionCriteriaWithSignals }
|
||||
|
||||
Java
|
||||
: @@snip [BasicPersistentBehaviorTest.java](/akka-persistence-typed/src/test/java/jdocs/akka/persistence/typed/BasicPersistentBehaviorTest.java) { #retentionCriteriaWithSignals }
|
||||
|
||||
## Event deletion
|
||||
|
||||
Deleting events in event sourcing based applications is typically either not used at all, or used in conjunction with snapshotting.
|
||||
If snapshot-based recovery is enabled, after a snapshot has been successfully stored, a delete (journaled by a single event sourced actor) up until the sequence number of the data held by that snapshot can be issued.
|
||||
|
||||
To elect to use this, enable `RetentionCriteria.deleteEventsOnSnapshot` which is disabled by default.
|
||||
You can leverage `EventSourcedSignal` to react to outcomes @scala[with `receiveSignal` handler] @java[by overriding `receiveSignal`].
|
||||
|
||||
Scala
|
||||
: @@snip [BasicPersistentBehaviorCompileOnly.scala](/akka-persistence-typed/src/test/scala/docs/akka/persistence/typed/BasicPersistentBehaviorCompileOnly.scala) { #snapshotAndEventDeletes }
|
||||
|
||||
Java
|
||||
: @@snip [BasicPersistentBehaviorTest.java](/akka-persistence-typed/src/test/java/jdocs/akka/persistence/typed/BasicPersistentBehaviorTest.java) { #retentionCriteria }
|
||||
|
||||
On `SaveSnapshotSuccess`, old events would be deleted based on `RetentionCriteria` prior to old snapshots being deleted. On async deletion, either `DeleteEventsCompleted` or `DeleteEventsFailed` is emitted. Successful completion is logged by the
|
||||
system at log level `debug`, failures at log level `warning`.
|
||||
|
||||
Message deletion does not affect the highest sequence number of the journal, even if all messages were deleted from it after a delete occurs.
|
||||
|
||||
@@@ note
|
||||
|
||||
It is up to the journal implementation whether events are actually removed from storage.
|
||||
Deleting events prevents future replaying of old events to apply new state.
|
||||
|
||||
@@@ note
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue