Improve documentation for snapshots

patch by Abi Palagashvili; reviewed by Stefan Miklosovic and Brandon Williams for CASSANDRA-16887 Co-authored-by: akihiro17 <akihiro17@users.noreply.github.com> Co-authored-by: Stefan Miklosovic <smiklosovic@apache.org>
apache · Jan 25, 2024 · c5a023a · c5a023a
1 parent f6707e6
commit c5a023a
Show file tree

Hide file tree

Showing 8 changed files with 105 additions and 3 deletions.
diff --git a/doc/modules/cassandra/examples/BASH/nodetool_clearsnapshot_all.sh b/doc/modules/cassandra/examples/BASH/nodetool_clearsnapshot_all.sh
@@ -1 +1 @@
-$ nodetool clearsnapshot -all cqlkeyspace
+$ nodetool clearsnapshot --all cqlkeyspace
diff --git a/doc/modules/cassandra/examples/RESULTS/cqlsh_list_snapshots.result b/doc/modules/cassandra/examples/RESULTS/cqlsh_list_snapshots.result
@@ -0,0 +1,27 @@
+cqlsh> expand on;
+EXPAND set to ON
+cqlsh> select * from system_views.snapshots ;
+
+@ Row 1
+---------------+---------------------------------
+ name          | catalog-cql-ks
+ keyspace_name | catalogkeyspace
+ table_name    | journal
+ created_at    | 2024-01-25 10:06:41.420000+0000
+ ephemeral     | False
+ expires_at    | 2024-01-25 10:09:41.420000+0000
+ size_on_disk  | 6279
+ true_size     | 1143
+
+@ Row 2
+---------------+---------------------------------
+ name          | catalog-cql-ks
+ keyspace_name | catalogkeyspace
+ table_name    | magazine
+ created_at    | 2024-01-25 10:06:41.420000+0000
+ ephemeral     | False
+ expires_at    | 2024-01-25 10:09:41.420000+0000
+ size_on_disk  | 1125
+ true_size     | 1125
+
+(2 rows)
diff --git a/doc/modules/cassandra/examples/RESULTS/nodetool_list_snapshot_empty.result b/doc/modules/cassandra/examples/RESULTS/nodetool_list_snapshot_empty.result
@@ -0,0 +1,3 @@
+$ nodetool listsnapshots
+Snapshot Details:
+There are no snapshots
diff --git a/doc/modules/cassandra/examples/RESULTS/nodetool_list_snapshots_ephemeral.result b/doc/modules/cassandra/examples/RESULTS/nodetool_list_snapshots_ephemeral.result
@@ -0,0 +1,5 @@
+$ nodetool listsnapshots -e
+Snapshot Details:
+Snapshot name  Keyspace name   Column family name True size Size on disk Creation time            Expiration time          Ephemeral
+catalog-cql-ks catalogkeyspace magazine           1.1 KiB   1.1 KiB      2024-01-25T10:01:59.745Z 2024-01-25T10:04:59.745Z false
+catalog-cql-ks catalogkeyspace journal            1.12 KiB  6.13 KiB     2024-01-25T10:01:59.745Z 2024-01-25T10:04:59.745Z false
diff --git a/doc/modules/cassandra/examples/RESULTS/nodetool_snapshot_help.result b/doc/modules/cassandra/examples/RESULTS/nodetool_snapshot_help.result
@@ -42,6 +42,9 @@ OPTIONS
        -t <tag>, --tag <tag>
            The name of the snapshot
 
+       --ttl <ttl>
+           Specify a TTL of created snapshot
+
        -u <username>, --username <username>
            Remote jmx agent username
 

