Add allocation profile export and zleak utility for import

When attempting to debug performance problems on large systems, one of
the major factors that affect performance is free space
fragmentation. This heavily affects the allocation process, which is an
area of active development in ZFS. Unfortunately, fragmenting a large
pool for testing purposes is time consuming; it usually involves filling
the pool and then repeatedly overwriting data until the free space
becomes fragmented, which can take many hours. And even if the time is
available, artificial workloads rarely generate the same fragmentation
patterns as the natural workloads they're attempting to mimic.

This patch has two parts. First, in zdb, we add the ability to export
the full allocation map of the pool. It iterates over each vdev,
printing every allocated segment in the ms_allocatable range tree. This
can be done while the pool is online, though in that case the allocation
map may actually be from several different TXGs as new ones are loaded
on demand.

The second is a new utility called zleak (and its supporting library and
kernel changes). This is a small python program that invokes a new ioctl
(via libzfs_core): zfs_ioc_raw_alloc. This ioctl takes in an nvlist of
allocations to perform, and then allocates them. It does not currently
store those allocations anywhere to make them reversible, and there is
no corresponding raw_free ioctl (which would be extremely dangerous);
this is an irreversible process, only intended for performance
testing. The only way to reclaim the space afterwards is to destroy the
pool or roll back to a checkpoint.

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

Author: Paul Dagnelie

cmd/Makefile.am

@@ -98,15 +98,17 @@ endif
 
 
 if USING_PYTHON
-bin_SCRIPTS      += arc_summary     arcstat        dbufstat        zilstat
-CLEANFILES       += arc_summary     arcstat        dbufstat        zilstat
-dist_noinst_DATA += %D%/arc_summary %D%/arcstat.in %D%/dbufstat.in %D%/zilstat.in
+bin_SCRIPTS      += arc_summary     arcstat        dbufstat        zilstat        zleak
+CLEANFILES       += arc_summary     arcstat        dbufstat        zilstat        zleak
+dist_noinst_DATA += %D%/arc_summary %D%/arcstat.in %D%/dbufstat.in %D%/zilstat.in %D%/zleak
 
 $(call SUBST,arcstat,%D%/)
 $(call SUBST,dbufstat,%D%/)
 $(call SUBST,zilstat,%D%/)
 arc_summary: %D%/arc_summary
 	$(AM_V_at)cp $< $@
+zleak: %D%/zleak
+	$(AM_V_at)cp $< $@
 endif
 
 

cmd/zdb/zdb.c

@@ -107,7 +107,9 @@ extern uint_t zfs_reconstruct_indirect_combinations_max;
 extern uint_t zfs_btree_verify_intensity;
 
 static const char cmdname[] = "zdb";
-uint8_t dump_opt[256];
+uint8_t dump_opt[512];
+
+#define	ALLOCATABLE_OPT	256
 
 typedef void object_viewer_t(objset_t *, uint64_t, void *data, size_t size);
 
@@ -1650,6 +1652,16 @@ dump_metaslab_stats(metaslab_t *msp)
 	dump_histogram(rt->rt_histogram, ZFS_RANGE_TREE_HISTOGRAM_SIZE, 0);
 }
 
+static void
+dump_allocated(void *arg, uint64_t start, uint64_t size)
+{
+	uint64_t *off = arg;
+	if (*off != start)
+		(void) printf("ALLOC: %"PRIu64" %"PRIu64"\n", *off,
+		    start - *off);
+	*off = start + size;
+}
+
 static void
 dump_metaslab(metaslab_t *msp)
 {
@@ -1666,13 +1678,24 @@ dump_metaslab(metaslab_t *msp)
 	    (u_longlong_t)msp->ms_id, (u_longlong_t)msp->ms_start,
 	    (u_longlong_t)space_map_object(sm), freebuf);
 
-	if (dump_opt['m'] > 2 && !dump_opt['L']) {
+	if (dump_opt[ALLOCATABLE_OPT] ||
+	    (dump_opt['m'] > 2 && !dump_opt['L'])) {
 		mutex_enter(&msp->ms_lock);
 		VERIFY0(metaslab_load(msp));
+	}
+
+	if (dump_opt['m'] > 2 && !dump_opt['L']) {
 		zfs_range_tree_stat_verify(msp->ms_allocatable);
 		dump_metaslab_stats(msp);
-		metaslab_unload(msp);
-		mutex_exit(&msp->ms_lock);
+	}
+
+	if (dump_opt[ALLOCATABLE_OPT]) {
+		uint64_t off = msp->ms_start;
+		zfs_range_tree_walk(msp->ms_allocatable, dump_allocated,
+		    &off);
+		if (off != msp->ms_start + msp->ms_size)
+			(void) printf("ALLOC: %"PRIu64" %"PRIu64"\n", off,
+			    msp->ms_size - off);
 	}
 
 	if (dump_opt['m'] > 1 && sm != NULL &&
@@ -1687,6 +1710,12 @@ dump_metaslab(metaslab_t *msp)
 		    SPACE_MAP_HISTOGRAM_SIZE, sm->sm_shift);
 	}
 
