This is an automated email from the ASF dual-hosted git repository.
timoninmaxim pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ignite.git
The following commit(s) were added to refs/heads/master by this push:
new 857fe891c5d IGNITE-18927 Add incremental snapshot docs (#10609)
857fe891c5d is described below
commit 857fe891c5d887820e0076912ce78f84ee8c4733
Author: Maksim Timonin <[email protected]>
AuthorDate: Tue Mar 28 15:55:09 2023 +0300
IGNITE-18927 Add incremental snapshot docs (#10609)
---
.../java/org/apache/ignite/snippets/Snapshots.java | 9 ++-
docs/_docs/monitoring-metrics/system-views.adoc | 3 +
docs/_docs/snapshots/snapshots.adoc | 82 ++++++++++++++++++----
.../snapshot/IgniteSnapshotManager.java | 2 +-
4 files changed, 82 insertions(+), 14 deletions(-)
diff --git
a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/Snapshots.java
b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/Snapshots.java
index 1e3f74fdc2a..0aa2fb44414 100644
---
a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/Snapshots.java
+++
b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/Snapshots.java
@@ -41,8 +41,11 @@ public class Snapshots {
try (IgniteCache<Integer, String> cache =
ignite.getOrCreateCache(ccfg)) {
cache.put(1, "Maxim");
- // Start snapshot operation.
+ // Create snapshot operation.
ignite.snapshot().createSnapshot("snapshot_02092020").get();
+
+ // Create incremental snapshot operation.
+
ignite.snapshot().createIncrementalSnapshot("snapshot_02092020").get();
}
finally {
ignite.destroyCache(ccfg.getName());
@@ -52,6 +55,10 @@ public class Snapshots {
//tag::restore[]
// Restore cache named "snapshot-cache" from the snapshot
"snapshot_02092020".
ignite.snapshot().restoreSnapshot("snapshot_02092020",
Collections.singleton("snapshot-cache")).get();
+
+ // Restore cache named "snapshot-cache" from the snapshot
"snapshot_02092020" and its increment with index 1.
+ ignite.snapshot().restoreSnapshot("snapshot_02092020",
Collections.singleton("snapshot-cache"), 1).get();
+
//end::restore[]
ignite.close();
diff --git a/docs/_docs/monitoring-metrics/system-views.adoc
b/docs/_docs/monitoring-metrics/system-views.adoc
index 55f4dea139e..363f0006d24 100644
--- a/docs/_docs/monitoring-metrics/system-views.adoc
+++ b/docs/_docs/monitoring-metrics/system-views.adoc
@@ -988,4 +988,7 @@ The SNAPSHOT view exposes information about local snapshots.
| CONSISTENT_ID | VARCHAR | Consistent ID of a node to which snapshot data
relates.
| BASELINE_NODES | VARCHAR | Baseline nodes affected by the snapshot.
| CACHE_GROUPS | VARCHAR | Cache group names that were included in the
snapshot.
+| SNAPSHOT_RECORD_SEGMENT | BIGINT | Index of WAL segment containing
snapshot's WAL record.
+| INCREMENT_INDEX | INTEGER | Incremental snapshot index.
+| TYPE | VARCHAR | Type of snapshot - full or incremental.
|===
diff --git a/docs/_docs/snapshots/snapshots.adoc
b/docs/_docs/snapshots/snapshots.adoc
index c1e47857e15..b40b16ce83d 100644
--- a/docs/_docs/snapshots/snapshots.adoc
+++ b/docs/_docs/snapshots/snapshots.adoc
@@ -16,7 +16,7 @@
== Overview
-Ignite provides an ability to create full cluster snapshots for deployments
using
+Ignite provides an ability to create full and incremental cluster snapshots
for deployments using
link:persistence/native-persistence[Ignite Persistence]. An Ignite snapshot
includes a consistent cluster-wide copy of
all data records persisted on disk and some other files needed for a restore
procedure.
@@ -28,15 +28,15 @@ with several exceptions. Let's take this snapshot as an
example to review the st
work
└── snapshots
└── backup23012020
+ ├── increments
+ │ └── 0000000000000001
└── db
├── binary_meta
│ ├── node1
│ ├── node2
│ └── node3
├── marshaller
- │ ├── node1
- │ ├── node2
- │ └── node3
+ │ └── classname0
├── node1
│ └── my-sample-cache
│ ├── cache_data.dat
@@ -62,8 +62,10 @@ the nodes are named as `node1`, `node2`, and `node3`, while
in practice, the nam
link:https://cwiki.apache.org/confluence/display/IGNITE/Ignite+Persistent+Store+-+under+the+hood#IgnitePersistentStoreunderthehood-SubfoldersGeneration[consistent
IDs].
* The snapshot keeps a copy of the `my-sample-cache` cache.
* The `db` folder keeps a copy of data records in `part-N.bin` and
`cache_data.dat` files. Write-ahead and checkpointing
-are not added into the snapshot as long as those are not required for the
current restore procedure.
+are not added into the snapshot as long as those are not required for the full
snapshot restore procedure.
* The `binary_meta` and `marshaller` directories store metadata and
marshaller-specific information.
+* The `increments` directory stores incremental snapshots based on the full
snapshot `backup23012020`, in this example
+there is a single increment `0000000000000001`. It contains `wal` directory
that stores the compressed WAL segments, `binary_meta` and `marshaller`
directories.
[NOTE]
====
@@ -76,6 +78,31 @@ snapshot data spread across the cluster. Each node keeps a
segment of the snapsh
The link:snapshots/snapshots#restoring-from-snapshot[restore procedure]
explains how to tether together all the segments during recovery.
====
+== Incremental snapshots
+
+The low RPO (Recovery Point Object), e.g. a few minutes, can hardly be
achieved using full snapshots. They require additional resources
+to create and store all partitions data. Instead, you can use incremental
snapshots:
+
+1. to store the data changes happened since previous full or incremental
snapshot was created
+2. to provide a lightweight creation process and can be run concurrently with
runtime load.
+
+[NOTE]
+====
+
+Incremental snapshots consist of compressed WAL segments, which are collected
in the background without pressure on cluster resources.
+====
+
+There are some prerequisites for using incremental snapshots:
+
+* Incremental snapshots are based on existing full snapshot.
+* link:persistence/native-persistence#wal-archive-compaction[WAL archive
compaction] has to be enabled.
+* Incremental snapshots has to be created on the same media drive where WAL
archives are stored.
+
+During incremental snapshot restore procedure the full snapshot is restored
first and after that all increments are restored sequentially.
+
+Please refer to the sections
link:snapshots/snapshots#consistency-guarantees[Consistency Guarantees] and
+link:snapshots/snapshots#current-limitations[Current Limitations] below for
more details about incremental snapshots.
+
== Configuration
=== Snapshot Directory
@@ -133,7 +160,10 @@ control.(sh|bat) --snapshot create snapshot_09062021
control.(sh|bat) --snapshot create snapshot_09062021 --sync
# Create a cluster snapshot named "snapshot_09062021" in the
"/tmp/ignite/snapshots" folder (the full path to the snapshot files will be
/tmp/ignite/snapshots/snapshot_09062021):
-control.(sh|bat) --snapshot create snapshot_09062021 -dest
/tmp/ignite/snapshots
+control.(sh|bat) --snapshot create snapshot_09062021 --dest
/tmp/ignite/snapshots
+
+# Create an incremental snapshot based on full snapshot "snapshot_09062021":
+control.(sh|bat) --snapshot create snapshot_09062021 --incremental
----
=== Using JMX
@@ -143,7 +173,8 @@ Use the `SnapshotMXBean` interface to perform the
snapshot-specific procedures v
[cols="1,1",opts="header"]
|===
|Method | Description
-|createSnapshot(String snpName) | Create a snapshot.
+|createSnapshot(String snpName, String snpPath) | Create a snapshot.
+|createIncrementalSnapshot(String snpName, String snpPath) | Create an
incremental snapshot.
|===
=== Using Java API
@@ -181,12 +212,12 @@ Both procedures are described below, however, it is
preferable to use the restor
=== Manual Snapshot Restore Procedure
-The snapshot structure is similar to the layout of the Ignite Native
Persistence, so for the manual snapshot restore you must
-do a snapshot restore only on the same cluster with the same node
`consistentId` and on the same topology on which a snapshot
-was taken. If you need to restore a snapshot on a different cluster or on a
different cluster topology use the
-link:snapshots/snapshots#automatic-snapshot-restore-procedure[Automatic
Snapshot Restore Procedure].
+The snapshot structure is similar to the layout of the Ignite Native
Persistence. Therefore, to restore the manual snapshot, you must
+restore a snapshot only on the same cluster with the same node `consistentId`
and on the same topology on which a snapshot
+was taken. Only the full snapshot can be restored. If you need to restore a
snapshot on a different cluster, or on a different
+cluster topology, or restore incremental snapshots use the
link:snapshots/snapshots#automatic-snapshot-restore-procedure[Automatic
Snapshot Restore Procedure].
-In general, stop the cluster, then replace persistence data and other files
with the data from the snapshot, and restart the nodes.
+In general, stop the cluster, then replace the persistence data and other
files using the data from the snapshot, and restart the nodes.
The detailed procedure looks as follows:
@@ -228,6 +259,10 @@ tab:CLI[]
----
# Restore cache group "snapshot-cache" from the snapshot "snapshot_02092020".
control.(sh|bat) --snapshot restore snapshot_02092020 --groups snapshot-cache
+
+# Restore cache group "snapshot-cache" from the snapshot "snapshot_02092020"
and its increment with index 1.
+control.(sh|bat) --snapshot restore snapshot_02092020 --groups snapshot-cache
--increment 1
+
----
--
@@ -247,6 +282,9 @@ control.(sh|bat) --snapshot restore snapshot_09062021 --src
/tmp/ignite/snapshot
# Start restoring only "cache-group1" and "cache-group2" from the snapshot
"snapshot_09062021" in the background.
control.(sh|bat) --snapshot restore snapshot_09062021 --groups
cache-group1,cache-group2
+
+# Start restoring all user-created cache groups from the snapshot
"snapshot_09062021" and its increment with index 1.
+control.(sh|bat) --snapshot restore snapshot_09062021 --increment 1
----
== Getting Snapshot Operation Status
@@ -332,6 +370,14 @@ The consistency between the Ignite Persistence files and
their snapshot copies i
files to the destination snapshot directory with tracking all concurrent
ongoing changes. The tracking of the changes
might require extra space on the Ignite Persistence storage media (up to the
1x size of the storage media).
+=== Incremental snapshot consistency guarantees
+
+Incremental snapshots uses different non-blocking approach for achieving
transactional consistency based on the Consistent Cut algorithm.
+This allows you to start incremental snapshots concurrently with the runtime
load without affecting performance. But it doesn't guarantee consistency
+for atomic caches. It's highly recommended to verify these caches after
restoring with the `idle_verify`
+command. If necessary, it's possible to repair inconsistent partitions with
the `consistency` command. Please, check the
+link:tools/control-script[Control Script] section for more information about
these commands.
+
== Current Limitations
The snapshot procedure has some limitations that you should be aware of before
using the feature in your production environment:
@@ -347,3 +393,15 @@ The snapshot procedure has some limitations that you
should be aware of before u
If any of these limitations prevent you from using Apache Ignite, then select
alternate snapshotting implementations for
Ignite provided by enterprise vendors.
+
+=== Incremental snapshot limitations
+
+Incremental snapshots can't be created in the following cases:
+
+* Encrypted caches are presented in a cluster.
+* Caches are created, changed or destroyed after full snapshot was created.
+* After link:data-rebalancing[data has been rebalanced] in the cluster.
+
+Ignite automatically monitors these events and prevents the incremental
snapshot creation. It's required to create a new
+full snapshot and after that creation of incremental snapshots becomes
available again.
+
diff --git
a/modules/core/src/main/java/org/apache/ignite/internal/processors/cache/persistence/snapshot/IgniteSnapshotManager.java
b/modules/core/src/main/java/org/apache/ignite/internal/processors/cache/persistence/snapshot/IgniteSnapshotManager.java
index 926ac272e14..9cf0cab4a49 100644
---
a/modules/core/src/main/java/org/apache/ignite/internal/processors/cache/persistence/snapshot/IgniteSnapshotManager.java
+++
b/modules/core/src/main/java/org/apache/ignite/internal/processors/cache/persistence/snapshot/IgniteSnapshotManager.java
@@ -253,7 +253,7 @@ import static
org.apache.ignite.spi.systemview.view.SnapshotView.SNAPSHOT_SYS_VI
* These major actions available:
* <ul>
* <li>Create snapshot of the whole cluster cache groups by triggering PME
to achieve consistency.</li>
- * <li>Create incremental snapshot of transactional cache groups by using
Consistent Cut algorithm.</li>
+ * <li>Create incremental snapshot using lightweight, non-blocking
Consistent Cut algorithm.</li>
* </ul>
*/
public class IgniteSnapshotManager extends GridCacheSharedManagerAdapter
