Add TXG timestamp database

This feature enables tracking of when TXGs are committed to disk,
providing an estimated timestamp for each TXG.

With this information, it becomes possible to perform scrubs based
on specific date ranges, improving the granularity of
data management and recovery operations.

Signed-off-by: Mariusz Zaborski <[email protected]>
Sponsored-by: Klara, Inc.
Sponsored-by: Wasabi Technology, Inc.

Author: oshogbo

cmd/zpool/zpool_main.c

@@ -513,7 +513,7 @@ get_usage(zpool_help_t idx)
 		return (gettext("\tinitialize [-c | -s | -u] [-w] <pool> "
 		    "[<device> ...]\n"));
 	case HELP_SCRUB:
-		return (gettext("\tscrub [-e | -s | -p | -C] [-w] "
+		return (gettext("\tscrub [-e | -s | -p | -C | -E | -S] [-w] "
 		    "<pool> ...\n"));
 	case HELP_RESILVER:
 		return (gettext("\tresilver <pool> ...\n"));
@@ -8368,6 +8368,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
@@ -8411,7 +8413,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(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) {
@@ -8430,10 +8433,27 @@ wait_callback(zpool_handle_t *zhp, void *data)
 	return (zpool_wait(zhp, *act));
 }
 
+static time_t
+date_string_to_sec(const char *timestr)
+{
+	struct tm tm = {0};
+
+	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);
+		}
+	}
+
+	return (timegm(&tm));
+}
+
 /*
- * 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.
@@ -8449,21 +8469,28 @@ 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;
 	boolean_t is_stop = B_FALSE;
 	boolean_t is_txg_continue = B_FALSE;
 
 	/* check options */
-	while ((c = getopt(argc, argv, "spweC")) != -1) {
+	while ((c = getopt(argc, argv, "spweCE:S:")) != -1) {
 		switch (c) {
 		case 'e':
 			is_error_scrub = B_TRUE;
 			break;
+		case 'E':
+			cb.cb_date_end = date_string_to_sec(optarg);
+			break;
 		case 's':
 			is_stop = B_TRUE;
 			break;
+		case 'S':
+			cb.cb_date_start = date_string_to_sec(optarg);
+			break;
 		case 'p':
 			is_pause = B_TRUE;
 			break;
@@ -8511,6 +8538,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: "
@@ -8551,6 +8591,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

@@ -291,7 +291,8 @@ typedef struct trimflags {
 /*
  * 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(zpool_handle_t *, pool_scan_func_t, pool_scrub_cmd_t,
+    time_t, time_t);
 _LIBZFS_H int zpool_initialize(zpool_handle_t *, pool_initialize_func_t,
     nvlist_t *);
 _LIBZFS_H int zpool_initialize_wait(zpool_handle_t *, pool_initialize_func_t,

include/sys/dmu.h

@@ -394,6 +394,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
@@ -343,6 +345,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
+ * Fred Weigel <[email protected]>
+ * Mariusz Zaborski <[email protected]>
+ * 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);
+const 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

@@ -6702,6 +6702,8 @@
       <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'>

lib/libzfs/libzfs_pool.c

@@ -2730,7 +2730,8 @@ 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,
+    time_t date_start, time_t date_end)
 {
 	char errbuf[ERRBUFLEN];
 	int err;
@@ -2739,6 +2740,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

@@ -179,6 +179,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/man8/zpool-scrub.8

@@ -27,7 +27,7 @@
 .\" Copyright 2017 Nexenta Systems, Inc.
 .\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
 .\"
-.Dd November 18, 2024
+.Dd December 11, 2024
 .Dt ZPOOL-SCRUB 8
 .Os
 .
@@ -39,6 +39,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
 .Ar pool Ns …
 .
 .Sh DESCRIPTION
@@ -109,15 +111,49 @@ Wait until scrub has completed before returning.
 .It Fl e
 Only scrub files with known data errors as reported by
 .Nm zpool Cm status Fl v .
-The pool must have been scrubbed at least once with the
-.Sy head_errlog
-feature enabled to use this option.
 Error scrubbing cannot be run simultaneously with regular scrubbing or
 resilvering, nor can it be run when a regular scrub is paused.
 .It Fl C
 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.
 .El
 .Sh EXAMPLES
 .Ss Example 1

module/Kbuild.in

@@ -414,6 +414,7 @@ ZFS_OBJS := \
 	zfs_byteswap.o \
 	zfs_chksum.o \
 	zfs_debug_common.o \
+	zfs_crrd.o \
 	zfs_fm.o \
 	zfs_fuid.o \
 	zfs_impl.o \

module/Makefile.bsd

@@ -217,6 +217,7 @@ SRCS+=	abd_os.c \
 	vdev_label_os.c \
 	zfs_acl.c \
 	zfs_ctldir.c \
+	zfs_crrd.c \
 	zfs_debug.c \
 	zfs_dir.c \
 	zfs_file_os.c \