+	if (dump_opt[ALLOCATABLE_OPT] ||
+	    (dump_opt['m'] > 2 && !dump_opt['L'])) {
+		metaslab_unload(msp);
+		mutex_exit(&msp->ms_lock);
+	}
+
 	if (vd->vdev_ops == &vdev_draid_ops)
 		ASSERT3U(msp->ms_size, <=, 1ULL << vd->vdev_ms_shift);
 	else
@@ -1723,8 +1752,9 @@ print_vdev_metaslab_header(vdev_t *vd)
 		}
 	}
 
-	(void) printf("\tvdev %10llu   %s",
-	    (u_longlong_t)vd->vdev_id, bias_str);
+	(void) printf("\tvdev %10llu\t%s  metaslab shift %4lld",
+	    (u_longlong_t)vd->vdev_id, bias_str,
+	    (u_longlong_t)vd->vdev_ms_shift);
 
 	if (ms_flush_data_obj != 0) {
 		(void) printf("   ms_unflushed_phys object %llu",
@@ -9315,6 +9345,8 @@ main(int argc, char **argv)
 		{"all-reconstruction",	no_argument,		NULL, 'Y'},
 		{"livelist",		no_argument,		NULL, 'y'},
 		{"zstd-headers",	no_argument,		NULL, 'Z'},
+		{"allocatable-map",	no_argument,		NULL,
+		    ALLOCATABLE_OPT},
 		{0, 0, 0, 0}
 	};
 
@@ -9345,6 +9377,7 @@ main(int argc, char **argv)
 		case 'u':
 		case 'y':
 		case 'Z':
+		case ALLOCATABLE_OPT:
 			dump_opt[c]++;
 			dump_all = 0;
 			break;

cmd/zdb/zdb.h

@@ -29,6 +29,6 @@
 #define	_ZDB_H
 
 void dump_intent_log(zilog_t *);
-extern uint8_t dump_opt[256];
+extern uint8_t dump_opt[512];
 
 #endif	/* _ZDB_H */

cmd/zdb/zdb_il.c

@@ -48,7 +48,7 @@
 
 #include "zdb.h"
 
-extern uint8_t dump_opt[256];
+extern uint8_t dump_opt[512];
 
 static char tab_prefix[4] = "\t\t\t";
 

cmd/zleak

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: CDDL-1.0
+
+#
+# This file and its contents are supplied under the terms of the
+# Common Development and Distribution License ("CDDL"), version 1.0.
+# You may only use this file in accordance with the terms of version
+# 1.0 of the CDDL.
+#
+# A full copy of the text of the CDDL should have accompanied this
+# source.  A copy of the CDDL is also available via the Internet at
+# http://www.illumos.org/license/CDDL.
+#
+
+#
+# Copyright (c) 2025 by Klara, Inc.
+#
+
+import argparse, fileinput, libzfs_core, sys, errno
+
+def perform_raw_alloc(pool, ms_shift, ms_count, vdev_id, allocs, force,
+    verbose):
+    if args.verbose == 1:
+        print(f"Raw alloc: vdev {vdev_id}, {count} starting with offset "
+              f"{allocs[0][0]}")
+    if args.verbose >= 2:
+        print(f"Raw alloc: {pool} {ms_shift} {ms_count} {vdev_id} {count}")
+    try:
+        libzfs_core.lzc_raw_alloc(pool, 1 << ms_shift, ms_count, vdev_id,
+                                  allocs, args.force)
+    except libzfs_core.exceptions.ZFSGenericError as e:
+        if e.errno == errno.EINVAL:
+            print("Invalid map for provided pool")
+            sys.exit(1)
+        assert (e.errno == errno.E2BIG and force)
+        sys.exit(0)
+
+allocs = []
+count = 0
+
+parser = argparse.ArgumentParser(
+    prog='zleak',
+    description='facility to replicate memory fragmentation in ZFS'
+)
+parser.add_argument('poolname')
+parser.add_argument('-v', '--verbose', action='count', default=0)
+parser.add_argument('-f', '--force', action='store_true', default=False)
+args = parser.parse_args()
+
+pool = args.poolname.encode('utf-8')
+
+for line in fileinput.input('-'):
+    dump = False
+    line = line.rstrip()
+    if not line.startswith(("ALLOC: ", "\tvdev ", "\tmetaslabs ")):
+        continue
+
+    tokens = line.split()
+    if line.startswith("\tvdev    "):
+        next_vdev_id = int(tokens[1])
+        next_ms_shift = int(tokens[4])
+        next_ms_count = 0
+        dump = True
+    elif line.startswith("\tmetaslabs "):
+        next_ms_count = int(tokens[1])
+    else:
+        start = int(tokens[1])
+        size = int(tokens[2])
+        allocs.append((start, size))
+        count = count + 1
+
+    if count == 1000000 or (dump and count != 0):
+        perform_raw_alloc(pool, ms_shift, ms_count, vdev_id, allocs,
+                          args.force, args.verbose)
+        count = 0
+        allocs = []
+    vdev_id = next_vdev_id
+    ms_shift = next_ms_shift
+    ms_count = next_ms_count
+
+
+if count > 0:
+    perform_raw_alloc(pool, ms_shift, ms_count, vdev_id, allocs,
+                      args.force, args.verbose)
+

contrib/debian/openzfs-zfsutils.install

@@ -40,6 +40,7 @@ usr/sbin/arc_summary
 usr/sbin/arcstat
 usr/sbin/dbufstat
 usr/sbin/zilstat
+usr/sbin/zleak
 usr/share/zfs/compatibility.d/
 usr/share/bash-completion/completions
 usr/share/man/man1/arcstat.1

contrib/debian/rules.in

@@ -85,6 +85,7 @@ override_dh_auto_install:
 	mv '$(CURDIR)/debian/tmp/usr/bin/arcstat' '$(CURDIR)/debian/tmp/usr/sbin/arcstat'
 	mv '$(CURDIR)/debian/tmp/usr/bin/dbufstat' '$(CURDIR)/debian/tmp/usr/sbin/dbufstat'
 	mv '$(CURDIR)/debian/tmp/usr/bin/zilstat' '$(CURDIR)/debian/tmp/usr/sbin/zilstat'
+	mv '$(CURDIR)/debian/tmp/usr/bin/zleak' '$(CURDIR)/debian/tmp/usr/sbin/zleak'
 
 	@# Zed has dependencies outside of the system root.
 	mv '$(CURDIR)/debian/tmp/sbin/zed' '$(CURDIR)/debian/tmp/usr/sbin/zed'

contrib/pyzfs/libzfs_core/__init__.py

@@ -95,6 +95,7 @@
     lzc_set_props,
     lzc_list_children,
     lzc_list_snaps,
+    lzc_raw_alloc,
     receive_header,
 )
 
