Add documentation for ReplayFilter #20301

akka-docs/rst/scala/persistence.rst

@@ -123,6 +123,8 @@ It contains instructions on how to run the ``PersistentActorExample``.
   Note that when using ``become`` from ``receiveRecover`` it will still only use the ``receiveRecover``
   behavior when replaying the events. When replay is completed it will use the new behavior.
 
+.. _persistence-id-scala:
+
 Identifiers
 -----------
 
@@ -440,6 +442,37 @@ mechanism when ``persist()`` is used. Notice the early stop behaviour that occur
 .. includecode:: code/docs/persistence/PersistenceDocSpec.scala#safe-shutdown-example-bad
 .. includecode:: code/docs/persistence/PersistenceDocSpec.scala#safe-shutdown-example-good
 
+.. _replay-filter-scala:
+
+Replay Filter
+-------------
+There could be cases where event streams are corrupted and multiple writers (i.e. multiple persistent actor instances)
+journaled different messages with the same sequence number.
+In such a case, you can configure how you filter replayed messages from multiple writers, upon recovery.
+
+In your configuration, under the ``akka.persistence.journal.xxx.replay-filter`` section (where ``xxx`` is your journal plugin id),
+you can select the replay filter ``mode`` from one of the following values:
+
+* repair-by-discard-old
+* fail
+* warn
+* off
+
+For example, if you configure the replay filter for leveldb plugin, it looks like this::
+
+      # The replay filter can detect a corrupt event stream by inspecting
+      # sequence numbers and writerUuid when replaying events.
+      akka.persistence.journal.leveldb.replay-filter {
+        # What the filter should do when detecting invalid events.
+        # Supported values:
+        # `repair-by-discard-old` : discard events from old writers,
+        #                           warning is logged
+        # `fail` : fail the replay, error is logged
+        # `warn` : log warning but emit events untouched
+        # `off` : disable this feature completely
+        mode = repair-by-discard-old
+      }
+
 .. _persistent-views:
 
 Persistent Views