diff --git a/doc/modules/cassandra/examples/RESULTS/nodetool_snapshot_list_ttl_snapshots.result b/doc/modules/cassandra/examples/RESULTS/nodetool_snapshot_list_ttl_snapshots.result
@@ -0,0 +1,4 @@
+$ nodetool listsnapshots
+Snapshot Details:
+Snapshot name   Keyspace name   Column family name True size Size on disk Creation time            Expiration time
+catalog-journal catalogkeyspace journal            1.12 KiB  6.13 KiB     2024-01-25T09:45:31.820Z 2024-01-25T09:48:31.820Z
diff --git a/doc/modules/cassandra/examples/RESULTS/nodetool_snapshot_take_ttl.result b/doc/modules/cassandra/examples/RESULTS/nodetool_snapshot_take_ttl.result
@@ -0,0 +1,3 @@
+$ nodetool snapshot --tag catalog-journal --ttl 3m catalogkeyspace.journal
+Requested creating snapshot(s) for [catalogkeyspace.journal] with snapshot name [catalog-journal] and options {skipFlush=false, ttl=3m}
+Snapshot directory: catalog-journal
diff --git a/doc/modules/cassandra/pages/managing/operating/backups.adoc b/doc/modules/cassandra/pages/managing/operating/backups.adoc
@@ -312,6 +312,63 @@ results in
 include::cassandra:example$RESULTS/nodetool_list_snapshots.result[]
 ----
 
+It is also possible to list all snaphots including so-called _ephemeral_ snapshots. These are
+technical snapshots internal to Cassandra which are normally deleted after a particular operation is done.
+
+If `-e` flag is used when listing snapshots, a new column will be added to the output telling if a snapshot is
+ephemeral or not:
+
+[source, bash]
+----
+include::cassandra:example$RESULTS/nodetool_list_snapshots_ephemeral.result[]
+----
+
+[NOTE]
+====
+You can not manually remove ephemeral snapshots.
+====
+
+It is also possible to list snapshots via `system_views.snapshots` virtual table:
+
+[source, cql]
+----
+include::cassandra:example$RESULTS/cqlsh_list_snapshots.result[]
+----
+
+=== Expiring snapshots
+
+It is possible to set a time-to-live (TTL) for a created snapshot using the `--ttl` option, causing that snapshot
+to be automatically cleaned up when the TTL expires. TTL can be specified in minutes (m), seconds (s), hours (h)
+and days (d). The example below shows the creation of a snapshot for all tables in the `catalogkeyspace`
+and `cqlkeyspace` keyspaces with a TTL of 3 minutes:
+
+[source,bash]
+----
+include::cassandra:example$RESULTS/nodetool_snapshot_take_ttl.result[]
+----
+
+now let's display information about snapshots:
+
+[source,bash]
+----
+include::cassandra:example$RESULTS/nodetool_snapshot_list_ttl_snapshots.result[]
+----
+
+We see creation and expiration time. Let's wait a couple of minutes and try again:
+
+[source,bash]
+----
+include::cassandra:example$RESULTS/nodetool_list_snapshot_empty.result[]
+----
+
+Finally, these snapshots have expired.
+
+[NOTE]
+====
+If you take a snapshot with TTL and stop Cassandra node and you start it again by the
+time that snapshot would be expired, Cassandra will automatically delete it upon its start.
+====
+
 === Finding Snapshots Directories
 
 The `snapshots` directories may be listed with `find –name snapshots`
@@ -363,7 +420,7 @@ include::cassandra:example$RESULTS/snapshot_files.result[]
 === Clearing Snapshots
 
 Snapshots may be cleared or deleted with the `nodetool clearsnapshot`
-command. Either a specific snapshot name must be specified or the `–all`
+command. Either a specific snapshot name must be specified or the `--all`
 option must be specified.
 
 For example, delete a snapshot called `magazine` from keyspace `cqlkeyspace`:
@@ -373,7 +430,7 @@ For example, delete a snapshot called `magazine` from keyspace `cqlkeyspace`:
 include::cassandra:example$BASH/nodetool_clearsnapshot.sh[]
 ----
 
-or delete all snapshots from `cqlkeyspace` with the –all option:
+or delete all snapshots from `cqlkeyspace` with the `--all` option:
 
 [source,bash]
 ----