From f80338facc955928416e7f4b30f0cc05df15f4b1 Mon Sep 17 00:00:00 2001 From: Christos Longros <98426896+chrislongros@users.noreply.github.com> Date: Mon, 16 Mar 2026 19:08:05 +0100 Subject: [PATCH] zarcsummary: add man page Reviewed-by: Brian Behlendorf Reviewed-by: Alexander Motin Signed-off-by: Christos Longros Closes #18330 --- contrib/debian/openzfs-zfsutils.install | 1 + man/Makefile.am | 1 + man/man1/zarcsummary.1 | 179 ++++++++++++++++++++++++ 3 files changed, 181 insertions(+) create mode 100644 man/man1/zarcsummary.1 diff --git a/contrib/debian/openzfs-zfsutils.install b/contrib/debian/openzfs-zfsutils.install index ac262db85..5e7cdb985 100644 --- a/contrib/debian/openzfs-zfsutils.install +++ b/contrib/debian/openzfs-zfsutils.install @@ -42,6 +42,7 @@ usr/bin/dbufstat usr/sbin usr/bin/zilstat usr/share/zfs/compatibility.d/ usr/share/bash-completion/completions +usr/share/man/man1/zarcsummary.1 usr/share/man/man1/zarcstat.1 usr/share/man/man1/zhack.1 usr/share/man/man1/zilstat.1 diff --git a/man/Makefile.am b/man/Makefile.am index 9ecb38945..5eb7fd95d 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -4,6 +4,7 @@ dist_noinst_man_MANS = \ dist_man_MANS = \ %D%/man1/zilstat.1 \ + %D%/man1/zarcsummary.1 \ %D%/man1/zarcstat.1 \ %D%/man1/raidz_test.1 \ %D%/man1/test-runner.1 \ diff --git a/man/man1/zarcsummary.1 b/man/man1/zarcsummary.1 new file mode 100644 index 000000000..6574417b4 --- /dev/null +++ b/man/man1/zarcsummary.1 @@ -0,0 +1,179 @@ +.\" 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) 2026 Christos Longros. All rights reserved. +.\" +.Dd March 14, 2026 +.Dt ZARCSUMMARY 1 +.Os +. +.Sh NAME +.Nm zarcsummary +.Nd print ZFS ARC and subsystem statistics +.Sh SYNOPSIS +.Nm +.Op Fl adghr +.Op Fl p Ar page +.Op Fl s Ar section +. +.Sh DESCRIPTION +.Nm +collects statistics from the running kernel and prints a human-readable +report on the state of the ZFS Adaptive Replacement Cache +.Pq ARC +and several related subsystems. +The output is a snapshot; for periodic sampling, use +.Xr zarcstat 1 +instead. +.Pp +When invoked without arguments, +.Nm +prints all sections in sequence. +A single section may be selected with the +.Fl s +option. +.Pp +The report is organized into the following sections: +.Bl -tag -offset Ds -width "tunables" +.It Sy arc +Current and target ARC sizes, the split between the Most Recently Used +.Pq MRU +and Most Frequently Used +.Pq MFU +lists, overall hit and miss ratios, compression savings, and whether the +ARC is experiencing memory pressure. +.It Sy archits +Breakdown of ARC hits and misses by demand reads versus prefetches +and data versus metadata. +.It Sy dmu +Data Management Unit predictive prefetcher statistics, including stream +hits, misses, and I/O issued ahead of and behind the current stream. +.It Sy l2arc +Level-2 ARC statistics for any cache devices attached to imported pools. +This section only appears when an L2ARC device is present and covers +bytes read and written, hit rates, and eviction activity. +.It Sy spl +Solaris Porting Layer memory allocator statistics. +This section is only available on Linux. +.It Sy tunables +Current values of kernel tunables that govern ARC behavior, including +.Va zfs_arc_max +and +.Va zfs_arc_min . +Combining this section with +.Fl d +adds a brief explanation of each tunable. +.It Sy zil +ZFS Intent Log statistics: committed transaction counts, flush requests +to stable storage, and the byte-level split between normal vdevs and +any separate log +.Pq SLOG +device. +.El +. +.Sh OPTIONS +.Bl -tag -width "-s" +.It Fl a , -alternate +Use an alternate layout for the tunables and SPL sections. +.It Fl d , -description +Print a short description next to each tunable and SPL entry. +.It Fl h , -help +Display a help message. +.It Fl g , -graph +Print an ASCII graph of current ARC use and exit. +.It Fl p Ar page , Fl -page Ar page +Print a section by its legacy page number. +.Sy Deprecated ; +use +.Fl s +instead. +.It Fl r , -raw +Dump all available data with minimal formatting. +.It Fl s Ar section , Fl -section Ar section +Print only the named section. +See +.Sx DESCRIPTION +for the list of valid section names. +.El +. +.Sh ENVIRONMENT +.Bl -tag -width "FreeBSD" +.It Sy Linux +Statistics are read from +.Pa /proc/spl/kstat/zfs/ . +.It Fx +Statistics are read via +.Xr sysctl 3 +from the +.Va vfs.zfs +and +.Va kstat.zfs.misc +trees. +The +.Pa py-sysctl +package must be installed for +.Nm +to function. +.El +. +.Sh EXIT STATUS +.Ex -std +. +.Sh EXAMPLES +Print the full report: +.Dl # zarcsummary +.Pp +Display only ARC size and hit rate information: +.Dl # zarcsummary -s arc +.Pp +Show a visual overview of ARC health: +.Dl # zarcsummary -g +.Pp +Search for all statistics containing +.Dq hit : +.Dl # zarcsummary -r | grep hit +.Pp +Review all tunables with their descriptions: +.Dl # zarcsummary -d -s tunables +. +.Sh SEE ALSO +.Xr zarcstat 1 , +.Xr zpool-status 8 +. +.Sh HISTORY +.Nm +originated as a Perl script called +.Nm arc_summary , +written by +.An Ben Rockwood +in 2008 for Solaris. +.An Martin Matuska +ported it to +.Fx +in 2010, and +.An Jason J. Hellenthal +took over maintenance. +.An Scot W. Stevenson +contributed a full rewrite in Python 3 in 2017, introducing the +.Fl g , +.Fl r , +and +.Fl s +options along with the section-based output layout. +The tool was renamed from +.Nm arc_summary +to +.Nm zarcsummary +in 2025 to align with the OpenZFS command naming convention. +. +.Sh AUTHORS +This manual page was written by +.An Christos Longros Aq Mt chris.longros@gmail.com .