diff --git a/contrib/debian/openzfs-zfsutils.install b/contrib/debian/openzfs-zfsutils.install index 5e7cdb98571c..fa203185316f 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/dbufstat.1 usr/share/man/man1/zarcsummary.1 usr/share/man/man1/zarcstat.1 usr/share/man/man1/zhack.1 diff --git a/man/Makefile.am b/man/Makefile.am index 5eb7fd95d3c8..6b44cfddfaf6 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -3,6 +3,7 @@ dist_noinst_man_MANS = \ %D%/man1/cstyle.1 dist_man_MANS = \ + %D%/man1/dbufstat.1 \ %D%/man1/zilstat.1 \ %D%/man1/zarcsummary.1 \ %D%/man1/zarcstat.1 \ diff --git a/man/man1/dbufstat.1 b/man/man1/dbufstat.1 new file mode 100644 index 000000000000..311af5e76a98 --- /dev/null +++ b/man/man1/dbufstat.1 @@ -0,0 +1,233 @@ +.\" 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) 2013 Lawrence Livermore National Security, LLC. +.\" +.Dd March 19, 2026 +.Dt DBUFSTAT 1 +.Os +. +.Sh NAME +.Nm dbufstat +.Nd display statistics for DMU buffer cache +.Sh SYNOPSIS +.Nm +.Op Fl bdhnrtvx +.Op Fl f Ar field Ns Op , Ns Ar field Ns … +.Op Fl F Ar field Ns = Ns Ar value Ns Op , Ns … +.Op Fl i Ar file +.Op Fl o Ar file +.Op Fl s Ar separator +. +.Sh DESCRIPTION +.Nm +displays statistics about the DMU (Data Management Unit) buffer +cache, also known as the dbuf cache. +This information is read from the +.Sy dbufs +kstat +.Po Pa /proc/spl/kstat/zfs/dbufs +on Linux and +.Sy kstat.zfs.misc.dbufs +on FreeBSD +.Pc . +.Pp +.Nm +can display data in three modes: +.Bl -tag -width "-b" +.It Fl b +Display a table of information for each individual dbuf +(buffer). +This is the most detailed view. +.It Fl d +Display a table of information for each dnode +(the default mode). +Multiple dbufs belonging to the same dnode are +aggregated. +.It Fl t +Display a table of information for each dnode type. +Multiple dnodes of the same type are aggregated. +.El +.Pp +The following fields are available for display. +Not all fields are compatible with all modes; use +.Fl v +to see which fields are incompatible with each mode. +.Bl -tag -compact -offset Ds -width "indirect" +.It Sy pool +Pool name. +.It Sy objset +Dataset identification number. +.It Sy object +Object number. +.It Sy level +Indirection level of buffer. +.It Sy blkid +Block number of buffer. +.It Sy offset +Offset in object of buffer. +.It Sy dbsize +Size of buffer. +.It Sy usize +Size of attached user data. +.It Sy meta +Whether this buffer is metadata. +.It Sy state +State of buffer (read, cached, etc). +.It Sy dbholds +Number of holds on buffer. +.It Sy dbc +Whether this buffer is in the dbuf cache. +.It Sy list +Which ARC list contains this buffer. +.It Sy atype +ARC header type (data or metadata). +.It Sy flags +ARC read flags. +.It Sy count +ARC data count. +.It Sy asize +Size of this ARC buffer. +.It Sy access +Time this ARC buffer was last accessed. +.It Sy mru +Hits while on the ARC's MRU list. +.It Sy gmru +Hits while on the ARC's MRU ghost list. +.It Sy mfu +Hits while on the ARC's MFU list. +.It Sy gmfu +Hits while on the ARC's MFU ghost list. +.It Sy l2 +Hits while on the L2ARC. +.It Sy l2_dattr +L2ARC disk address/offset. +.It Sy l2_asize +L2ARC allocated size (depends on compression). +.It Sy l2_comp +L2ARC compression algorithm for buffer. +.It Sy aholds +Number of holds on this ARC buffer. +.It Sy dtype +Dnode type. +.It Sy btype +Bonus buffer type. +.It Sy data_bs +Data block size. +.It Sy meta_bs +Metadata block size. +.It Sy bsize +Bonus buffer size. +.It Sy lvls +Number of indirection levels. +.It Sy dholds +Number of holds on dnode. +.It Sy blocks +Number of allocated blocks. +.It Sy dsize +Size of dnode. +.It Sy cached +Bytes cached for all blocks. +.It Sy direct +Bytes cached for direct blocks. +.It Sy indirect +Bytes cached for indirect blocks. +.It Sy bonus +Bytes cached for bonus buffer. +.It Sy spill +Bytes cached for spill block. +.El +. +.Sh OPTIONS +.Bl -tag -width "-F filter" +.It Fl b +Display information for each individual dbuf. +.It Fl d +Display information for each dnode (default). +.It Fl f Ar field Ns Op , Ns Ar field Ns … +Display only the specified fields. +.It Fl F Ar field Ns = Ns Ar value Ns Op , Ns … +Filter output by field value or regular expression. +Multiple filters may be specified as a comma-separated list. +.It Fl h +Display a help message. +.It Fl i Ar file +Redirect input from the specified file instead of the +.Sy dbufs +kstat. +.It Fl n +Exclude the header from output. +.It Fl o Ar file +Redirect output to the specified file instead of standard output. +.It Fl r +Display raw values. +Specify twice to also display numeric type and compression +identifiers instead of names. +.It Fl s Ar separator +Override the default field separator (two spaces) with a +custom character or string. +.It Fl t +Display information for each dnode type. +.It Fl v +List all possible field headers, definitions, and +incompatibilities for each mode. +.It Fl x +Display extended statistics. +.El +. +.Sh EXAMPLES +Display per-dnode statistics (default mode): +.Bd -literal -compact -offset Ds +# dbufstat -d + pool objset object dtype cached + zroot 30 34466 DMU_OT_DIRECTORY_CONTENTS 240K + zroot 30 0 DMU_OT_DNODE 14M + zroot 30 36343 DMU_OT_DIRECTORY_CONTENTS 1024 + zroot 30 32921 DMU_OT_PLAIN_FILE_CONTENTS 2.5K +.Ed +.Pp +Display per-type statistics: +.Bd -literal -compact -offset Ds +# dbufstat -t + pool objset dtype cached + zroot 30 DMU_OT_DIRECTORY_CONTENTS 1.9M + zroot 30 DMU_OT_DNODE 14M + zroot 30 DMU_OT_PLAIN_FILE_CONTENTS 8.4M + zroot 0 DMU_OT_DSL_PROPS 2.6M +.Ed +.Pp +Display per-buffer statistics: +.Bd -literal -compact -offset Ds +# dbufstat -b + pool objset object level blkid offset dbsize + zroot 30 34466 1 0 0 128K + zroot 30 0 0 292 4.6M 16K + zroot 30 34466 0 8 128K 16K + zroot 0 4 0 0 0 128K +.Ed +.Pp +Display specific fields per dnode: +.Dl # Nm dbufstat Fl d Fl f Ar pool,object,objset,dsize,cached +.Pp +Display per-type statistics with comma-separated output: +.Dl # Nm dbufstat Fl t Fl s Qq , +.Pp +Display extended per-buffer statistics with filters: +.Dl # Nm dbufstat Fl bx Fl F Ar dbc=1,pool=zroot +. +.Sh SEE ALSO +.Xr zarcstat 1 , +.Xr zfs 8 , +.Xr zpool-iostat 8 +. +.Sh AUTHORS +This man page was written by +.An Christos Longros Aq Mt chris.longros@gmail.com .