Add TXG timestamp database

cmd/zpool/zpool_main.c

@@ -513,8 +513,8 @@ get_usage(zpool_help_t idx)
 		return (gettext("\tinitialize [-c | -s | -u] [-w] <-a | <pool> "
 		    "[<device> ...]>\n"));
 	case HELP_SCRUB:
-		return (gettext("\tscrub [-e | -s | -p | -C] [-w] <-a | "
-		    "<pool> [<pool> ...]>\n"));
+		return (gettext("\tscrub [-e | -s | -p | -C | -E | -S] [-w] "
+		    "<-a | <pool> [<pool> ...]>\n"));
 	case HELP_RESILVER:
 		return (gettext("\tresilver <pool> ...\n"));
 	case HELP_TRIM:
@@ -8359,6 +8359,8 @@ zpool_do_reopen(int argc, char **argv)
 typedef struct scrub_cbdata {
 	int	cb_type;
 	pool_scrub_cmd_t cb_scrub_cmd;
+	time_t	cb_date_start;
+	time_t	cb_date_end;
 } scrub_cbdata_t;
 
 static boolean_t
@@ -8402,8 +8404,8 @@ scrub_callback(zpool_handle_t *zhp, void *data)
 		return (1);
 	}
 
-	err = zpool_scan(zhp, cb->cb_type, cb->cb_scrub_cmd);
-
+	err = zpool_scan_range(zhp, cb->cb_type, cb->cb_scrub_cmd,
+	    cb->cb_date_start, cb->cb_date_end);
 	if (err == 0 && zpool_has_checkpoint(zhp) &&
 	    cb->cb_type == POOL_SCAN_SCRUB) {
 		(void) printf(gettext("warning: will not scrub state that "
@@ -8421,10 +8423,34 @@ wait_callback(zpool_handle_t *zhp, void *data)
 	return (zpool_wait(zhp, *act));
 }
 
+static time_t
+date_string_to_sec(const char *timestr, boolean_t rounding)
+{
+	struct tm tm = {0};
+	int adjustment = rounding ? 1 : 0;
+
+	/* Allow mktime to determine timezone. */
+	tm.tm_isdst = -1;
+
+	if (strptime(timestr, "%Y-%m-%d %H:%M", &tm) == NULL) {
+		if (strptime(timestr, "%Y-%m-%d", &tm) == NULL) {
+			fprintf(stderr, gettext("Failed to parse the date.\n"));
+			usage(B_FALSE);
+		}
+		adjustment *= 24 * 60 * 60;
+	} else {
+		adjustment *= 60;
+	}
+
+	return (mktime(&tm) + adjustment);
+}
+
 /*
- * zpool scrub [-e | -s | -p | -C] [-w] <pool> ...
+ * zpool scrub [-e | -s | -p | -C | -E | -S] [-w] <pool> ...
  *
  *	-e	Only scrub blocks in the error log.
+ *	-E	End date of scrub.
+ *	-S	Start date of scrub.
  *	-s	Stop.  Stops any in-progress scrub.
  *	-p	Pause. Pause in-progress scrub.
  *	-w	Wait.  Blocks until scrub has completed.
@@ -8440,6 +8466,7 @@ zpool_do_scrub(int argc, char **argv)
 
 	cb.cb_type = POOL_SCAN_SCRUB;
 	cb.cb_scrub_cmd = POOL_SCRUB_NORMAL;
+	cb.cb_date_start = cb.cb_date_end = 0;
 
 	boolean_t is_error_scrub = B_FALSE;
 	boolean_t is_pause = B_FALSE;
@@ -8448,17 +8475,27 @@ zpool_do_scrub(int argc, char **argv)
 	boolean_t scrub_all = B_FALSE;
 
 	/* check options */
-	while ((c = getopt(argc, argv, "aspweC")) != -1) {
+	while ((c = getopt(argc, argv, "aspweCE:S:")) != -1) {
 		switch (c) {
 		case 'a':
 			scrub_all = B_TRUE;
 			break;
 		case 'e':
 			is_error_scrub = B_TRUE;
 			break;
+		case 'E':
+			/*
+			 * Round the date. It's better to scrub more data than
+			 * less. This also makes the date inclusive.
+			 */
+			cb.cb_date_end = date_string_to_sec(optarg, B_TRUE);
+			break;
 		case 's':
 			is_stop = B_TRUE;
 			break;
+		case 'S':
+			cb.cb_date_start = date_string_to_sec(optarg, B_FALSE);
+			break;
 		case 'p':
 			is_pause = B_TRUE;
 			break;
@@ -8506,6 +8543,19 @@ zpool_do_scrub(int argc, char **argv)
 		}
 	}
 
+	if ((cb.cb_date_start != 0 || cb.cb_date_end != 0) &&
+	    cb.cb_scrub_cmd != POOL_SCRUB_NORMAL) {
+		(void) fprintf(stderr, gettext("invalid option combination: "
+		    "start/end date is available only with normal scrub\n"));
+		usage(B_FALSE);
+	}
+	if (cb.cb_date_start != 0 && cb.cb_date_end != 0 &&
+	    cb.cb_date_start > cb.cb_date_end) {
+		(void) fprintf(stderr, gettext("invalid arguments: "
+		    "end date has to be later than start date\n"));
+		usage(B_FALSE);
+	}
+
 	if (wait && (cb.cb_type == POOL_SCAN_NONE ||
 	    cb.cb_scrub_cmd == POOL_SCRUB_PAUSE)) {
 		(void) fprintf(stderr, gettext("invalid option combination: "
@@ -8546,6 +8596,7 @@ zpool_do_resilver(int argc, char **argv)
 
 	cb.cb_type = POOL_SCAN_RESILVER;
 	cb.cb_scrub_cmd = POOL_SCRUB_NORMAL;
+	cb.cb_date_start = cb.cb_date_end = 0;
 
 	/* check options */
 	while ((c = getopt(argc, argv, "")) != -1) {

include/Makefile.am

@@ -10,6 +10,7 @@ COMMON_H = \
 	cityhash.h \
 	zfeature_common.h \
 	zfs_comutil.h \
+	zfs_crrd.h \
 	zfs_deleg.h \
 	zfs_fletcher.h \
 	zfs_namecheck.h \

include/libzfs.h

@@ -302,6 +302,8 @@ typedef struct initialize_cbdata {
  * Functions to manipulate pool and vdev state
  */
 _LIBZFS_H int zpool_scan(zpool_handle_t *, pool_scan_func_t, pool_scrub_cmd_t);
+_LIBZFS_H int zpool_scan_range(zpool_handle_t *, pool_scan_func_t,
+    pool_scrub_cmd_t, time_t, time_t);
 _LIBZFS_H int zpool_initialize_one(zpool_handle_t *, void *);
 _LIBZFS_H int zpool_initialize(zpool_handle_t *, pool_initialize_func_t,
     nvlist_t *);

include/sys/dmu.h

@@ -414,6 +414,9 @@ typedef struct dmu_buf {
 #define	DMU_POOL_ZPOOL_CHECKPOINT	"com.delphix:zpool_checkpoint"
 #define	DMU_POOL_LOG_SPACEMAP_ZAP	"com.delphix:log_spacemap_zap"
 #define	DMU_POOL_DELETED_CLONES		"com.delphix:deleted_clones"
+#define	DMU_POOL_TXG_LOG_TIME_MINUTES	"com.klaraystems:txg_log_time:minutes"
+#define	DMU_POOL_TXG_LOG_TIME_DAYS	"com.klaraystems:txg_log_time:days"
+#define	DMU_POOL_TXG_LOG_TIME_MONTHS	"com.klaraystems:txg_log_time:months"
 
 /*
  * Allocate an object from this objset.  The range of object numbers

include/sys/spa_impl.h

@@ -55,6 +55,8 @@
 #include <sys/dsl_deadlist.h>
 #include <zfeature_common.h>
 
+#include "zfs_crrd.h"
+
 #ifdef	__cplusplus
 extern "C" {
 #endif
@@ -344,6 +346,12 @@ struct spa {
 	spa_checkpoint_info_t spa_checkpoint_info; /* checkpoint accounting */
 	zthr_t		*spa_checkpoint_discard_zthr;
 
+	kmutex_t	spa_txg_log_time_lock;	/* for spa_txg_log_time */
+	dbrrd_t		spa_txg_log_time;
+	uint64_t	spa_last_noted_txg;
+	uint64_t	spa_last_noted_txg_time;
+	uint64_t	spa_last_flush_txg_time;
+
 	space_map_t	*spa_syncing_log_sm;	/* current log space map */
 	avl_tree_t	spa_sm_logs_by_txg;
 	kmutex_t	spa_flushed_ms_lock;	/* for metaslabs_by_flushed */

include/zfs_crrd.h

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: CDDL-1.0
+/*
+ * CDDL HEADER START
+ *
+ * The contents of this file are subject to the terms of the
+ * Common Development and Distribution License (the "License").
+ * You may not use this file except in compliance with the License.
+ *
+ * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
+ * or https://opensource.org/licenses/CDDL-1.0.
+ * See the License for the specific language governing permissions
+ * and limitations under the License.
+ *
+ * When distributing Covered Code, include this CDDL HEADER in each
+ * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
+ * If applicable, add the following below this CDDL HEADER, with the
+ * fields enclosed by brackets "[]" replaced with your own identifying
+ * information: Portions Copyright [yyyy] [name of copyright owner]
+ *
+ * CDDL HEADER END
+ */
+/*
+ * Copyright (c) 2024 Klara Inc.
+ *
+ * This software was developed by
+ * Mariusz Zaborski <mariusz.zaborski@klarasystems.com>
+ * Fred Weigel <fred.weigel@klarasystems.com>
+ * under sponsorship from Wasabi Technology, Inc. and Klara Inc.
+ */
+
+#ifndef _CRRD_H_
+#define	_CRRD_H_
+
+#define	RRD_MAX_ENTRIES	256
+
+#define	RRD_ENTRY_SIZE	sizeof (uint64_t)
+#define	RRD_STRUCT_ELEM	(sizeof (rrd_t) / RRD_ENTRY_SIZE)
+
+typedef enum {
+	DBRRD_FLOOR,
+	DBRRD_CEILING
+} dbrrd_rounding_t;
+
+typedef struct {
+	uint64_t	rrdd_time;
+	uint64_t	rrdd_txg;
+} rrd_data_t;
+
+typedef struct {
+	uint64_t	rrd_head;	/* head (beginning) */
+	uint64_t	rrd_tail;	/* tail (end) */
+	uint64_t	rrd_length;
+
+	rrd_data_t	rrd_entries[RRD_MAX_ENTRIES];
+} rrd_t;
+
+typedef struct {
+	rrd_t		dbr_minutes;
+	rrd_t		dbr_days;
+	rrd_t		dbr_months;
+} dbrrd_t;
+
+size_t rrd_len(rrd_t *rrd);
+
+const rrd_data_t *rrd_entry(rrd_t *r, size_t i);
+rrd_data_t *rrd_tail_entry(rrd_t *rrd);
+uint64_t rrd_tail(rrd_t *rrd);
+uint64_t rrd_get(rrd_t *rrd, size_t i);
+
+void rrd_add(rrd_t *rrd, hrtime_t time, uint64_t txg);
+
+void dbrrd_add(dbrrd_t *db, hrtime_t time, uint64_t txg);
+uint64_t dbrrd_query(dbrrd_t *r, hrtime_t tv, dbrrd_rounding_t rouding);
+
+#endif

lib/libzfs/libzfs.abi

@@ -574,6 +574,7 @@
     <elf-symbol name='zpool_reguid' type='func-type' binding='global-binding' visibility='default-visibility' is-defined='yes'/>
     <elf-symbol name='zpool_reopen_one' type='func-type' binding='global-binding' visibility='default-visibility' is-defined='yes'/>
     <elf-symbol name='zpool_scan' type='func-type' binding='global-binding' visibility='default-visibility' is-defined='yes'/>
+    <elf-symbol name='zpool_scan_range' type='func-type' binding='global-binding' visibility='default-visibility' is-defined='yes'/>
     <elf-symbol name='zpool_search_import' type='func-type' binding='global-binding' visibility='default-visibility' is-defined='yes'/>
     <elf-symbol name='zpool_set_bootenv' type='func-type' binding='global-binding' visibility='default-visibility' is-defined='yes'/>
     <elf-symbol name='zpool_set_guid' type='func-type' binding='global-binding' visibility='default-visibility' is-defined='yes'/>
@@ -6946,6 +6947,14 @@
       <parameter type-id='b51cf3c2' name='cmd'/>
       <return type-id='95e97e5e'/>
     </function-decl>
+    <function-decl name='zpool_scan_range' mangled-name='zpool_scan_range' visibility='default' binding='global' size-in-bits='64' elf-symbol-id='zpool_scan_range'>
+      <parameter type-id='4c81de99' name='zhp'/>
+      <parameter type-id='7313fbe2' name='func'/>
+      <parameter type-id='b51cf3c2' name='cmd'/>
+      <parameter type-id='c9d12d66' name='date_start'/>
+      <parameter type-id='c9d12d66' name='date_end'/>
+      <return type-id='95e97e5e'/>
+    </function-decl>
     <function-decl name='zpool_find_vdev_by_physpath' mangled-name='zpool_find_vdev_by_physpath' visibility='default' binding='global' size-in-bits='64' elf-symbol-id='zpool_find_vdev_by_physpath'>
       <parameter type-id='4c81de99' name='zhp'/>
       <parameter type-id='80f4b756' name='ppath'/>

lib/libzfs/libzfs_pool.c

@@ -2773,7 +2773,13 @@ zpool_trim(zpool_handle_t *zhp, pool_trim_func_t cmd_type, nvlist_t *vds,
  * Scan the pool.
  */
 int
-zpool_scan(zpool_handle_t *zhp, pool_scan_func_t func, pool_scrub_cmd_t cmd)
+zpool_scan(zpool_handle_t *zhp, pool_scan_func_t func, pool_scrub_cmd_t cmd) {
+	return (zpool_scan_range(zhp, func, cmd, 0, 0));
+}
+
+int
+zpool_scan_range(zpool_handle_t *zhp, pool_scan_func_t func,
+    pool_scrub_cmd_t cmd, time_t date_start, time_t date_end)
 {
 	char errbuf[ERRBUFLEN];
 	int err;
@@ -2782,6 +2788,8 @@ zpool_scan(zpool_handle_t *zhp, pool_scan_func_t func, pool_scrub_cmd_t cmd)
 	nvlist_t *args = fnvlist_alloc();
 	fnvlist_add_uint64(args, "scan_type", (uint64_t)func);
 	fnvlist_add_uint64(args, "scan_command", (uint64_t)cmd);
+	fnvlist_add_uint64(args, "scan_date_start", (uint64_t)date_start);
+	fnvlist_add_uint64(args, "scan_date_end", (uint64_t)date_end);
 
 	err = lzc_scrub(ZFS_IOC_POOL_SCRUB, zhp->zpool_name, args, NULL);
 	fnvlist_free(args);

lib/libzpool/Makefile.am

@@ -177,6 +177,7 @@ nodist_libzpool_la_SOURCES = \
 	module/zfs/zfs_byteswap.c \
 	module/zfs/zfs_chksum.c \
 	module/zfs/zfs_debug_common.c \
+	module/zfs/zfs_crrd.c \
 	module/zfs/zfs_fm.c \
 	module/zfs/zfs_fuid.c \
 	module/zfs/zfs_ratelimit.c \

man/man4/zfs.4

@@ -2246,6 +2246,21 @@ Defer frees starting in this pass.
 Maximum memory used for prefetching a checkpoint's space map on each
 vdev while discarding the checkpoint.
 .
+.It Sy zfs_spa_note_txg_time Ns = Ns Sy 600 Pq uint
+This parameter defines, in seconds, how often the TXG time database will record
+a new TXG if it has changed.
+After the specified time interval has passed, and if the TXG number has changed,
+the new value is recorded in the database.
+These timestamps can later be used for more granular operations, such as
+scrubbing.
+.
+.It Sy zfs_spa_flush_txg_time Ns = Ns Sy 600 Pq uint
+This parameter defines, in seconds, how often the ZFS will flush
+the TXG time database to disk.
+It ensures that the data is actually written to persistent storage, which helps
+preserve the database in case of unexpected shutdown.
+The database is also automatically flushed during the export sequence.
+.
 .It Sy zfs_special_class_metadata_reserve_pct Ns = Ns Sy 25 Ns % Pq uint
 Only allow small data blocks to be allocated on the special and dedup vdev
 types when the available free space percentage on these vdevs exceeds this

man/man8/zpool-scrub.8

@@ -28,7 +28,7 @@
 .\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
 .\" Copyright (c) 2025 Hewlett Packard Enterprise Development LP.
 .\"
-.Dd November 18, 2024
+.Dd December 11, 2024
 .Dt ZPOOL-SCRUB 8
 .Os
 .
@@ -40,6 +40,8 @@
 .Cm scrub
 .Op Ns Fl e | Ns Fl p | Fl s Ns | Fl C Ns
 .Op Fl w
+.Op Fl S Ar date
+.Op Fl E Ar date
 .Fl a Ns | Ns Ar pool Ns …
 .
 .Sh DESCRIPTION
@@ -125,6 +127,44 @@ resilvering, nor can it be run when a regular scrub is paused.
 Continue scrub from last saved txg (see zpool
 .Sy last_scrubbed_txg
 property).
+.It Fl S Ar date , Fl E Ar date
+Allows specifying the date range for blocks created between these dates.
+.Bl -bullet -compact -offset indent
+.It
+.Fl S
+Defines a start date.
+If not specified, scrubbing begins from the start of the pool's
+existence.
+.It
+.Fl E
+Defines an end date.
+If not specified, scrubbing continues up to the most recent data.
+.El
+The provided date should be in the format:
+.Dq YYYY-MM-DD HH:MM .
+Where:
+.Bl -bullet -compact -offset indent
+.It
+.Dq YYYY
+is the year.
+.It
+.Dq MM
+is the numeric representation of the month.
+.It
+.Dq DD
+is the day of the month.
+.It
+.Dq HH
+is the hour.
+.It
+.Dq MM
+is the minutes.
+.El
+The hour and minutes parameters can be omitted.
+The time should be provided in machine local time zone.
+Specifying dates prior to enabling this feature will result in scrubbing
+starting from the date the pool was created.
+If the time was moved backward manually the data range may become inaccurate.
 .El
 .Sh EXAMPLES
 .Ss Example 1