@@ -151,6 +152,7 @@
     'lzc_set_props',
     'lzc_list_children',
     'lzc_list_snaps',
+    'lzc_raw_alloc',
     'receive_header',
 ]
 

contrib/pyzfs/libzfs_core/_error_translation.py

@@ -696,6 +696,12 @@ def lzc_list_translate_error(ret, name, opts):
     raise _generic_exception(ret, name, "Error obtaining a list")
 
 
+def lzc_raw_alloc_translate_errors(ret, name):
+    if ret == 0:
+        return
+    raise _generic_exception(ret, name, "Error performing raw allocations")
+
+
 def _handle_err_list(ret, errlist, names, exception, mapper):
     '''
     Convert one or more errors from an operation into the requested exception.

contrib/pyzfs/libzfs_core/_libzfs_core.py

@@ -2056,6 +2056,38 @@ def lzc_list_snaps(name):
     return iter(snaps)
 
 
+def lzc_raw_alloc(poolname, metaslab_size, metaslab_count, vdev_id,
+                  allocations, force):
+    '''
+    Allocate regions of the provided vdev directly; useful primarily for
+    performance analysis of fragmented pools. Results in space leakage that it
+    is not currently possible to reclaim.
+
+    :param bytes poolname: the name of the pool to allocate in
+    :param int metaslab_size: the size of a metaslab in this pool (for
+        validation)
+    :param int metaslab_count: the number of metaslabs in this top level
+        vdev (for validation)
+    :param int vdev_id: the id of the top-level vdev to perform allocations
+        from
+    :param allocations: pairs of offset and size to allocate
+    :type fromsnap: list of (int, int)
+
+    :raises TooManyArguments: if too many allocations are passed in
+    '''
+    if len(allocations) > 1000000:
+        raise exceptions.TooManyArguments()
+    allocs = _ffi.new(f"uint64_t[{2 * len(allocations)}]")
+    for i in range(len(allocations)):
+        (s, l) = allocations[i]
+        allocs[2 * i] = s
+        allocs[2 * i + 1] = l
+    ret = _lib.lzc_raw_alloc(poolname, uint64_t(metaslab_size),
+                             uint64_t(metaslab_count), uint64_t(vdev_id),
+                             allocs, 2 * len(allocations), force)
+    errors.lzc_raw_alloc_translate_errors(ret, poolname)
+
+
 # TODO: a better way to init and uninit the library
 def _initialize():
     class LazyInit(object):