From c5a023a20412c76dd265eeaecf0fd4132b426354 Mon Sep 17 00:00:00 2001 From: fibersel <0583463@gmail.com> Date: Thu, 25 Jan 2024 11:11:01 +0100 Subject: [PATCH] Improve documentation for snapshots patch by Abi Palagashvili; reviewed by Stefan Miklosovic and Brandon Williams for CASSANDRA-16887 Co-authored-by: akihiro17 Co-authored-by: Stefan Miklosovic --- .../BASH/nodetool_clearsnapshot_all.sh | 2 +- .../RESULTS/cqlsh_list_snapshots.result | 27 ++++++++ .../nodetool_list_snapshot_empty.result | 3 + .../nodetool_list_snapshots_ephemeral.result | 5 ++ .../RESULTS/nodetool_snapshot_help.result | 3 + ...odetool_snapshot_list_ttl_snapshots.result | 4 ++ .../RESULTS/nodetool_snapshot_take_ttl.result | 3 + .../pages/managing/operating/backups.adoc | 61 ++++++++++++++++++- 8 files changed, 105 insertions(+), 3 deletions(-) create mode 100644 doc/modules/cassandra/examples/RESULTS/cqlsh_list_snapshots.result create mode 100644 doc/modules/cassandra/examples/RESULTS/nodetool_list_snapshot_empty.result create mode 100644 doc/modules/cassandra/examples/RESULTS/nodetool_list_snapshots_ephemeral.result create mode 100644 doc/modules/cassandra/examples/RESULTS/nodetool_snapshot_list_ttl_snapshots.result create mode 100644 doc/modules/cassandra/examples/RESULTS/nodetool_snapshot_take_ttl.result diff --git a/doc/modules/cassandra/examples/BASH/nodetool_clearsnapshot_all.sh b/doc/modules/cassandra/examples/BASH/nodetool_clearsnapshot_all.sh index a22841d744..836cef717b 100644 --- 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 new file mode 100644 index 0000000000..baa5a014f8 --- /dev/null +++ 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 new file mode 100644 index 0000000000..9ec54e9ae9 --- /dev/null +++ b/doc/modules/cassandra/examples/RESULTS/nodetool_list_snapshot_empty.result @@ -0,0 +1,3 @@ +$ nodetool listsnapshots +Snapshot Details: +There are no snapshots \ No newline at end of file diff --git a/doc/modules/cassandra/examples/RESULTS/nodetool_list_snapshots_ephemeral.result b/doc/modules/cassandra/examples/RESULTS/nodetool_list_snapshots_ephemeral.result new file mode 100644 index 0000000000..655a0b3fe0 --- /dev/null +++ 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 \ No newline at end of file diff --git a/doc/modules/cassandra/examples/RESULTS/nodetool_snapshot_help.result b/doc/modules/cassandra/examples/RESULTS/nodetool_snapshot_help.result index a58360872a..0e5b1aa55d 100644 --- 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 The name of the snapshot + --ttl + Specify a TTL of created snapshot + -u , --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 new file mode 100644 index 0000000000..4d6d7b86ea --- /dev/null +++ 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 \ No newline at end of file diff --git a/doc/modules/cassandra/examples/RESULTS/nodetool_snapshot_take_ttl.result b/doc/modules/cassandra/examples/RESULTS/nodetool_snapshot_take_ttl.result new file mode 100644 index 0000000000..730cb4d560 --- /dev/null +++ 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 \ No newline at end of file diff --git a/doc/modules/cassandra/pages/managing/operating/backups.adoc b/doc/modules/cassandra/pages/managing/operating/backups.adoc index d1a45a5d79..1bc949d051 100644 --- 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] ----