diff options
| author | Bernard Spil <brnrd@FreeBSD.org> | 2026-11-04 13:11:21 +0000 |
|---|---|---|
| committer | Bernard Spil <brnrd@FreeBSD.org> | 2026-11-04 13:13:12 +0000 |
| commit | a40a51f0424b40166578f022c5a3a9bd7a34d336 (patch) | |
| tree | 063fb0a8e5fc5826f32eb70d3242b032f4502e84 | |
| parent | 490ff806d9392b218b4674e64723269d72c7ce5a (diff) | |
sysutils/py-zfsstat: Add OpenZFS python tools
For OpenZFS Mastery book.
Anyone that has more stake in this, please take
ownership.
See https://io.mwl.io/@mwl/117555657357834894
Requested by: Michael W. Lucas <@mwl@io.mwl.io>
| -rw-r--r-- | sysutils/Makefile | 1 | ||||
| -rw-r--r-- | sysutils/py-zfsstat/Makefile | 54 | ||||
| -rw-r--r-- | sysutils/py-zfsstat/pkg-descr | 3 | ||||
| -rw-r--r-- | sysutils/py-zfsstat/src/dbufstat.1 | 233 | ||||
| -rw-r--r-- | sysutils/py-zfsstat/src/dbufstat.in | 687 | ||||
| -rw-r--r-- | sysutils/py-zfsstat/src/zarcstat.1 | 427 | ||||
| -rw-r--r-- | sysutils/py-zfsstat/src/zarcstat.in | 805 | ||||
| -rw-r--r-- | sysutils/py-zfsstat/src/zarcsummary | 1076 | ||||
| -rw-r--r-- | sysutils/py-zfsstat/src/zarcsummary.1 | 179 | ||||
| -rw-r--r-- | sysutils/py-zfsstat/src/zilstat.1 | 180 | ||||
| -rw-r--r-- | sysutils/py-zfsstat/src/zilstat.in | 556 |
11 files changed, 4201 insertions, 0 deletions
diff --git a/sysutils/Makefile b/sysutils/Makefile index f4e509e8ceea..6055a2828fac 100644 --- a/sysutils/Makefile +++ b/sysutils/Makefile @@ -1170,6 +1170,7 @@ SUBDIR += py-tldr SUBDIR += py-tmuxp SUBDIR += py-uptime + SUBDIR += py-zfsstat SUBDIR += qchroot SUBDIR += qdirstat SUBDIR += qflipper diff --git a/sysutils/py-zfsstat/Makefile b/sysutils/py-zfsstat/Makefile new file mode 100644 index 000000000000..42c4563875f5 --- /dev/null +++ b/sysutils/py-zfsstat/Makefile @@ -0,0 +1,54 @@ +PORTNAME= zfsstat +PORTVERSION= 2.4.4 +CATEGORIES= sysutils python +MASTER_SITES= # none +PKGNAMEPREFIX= ${PYTHON_PKGNAMEPREFIX} +DISTFILES= # none + +MAINTAINER= brnrd@FreeBSD.org +COMMENT= OpenZFS Python stat utilities +WWW= https://github.com/openzfs/zfs/tree/zfs-${PORTVERSION}/cmd + +LICENSE= CDDL + +RUN_DEPENDS= ${PYTHON_PKGNAMEPREFIX}sysctl>=0:devel/py-sysctl@${PY_FLAVOR} + +NO_ARCH= yes +NO_BUILD= yes +WRKSRC= ${WRKDIR}/src +SRC= ${.CURDIR}/src +USES= python shebangfix + +SRC_FILES= dbufstat.in zarcstat.in zarcsummary zilstat.in + +# All script and man files are taken directly from OpenZFS source + +SCRIPT_FILES= bin/dbufstat \ + bin/zarcstat \ + bin/zarcsummary \ + bin/zilstat + +MAN_FILES= share/man/man1/dbufstat.1.gz \ + share/man/man1/zarcstat.1.gz \ + share/man/man1/zarcsummary.1.gz \ + share/man/man1/zilstat.1.gz + +PLIST_FILES= ${SCRIPT_FILES} ${MAN_FILES} + +do-extract: + ${MKDIR} ${WRKSRC} +.for f in ${SRC_FILES} + ${SED} -e "1s|^.*$$|\#!${PYTHON_CMD}|" \ + ${SRC}/${f} > ${WRKSRC}/${f:C/.in$$//} +.endfor + @${CP} -R ${SRC}/*.1 ${WRKSRC} + +do-install: +.for f in ${SCRIPT_FILES} + ${INSTALL_SCRIPT} ${WRKSRC}/${f:C/^bin.//} ${STAGEDIR}${PREFIX}/bin/ +.endfor +.for f in ${SRC_FILES} + ${INSTALL_MAN} ${WRKSRC}/${f:C/.in$$//}.1 ${STAGEDIR}${MANDIRS}/man1/ +.endfor + +.include <bsd.port.mk> diff --git a/sysutils/py-zfsstat/pkg-descr b/sysutils/py-zfsstat/pkg-descr new file mode 100644 index 000000000000..afe3aee83315 --- /dev/null +++ b/sysutils/py-zfsstat/pkg-descr @@ -0,0 +1,3 @@ +Python utilities from OpenZFS. + +These are not included in FreeBSD base as they depend on Python. diff --git a/sysutils/py-zfsstat/src/dbufstat.1 b/sysutils/py-zfsstat/src/dbufstat.1 new file mode 100644 index 000000000000..ac41e461f878 --- /dev/null +++ b/sysutils/py-zfsstat/src/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 +.\" https://opensource.org/license/CDDL-1.0. +.\" +.\" 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 . diff --git a/sysutils/py-zfsstat/src/dbufstat.in b/sysutils/py-zfsstat/src/dbufstat.in new file mode 100644 index 000000000000..37e765f5c359 --- /dev/null +++ b/sysutils/py-zfsstat/src/dbufstat.in @@ -0,0 +1,687 @@ +#!/usr/bin/env @PYTHON_SHEBANG@ +# SPDX-License-Identifier: CDDL-1.0 +# +# Print out statistics for all cached dmu buffers. This information +# is available through the dbufs kstat and may be post-processed as +# needed by the script. +# +# CDDL HEADER START +# +# The contents of this file are subject to the terms of the +# Common Development and Distribution License, Version 1.0 only +# (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) 2013 Lawrence Livermore National Security, LLC. +# Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER). +# +# This script must remain compatible with and Python 3.6+. +# + +import sys +import getopt +import errno +import re + +bhdr = ["pool", "objset", "object", "level", "blkid", "offset", "dbsize"] +bxhdr = ["pool", "objset", "object", "level", "blkid", "offset", "dbsize", + "usize", "meta", "state", "dbholds", "dbc", "list", "atype", "flags", + "count", "asize", "access", "mru", "gmru", "mfu", "gmfu", "l2", + "l2_dattr", "l2_asize", "l2_comp", "aholds", "dtype", "btype", + "data_bs", "meta_bs", "bsize", "lvls", "dholds", "blocks", "dsize"] +bincompat = ["cached", "direct", "indirect", "bonus", "spill"] + +dhdr = ["pool", "objset", "object", "dtype", "cached"] +dxhdr = ["pool", "objset", "object", "dtype", "btype", "data_bs", "meta_bs", + "bsize", "lvls", "dholds", "blocks", "dsize", "cached", "direct", + "indirect", "bonus", "spill"] +dincompat = ["level", "blkid", "offset", "dbsize", "usize", "meta", "state", + "dbholds", "dbc", "list", "atype", "flags", "count", "asize", + "access", "mru", "gmru", "mfu", "gmfu", "l2", "l2_dattr", + "l2_asize", "l2_comp", "aholds"] + +thdr = ["pool", "objset", "dtype", "cached"] +txhdr = ["pool", "objset", "dtype", "cached", "direct", "indirect", + "bonus", "spill"] +tincompat = ["object", "level", "blkid", "offset", "dbsize", "usize", "meta", + "state", "dbc", "dbholds", "list", "atype", "flags", "count", + "asize", "access", "mru", "gmru", "mfu", "gmfu", "l2", "l2_dattr", + "l2_asize", "l2_comp", "aholds", "btype", "data_bs", "meta_bs", + "bsize", "lvls", "dholds", "blocks", "dsize"] + +cols = { + # hdr: [size, scale, description] + "pool": [15, -1, "pool name"], + "objset": [6, -1, "dataset identification number"], + "object": [10, -1, "object number"], + "level": [5, -1, "indirection level of buffer"], + "blkid": [8, -1, "block number of buffer"], + "offset": [12, 1024, "offset in object of buffer"], + "dbsize": [7, 1024, "size of buffer"], + "usize": [7, 1024, "size of attached user data"], + "meta": [4, -1, "is this buffer metadata?"], + "state": [5, -1, "state of buffer (read, cached, etc)"], + "dbholds": [7, 1000, "number of holds on buffer"], + "dbc": [3, -1, "in dbuf cache"], + "list": [4, -1, "which ARC list contains this buffer"], + "atype": [7, -1, "ARC header type (data or metadata)"], + "flags": [9, -1, "ARC read flags"], + "count": [5, -1, "ARC data count"], + "asize": [7, 1024, "size of this ARC buffer"], + "access": [10, -1, "time this ARC buffer was last accessed"], + "mru": [5, 1000, "hits while on the ARC's MRU list"], + "gmru": [5, 1000, "hits while on the ARC's MRU ghost list"], + "mfu": [5, 1000, "hits while on the ARC's MFU list"], + "gmfu": [5, 1000, "hits while on the ARC's MFU ghost list"], + "l2": [5, 1000, "hits while on the L2ARC"], + "l2_dattr": [8, -1, "L2ARC disk address/offset"], + "l2_asize": [8, 1024, "L2ARC alloc'd size (depending on compression)"], + "l2_comp": [21, -1, "L2ARC compression algorithm for buffer"], + "aholds": [6, 1000, "number of holds on this ARC buffer"], + "dtype": [27, -1, "dnode type"], + "btype": [27, -1, "bonus buffer type"], + "data_bs": [7, 1024, "data block size"], + "meta_bs": [7, 1024, "metadata block size"], + "bsize": [6, 1024, "bonus buffer size"], + "lvls": [6, -1, "number of indirection levels"], + "dholds": [6, 1000, "number of holds on dnode"], + "blocks": [8, 1000, "number of allocated blocks"], + "dsize": [12, 1024, "size of dnode"], + "cached": [6, 1024, "bytes cached for all blocks"], + "direct": [6, 1024, "bytes cached for direct blocks"], + "indirect": [8, 1024, "bytes cached for indirect blocks"], + "bonus": [5, 1024, "bytes cached for bonus buffer"], + "spill": [5, 1024, "bytes cached for spill block"], +} + +hdr = None +xhdr = None +sep = " " # Default separator is 2 spaces +cmd = ("Usage: dbufstat [-bdhnrtvx] [-i file] [-f fields] [-o file] " + "[-s string] [-F filter]\n") +raw = 0 + + +if sys.platform.startswith("freebsd"): + import io + # Requires py-sysctl on FreeBSD + import sysctl + + def default_ifile(): + dbufs = sysctl.filter("kstat.zfs.misc.dbufs")[0].value + sys.stdin = io.StringIO(dbufs) + return "-" + +elif sys.platform.startswith("linux"): + def default_ifile(): + return "/proc/spl/kstat/zfs/dbufs" + + +def print_incompat_helper(incompat): + cnt = 0 + for key in sorted(incompat): + if cnt == 0: + sys.stderr.write("\t") + elif cnt > 8: + sys.stderr.write(",\n\t") + cnt = 0 + else: + sys.stderr.write(", ") + + sys.stderr.write("%s" % key) + cnt += 1 + + sys.stderr.write("\n\n") + + +def detailed_usage(): + sys.stderr.write("%s\n" % cmd) + + sys.stderr.write("Field definitions incompatible with '-b' option:\n") + print_incompat_helper(bincompat) + + sys.stderr.write("Field definitions incompatible with '-d' option:\n") + print_incompat_helper(dincompat) + + sys.stderr.write("Field definitions incompatible with '-t' option:\n") + print_incompat_helper(tincompat) + + sys.stderr.write("Field definitions are as follows:\n") + for key in sorted(cols.keys()): + sys.stderr.write("%11s : %s\n" % (key, cols[key][2])) + sys.stderr.write("\n") + + sys.exit(0) + + +def usage(): + sys.stderr.write("%s\n" % cmd) + sys.stderr.write("\t -b : Print table of information for each dbuf\n") + sys.stderr.write("\t -d : Print table of information for each dnode\n") + sys.stderr.write("\t -h : Print this help message\n") + sys.stderr.write("\t -n : Exclude header from output\n") + sys.stderr.write("\t -r : Print raw values\n") + sys.stderr.write("\t -t : Print table of information for each dnode type" + "\n") + sys.stderr.write("\t -v : List all possible field headers and definitions" + "\n") + sys.stderr.write("\t -x : Print extended stats\n") + sys.stderr.write("\t -i : Redirect input from the specified file\n") + sys.stderr.write("\t -f : Specify specific fields to print (see -v)\n") + sys.stderr.write("\t -o : Redirect output to the specified file\n") + sys.stderr.write("\t -s : Override default field separator with custom " + "character or string\n") + sys.stderr.write("\t -F : Filter output by value or regex\n") + sys.stderr.write("\nExamples:\n") + sys.stderr.write("\tdbufstat -d -o /tmp/d.log\n") + sys.stderr.write("\tdbufstat -t -s \",\" -o /tmp/t.log\n") + sys.stderr.write("\tdbufstat -v\n") + sys.stderr.write("\tdbufstat -d -f pool,object,objset,dsize,cached\n") + sys.stderr.write("\tdbufstat -bx -F dbc=1,objset=54,pool=testpool\n") + sys.stderr.write("\n") + + sys.exit(1) + + +def prettynum(sz, scale, num=0): + global raw + + suffix = [' ', 'K', 'M', 'G', 'T', 'P', 'E', 'Z'] + index = 0 + save = 0 + + if raw or scale == -1: + return "%*s" % (sz, num) + + # Rounding error, return 0 + elif 0 < num < 1: + num = 0 + + while num > scale and index < 5: + save = num + num = num / scale + index += 1 + + if index == 0: + return "%*d" % (sz, num) + + if (save / scale) < 10: + return "%*.1f%s" % (sz - 1, num, suffix[index]) + else: + return "%*d%s" % (sz - 1, num, suffix[index]) + + +def print_values(v): + global hdr + global sep + + try: + for col in hdr: + sys.stdout.write("%s%s" % ( + prettynum(cols[col][0], cols[col][1], v[col]), sep)) + sys.stdout.write("\n") + except IOError as e: + if e.errno == errno.EPIPE: + sys.exit(1) + + +def print_header(): + global hdr + global sep + + try: + for col in hdr: + sys.stdout.write("%*s%s" % (cols[col][0], col, sep)) + sys.stdout.write("\n") + except IOError as e: + if e.errno == errno.EPIPE: + sys.exit(1) + + +def get_typestring(t): + ot_strings = [ + "DMU_OT_NONE", + # general: + "DMU_OT_OBJECT_DIRECTORY", + "DMU_OT_OBJECT_ARRAY", + "DMU_OT_PACKED_NVLIST", + "DMU_OT_PACKED_NVLIST_SIZE", + "DMU_OT_BPOBJ", + "DMU_OT_BPOBJ_HDR", + # spa: + "DMU_OT_SPACE_MAP_HEADER", + "DMU_OT_SPACE_MAP", + # zil: + "DMU_OT_INTENT_LOG", + # dmu: + "DMU_OT_DNODE", + "DMU_OT_OBJSET", + # dsl: + "DMU_OT_DSL_DIR", + "DMU_OT_DSL_DIR_CHILD_MAP", + "DMU_OT_DSL_DS_SNAP_MAP", + "DMU_OT_DSL_PROPS", + "DMU_OT_DSL_DATASET", + # zpl: + "DMU_OT_ZNODE", + "DMU_OT_OLDACL", + "DMU_OT_PLAIN_FILE_CONTENTS", + "DMU_OT_DIRECTORY_CONTENTS", + "DMU_OT_MASTER_NODE", + "DMU_OT_UNLINKED_SET", + # zvol: + "DMU_OT_ZVOL", + "DMU_OT_ZVOL_PROP", + # other; for testing only! + "DMU_OT_PLAIN_OTHER", + "DMU_OT_UINT64_OTHER", + "DMU_OT_ZAP_OTHER", + # new object types: + "DMU_OT_ERROR_LOG", + "DMU_OT_SPA_HISTORY", + "DMU_OT_SPA_HISTORY_OFFSETS", + "DMU_OT_POOL_PROPS", + "DMU_OT_DSL_PERMS", + "DMU_OT_ACL", + "DMU_OT_SYSACL", + "DMU_OT_FUID", + "DMU_OT_FUID_SIZE", + "DMU_OT_NEXT_CLONES", + "DMU_OT_SCAN_QUEUE", + "DMU_OT_USERGROUP_USED", + "DMU_OT_USERGROUP_QUOTA", + "DMU_OT_USERREFS", + "DMU_OT_DDT_ZAP", + "DMU_OT_DDT_STATS", + "DMU_OT_SA", + "DMU_OT_SA_MASTER_NODE", + "DMU_OT_SA_ATTR_REGISTRATION", + "DMU_OT_SA_ATTR_LAYOUTS", + "DMU_OT_SCAN_XLATE", + "DMU_OT_DEDUP", + "DMU_OT_DEADLIST", + "DMU_OT_DEADLIST_HDR", + "DMU_OT_DSL_CLONES", + "DMU_OT_BPOBJ_SUBOBJ"] + otn_strings = { + 0x80: "DMU_OTN_UINT8_DATA", + 0xc0: "DMU_OTN_UINT8_METADATA", + 0x81: "DMU_OTN_UINT16_DATA", + 0xc1: "DMU_OTN_UINT16_METADATA", + 0x82: "DMU_OTN_UINT32_DATA", + 0xc2: "DMU_OTN_UINT32_METADATA", + 0x83: "DMU_OTN_UINT64_DATA", + 0xc3: "DMU_OTN_UINT64_METADATA", + 0x84: "DMU_OTN_ZAP_DATA", + 0xc4: "DMU_OTN_ZAP_METADATA", + 0xa0: "DMU_OTN_UINT8_ENC_DATA", + 0xe0: "DMU_OTN_UINT8_ENC_METADATA", + 0xa1: "DMU_OTN_UINT16_ENC_DATA", + 0xe1: "DMU_OTN_UINT16_ENC_METADATA", + 0xa2: "DMU_OTN_UINT32_ENC_DATA", + 0xe2: "DMU_OTN_UINT32_ENC_METADATA", + 0xa3: "DMU_OTN_UINT64_ENC_DATA", + 0xe3: "DMU_OTN_UINT64_ENC_METADATA", + 0xa4: "DMU_OTN_ZAP_ENC_DATA", + 0xe4: "DMU_OTN_ZAP_ENC_METADATA"} + + # If "-rr" option is used, don't convert to string representation + if raw > 1: + return "%i" % t + + try: + if t < len(ot_strings): + return ot_strings[t] + else: + return otn_strings[t] + except (IndexError, KeyError): + return "(UNKNOWN)" + + +def get_compstring(c): + comp_strings = ["ZIO_COMPRESS_INHERIT", "ZIO_COMPRESS_ON", + "ZIO_COMPRESS_OFF", "ZIO_COMPRESS_LZJB", + "ZIO_COMPRESS_EMPTY", "ZIO_COMPRESS_GZIP_1", + "ZIO_COMPRESS_GZIP_2", "ZIO_COMPRESS_GZIP_3", + "ZIO_COMPRESS_GZIP_4", "ZIO_COMPRESS_GZIP_5", + "ZIO_COMPRESS_GZIP_6", "ZIO_COMPRESS_GZIP_7", + "ZIO_COMPRESS_GZIP_8", "ZIO_COMPRESS_GZIP_9", + "ZIO_COMPRESS_ZLE", "ZIO_COMPRESS_LZ4", + "ZIO_COMPRESS_ZSTD", "ZIO_COMPRESS_FUNCTION"] + + # If "-rr" option is used, don't convert to string representation + if raw > 1: + return "%i" % c + + try: + return comp_strings[c] + except IndexError: + return "%i" % c + + +def parse_line(line, labels): + global hdr + + new = dict() + val = None + for col in hdr: + # These are "special" fields computed in the update_dict + # function, prevent KeyError exception on labels[col] for these. + if col not in ['bonus', 'cached', 'direct', 'indirect', 'spill']: + val = line[labels[col]] + + if col in ['pool', 'flags']: + new[col] = str(val) + elif col in ['dtype', 'btype']: + new[col] = get_typestring(int(val)) + elif col in ['l2_comp']: + new[col] = get_compstring(int(val)) + else: + new[col] = int(val) + + return new + + +def update_dict(d, k, line, labels): + pool = line[labels['pool']] + objset = line[labels['objset']] + key = line[labels[k]] + + dbsize = int(line[labels['dbsize']]) + usize = int(line[labels['usize']]) + blkid = int(line[labels['blkid']]) + level = int(line[labels['level']]) + + if pool not in d: + d[pool] = dict() + + if objset not in d[pool]: + d[pool][objset] = dict() + + if key not in d[pool][objset]: + d[pool][objset][key] = parse_line(line, labels) + d[pool][objset][key]['bonus'] = 0 + d[pool][objset][key]['cached'] = 0 + d[pool][objset][key]['direct'] = 0 + d[pool][objset][key]['indirect'] = 0 + d[pool][objset][key]['spill'] = 0 + + d[pool][objset][key]['cached'] += dbsize + usize + + if blkid == -1: + d[pool][objset][key]['bonus'] += dbsize + elif blkid == -2: + d[pool][objset][key]['spill'] += dbsize + else: + if level == 0: + d[pool][objset][key]['direct'] += dbsize + else: + d[pool][objset][key]['indirect'] += dbsize + + return d + + +def skip_line(vals, filters): + ''' + Determines if a line should be skipped during printing + based on a set of filters + ''' + if len(filters) == 0: + return False + + for key in vals: + if key in filters: + val = prettynum(cols[key][0], cols[key][1], vals[key]).strip() + # we want a full match here + if re.match("(?:" + filters[key] + r")\Z", val) is None: + return True + + return False + + +def print_dict(d, filters, noheader): + if not noheader: + print_header() + for pool in list(d.keys()): + for objset in list(d[pool].keys()): + for v in list(d[pool][objset].values()): + if not skip_line(v, filters): + print_values(v) + + +def dnodes_build_dict(filehandle): + labels = dict() + dnodes = dict() + + # First 3 lines are header information, skip the first two + for i in range(2): + next(filehandle) + + # The third line contains the labels and index locations + for i, v in enumerate(next(filehandle).split()): + labels[v] = i + + # The rest of the file is buffer information + for line in filehandle: + update_dict(dnodes, 'object', line.split(), labels) + + return dnodes + + +def types_build_dict(filehandle): + labels = dict() + types = dict() + + # First 3 lines are header information, skip the first two + for i in range(2): + next(filehandle) + + # The third line contains the labels and index locations + for i, v in enumerate(next(filehandle).split()): + labels[v] = i + + # The rest of the file is buffer information + for line in filehandle: + update_dict(types, 'dtype', line.split(), labels) + + return types + + +def buffers_print_all(filehandle, filters, noheader): + labels = dict() + + # First 3 lines are header information, skip the first two + for i in range(2): + next(filehandle) + + # The third line contains the labels and index locations + for i, v in enumerate(next(filehandle).split()): + labels[v] = i + + if not noheader: + print_header() + + # The rest of the file is buffer information + for line in filehandle: + vals = parse_line(line.split(), labels) + if not skip_line(vals, filters): + print_values(vals) + + +def main(): + global hdr + global sep + global raw + + desired_cols = None + bflag = False + dflag = False + hflag = False + ifile = None + ofile = None + tflag = False + vflag = False + xflag = False + nflag = False + filters = dict() + + try: + opts, args = getopt.getopt( + sys.argv[1:], + "bdf:hi:o:rs:tvxF:n", + [ + "buffers", + "dnodes", + "columns", + "help", + "infile", + "outfile", + "separator", + "types", + "verbose", + "extended", + "filter" + ] + ) + except getopt.error: + usage() + opts = None + + for opt, arg in opts: + if opt in ('-b', '--buffers'): + bflag = True + if opt in ('-d', '--dnodes'): + dflag = True + if opt in ('-f', '--columns'): + desired_cols = arg + if opt in ('-h', '--help'): + hflag = True + if opt in ('-i', '--infile'): + ifile = arg + if opt in ('-o', '--outfile'): + ofile = arg + if opt in ('-r', '--raw'): + raw += 1 + if opt in ('-s', '--separator'): + sep = arg + if opt in ('-t', '--types'): + tflag = True + if opt in ('-v', '--verbose'): + vflag = True + if opt in ('-x', '--extended'): + xflag = True + if opt in ('-n', '--noheader'): + nflag = True + if opt in ('-F', '--filter'): + fils = [x.strip() for x in arg.split(",")] + + for fil in fils: + f = [x.strip() for x in fil.split("=")] + + if len(f) != 2: + sys.stderr.write("Invalid filter '%s'.\n" % fil) + sys.exit(1) + + if f[0] not in cols: + sys.stderr.write("Invalid field '%s' in filter.\n" % f[0]) + sys.exit(1) + + if f[0] in filters: + sys.stderr.write("Field '%s' specified multiple times in " + "filter.\n" % f[0]) + sys.exit(1) + + try: + re.compile("(?:" + f[1] + r")\Z") + except re.error: + sys.stderr.write("Invalid regex for field '%s' in " + "filter.\n" % f[0]) + sys.exit(1) + + filters[f[0]] = f[1] + + if hflag or (xflag and desired_cols): + usage() + + if vflag: + detailed_usage() + + # Ensure at most only one of b, d, or t flags are set + if (bflag and dflag) or (bflag and tflag) or (dflag and tflag): + usage() + + if bflag: + hdr = bxhdr if xflag else bhdr + elif tflag: + hdr = txhdr if xflag else thdr + else: # Even if dflag is False, it's the default if none set + dflag = True + hdr = dxhdr if xflag else dhdr + + if desired_cols: + hdr = desired_cols.split(",") + + invalid = [] + incompat = [] + for ele in hdr: + if ele not in cols: + invalid.append(ele) + elif ((bflag and bincompat and ele in bincompat) or + (dflag and dincompat and ele in dincompat) or + (tflag and tincompat and ele in tincompat)): + incompat.append(ele) + + if len(invalid) > 0: + sys.stderr.write("Invalid column definition! -- %s\n" % invalid) + usage() + + if len(incompat) > 0: + sys.stderr.write("Incompatible field specified! -- %s\n" % + incompat) + usage() + + if ofile: + try: + tmp = open(ofile, "w") + sys.stdout = tmp + + except IOError: + sys.stderr.write("Cannot open %s for writing\n" % ofile) + sys.exit(1) + + if not ifile: + ifile = default_ifile() + + if ifile != "-": + try: + tmp = open(ifile, "r") + sys.stdin = tmp + except IOError: + sys.stderr.write("Cannot open %s for reading\n" % ifile) + sys.exit(1) + + if bflag: + buffers_print_all(sys.stdin, filters, nflag) + + if dflag: + print_dict(dnodes_build_dict(sys.stdin), filters, nflag) + + if tflag: + print_dict(types_build_dict(sys.stdin), filters, nflag) + + +if __name__ == '__main__': + main() diff --git a/sysutils/py-zfsstat/src/zarcstat.1 b/sysutils/py-zfsstat/src/zarcstat.1 new file mode 100644 index 000000000000..0e1278e6d749 --- /dev/null +++ b/sysutils/py-zfsstat/src/zarcstat.1 @@ -0,0 +1,427 @@ +.\" 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 +.\" https://opensource.org/license/CDDL-1.0. +.\" +.\" Copyright 2014 Adam Stevko. All rights reserved. +.\" Copyright (c) 2015 by Delphix. All rights reserved. +.\" Copyright (c) 2020 by AJ Jordan. All rights reserved. +.\" +.Dd September 19, 2024 +.Dt ZARCSTAT 1 +.Os +. +.Sh NAME +.Nm zarcstat +.Nd report ZFS ARC and L2ARC statistics +.Sh SYNOPSIS +.Nm +.Op Fl havxp +.Op Fl f Ar field Ns Op , Ns Ar field Ns … +.Op Fl o Ar file +.Op Fl s Ar string +.Op Ar interval +.Op Ar count +. +.Sh DESCRIPTION +.Nm +prints various ZFS ARC and L2ARC statistics in vmstat-like fashion: +.Bl -tag -compact -offset Ds -width "l2asize" +.It Sy c +ARC target size +.It Sy dh% +Demand hit percentage +.It Sy di% +Demand I/O hit percentage +.It Sy dm% +Demand miss percentage +.It Sy ddh% +Demand data hit percentage +.It Sy ddi% +Demand data I/O hit percentage +.It Sy ddm% +Demand data miss percentage +.It Sy dmh% +Demand metadata hit percentage +.It Sy dmi% +Demand metadata I/O hit percentage +.It Sy dmm% +Demand metadata miss percentage +.It Sy mfu +MFU list hits per second +.It Sy mh% +Metadata hit percentage +.It Sy mi% +Metadata I/O hit percentage +.It Sy mm% +Metadata miss percentage +.It Sy mru +MRU list hits per second +.It Sy ph% +Prefetch hits percentage +.It Sy pi% +Prefetch I/O hits percentage +.It Sy pm% +Prefetch miss percentage +.It Sy pdh% +Prefetch data hits percentage +.It Sy pdi% +Prefetch data I/O hits percentage +.It Sy pdm% +Prefetch data miss percentage +.It Sy pmh% +Prefetch metadata hits percentage +.It Sy pmi% +Prefetch metadata I/O hits percentage +.It Sy pmm% +Prefetch metadata miss percentage +.It Sy dhit +Demand hits per second +.It Sy dioh +Demand I/O hits per second +.It Sy dmis +Demand misses per second +.It Sy ddhit +Demand data hits per second +.It Sy ddioh +Demand data I/O hits per second +.It Sy ddmis +Demand data misses per second +.It Sy dmhit +Demand metadata hits per second +.It Sy dmioh +Demand metadata I/O hits per second +.It Sy dmmis +Demand metadata misses per second +.It Sy hit% +ARC hit percentage +.It Sy hits +ARC hits per second +.It Sy ioh% +ARC I/O hits percentage +.It Sy iohs +ARC I/O hits per second +.It Sy mfug +MFU ghost list hits per second +.It Sy mhit +Metadata hits per second +.It Sy mioh +Metadata I/O hits per second +.It Sy miss +ARC misses per second +.It Sy mmis +Metadata misses per second +.It Sy mrug +MRU ghost list hits per second +.It Sy phit +Prefetch hits per second +.It Sy pioh +Prefetch I/O hits per second +.It Sy pmis +Prefetch misses per second +.It Sy pdhit +Prefetch data hits per second +.It Sy pdioh +Prefetch data I/O hits per second +.It Sy pdmis +Prefetch data misses per second +.It Sy pmhit +Prefetch metadata hits per second +.It Sy pmioh +Prefetch metadata I/O hits per second +.It Sy pmmis +Prefetch metadata misses per second +.It Sy read +Total ARC accesses per second +.It Sy time +Current time +.It Sy size +ARC size +.It Sy arcsz +Alias for +.Sy size +.It Sy unc +Uncached list hits per second +.It Sy dread +Demand accesses per second +.It Sy ddread +Demand data accesses per second +.It Sy dmread +Demand metadata accesses per second +.It Sy eskip +evict_skip per second +.It Sy miss% +ARC miss percentage +.It Sy mread +Metadata accesses per second +.It Sy pread +Prefetch accesses per second +.It Sy pdread +Prefetch data accesses per second +.It Sy pmread +Prefetch metadata accesses per second +.It Sy l2hit% +L2ARC access hit percentage +.It Sy l2hits +L2ARC hits per second +.It Sy l2miss +L2ARC misses per second +.It Sy l2read +Total L2ARC accesses per second +.It Sy l2pref +L2ARC prefetch allocated size per second +.It Sy l2pref% +L2ARC prefetch allocated size percentage +.It Sy l2mfu +L2ARC MFU allocated size per second +.It Sy l2mfu% +L2ARC MFU allocated size percentage +.It Sy l2mru +L2ARC MRU allocated size per second +.It Sy l2mru% +L2ARC MRU allocated size percentage +.It Sy l2data +L2ARC data (buf content) allocated size per second +.It Sy l2data% +L2ARC data (buf content) allocated size percentage +.It Sy l2meta +L2ARC metadata (buf content) allocated size per second +.It Sy l2meta% +L2ARC metadata (buf content) allocated size percentage +.It Sy l2size +Size of the L2ARC +.It Sy mtxmis +mutex_miss per second +.It Sy l2bytes +Bytes read per second from the L2ARC +.It Sy l2wbytes +Bytes written per second to the L2ARC +.It Sy l2miss% +L2ARC access miss percentage +.It Sy l2asize +Actual (compressed) size of the L2ARC +.It Sy cmpsz +Compressed size +.It Sy cmpsz% +Compressed size percentage +.It Sy ovhsz +Overhead size +.It Sy ovhsz% +Overhead size percentage +.It Sy bonsz +Bonus size +.It Sy bonsz% +Bonus size percentage +.It Sy dnosz +Dnode size +.It Sy dnosz% +Dnode size percentage +.It Sy dbusz +Dbuf size +.It Sy dbusz% +Dbuf size percentage +.It Sy hdrsz +Header size +.It Sy hdrsz% +Header size percentage +.It Sy l2hsz +L2 header size +.It Sy l2hsz% +L2 header size percentage +.It Sy abdsz +ABD chunk waste size +.It Sy abdsz% +ABD chunk waste size percentage +.It Sy datatg +ARC data target +.It Sy datatg% +ARC data target percentage +.It Sy datasz +ARC data size +.It Sy datasz% +ARC data size percentage +.It Sy metatg +ARC metadata target +.It Sy metatg% +ARC metadata target percentage +.It Sy metasz +ARC metadata size +.It Sy metasz% +ARC metadata size percentage +.It Sy anosz +Anonymous size +.It Sy anosz% +Anonymous size percentage +.It Sy anoda +Anonymous data size +.It Sy anoda% +Anonymous data size percentage +.It Sy anome +Anonymous metadata size +.It Sy anome% +Anonymous metadata size percentage +.It Sy anoed +Anonymous evictable data size +.It Sy anoed% +Anonymous evictable data size percentage +.It Sy anoem +Anonymous evictable metadata size +.It Sy anoem% +Anonymous evictable metadata size percentage +.It Sy mfutg +MFU target +.It Sy mfutg% +MFU target percentage +.It Sy mfudt +MFU data target +.It Sy mfudt% +MFU data target percentage +.It Sy mfumt +MFU metadata target +.It Sy mfumt% +MFU metadata target percentage +.It Sy mfusz +MFU size +.It Sy mfusz% +MFU size percentage +.It Sy mfuda +MFU data size +.It Sy mfuda% +MFU data size percentage +.It Sy mfume +MFU metadata size +.It Sy mfume% +MFU metadata size percentage +.It Sy mfued +MFU evictable data size +.It Sy mfued% +MFU evictable data size percentage +.It Sy mfuem +MFU evictable metadata size +.It Sy mfuem% +MFU evictable metadata size percentage +.It Sy mfugsz +MFU ghost size +.It Sy mfugd +MFU ghost data size +.It Sy mfugm +MFU ghost metadata size +.It Sy mrutg +MRU target +.It Sy mrutg% +MRU target percentage +.It Sy mrudt +MRU data target +.It Sy mrudt% +MRU data target percentage +.It Sy mrumt +MRU metadata target +.It Sy mrumt% +MRU metadata target percentage +.It Sy mrusz +MRU size +.It Sy mrusz% +MRU size percentage +.It Sy mruda +MRU data size +.It Sy mruda% +MRU data size percentage +.It Sy mrume +MRU metadata size +.It Sy mrume% +MRU metadata size percentage +.It Sy mrued +MRU evictable data size +.It Sy mrued% +MRU evictable data size percentage +.It Sy mruem +MRU evictable metadata size +.It Sy mruem% +MRU evictable metadata size percentage +.It Sy mrugsz +MRU ghost size +.It Sy mrugd +MRU ghost data size +.It Sy mrugm +MRU ghost metadata size +.It Sy uncsz +Uncached size +.It Sy uncsz% +Uncached size percentage +.It Sy uncda +Uncached data size +.It Sy uncda% +Uncached data size percentage +.It Sy uncme +Uncached metadata size +.It Sy uncme% +Uncached metadata size percentage +.It Sy unced +Uncached evictable data size +.It Sy unced% +Uncached evictable data size percentage +.It Sy uncem +Uncached evictable metadata size +.It Sy uncem% +Uncached evictable metadata size percentage +.It Sy grow +ARC grow disabled +.It Sy need +ARC reclaim needed +.It Sy free +The ARC's idea of how much free memory there is, which includes evictable memory +in the page cache. +Since the ARC tries to keep +.Sy avail +above zero, +.Sy avail +is usually more instructive to observe than +.Sy free . +.It Sy avail +The ARC's idea of how much free memory is available to it, which is a bit less +than +.Sy free . +May temporarily be negative, in which case the ARC will reduce the target size +.Sy c . +.El +. +.Sh OPTIONS +.Bl -tag -width "-v" +.It Fl a +Print all possible stats. +.It Fl f +Display only specific fields. +See +.Sx DESCRIPTION +for supported statistics. +.It Fl h +Display help message. +.It Fl o +Report statistics to a file instead of the standard output. +.It Fl p +Disable auto-scaling of numerical fields (for raw, machine-parsable values). +.It Fl s +Display data with a specified separator (default: 2 spaces). +.It Fl x +Print extended stats +.Pq same as Fl f Sy time , Ns Sy mfu , Ns Sy mru , Ns Sy mfug , Ns Sy mrug , Ns Sy eskip , Ns Sy mtxmis , Ns Sy dread , Ns Sy pread , Ns Sy read . +.It Fl v +Show field headers and definitions +.El +. +.Sh OPERANDS +The following operands are supported: +.Bl -tag -compact -offset Ds -width "interval" +.It Ar interval +Specify the sampling interval in seconds. +.It Ar count +Display only +.Ar count +reports. +.El diff --git a/sysutils/py-zfsstat/src/zarcstat.in b/sysutils/py-zfsstat/src/zarcstat.in new file mode 100644 index 000000000000..ad0e12e9fbf6 --- /dev/null +++ b/sysutils/py-zfsstat/src/zarcstat.in @@ -0,0 +1,805 @@ +#!/usr/bin/env @PYTHON_SHEBANG@ +# SPDX-License-Identifier: CDDL-1.0 +# +# Print out ZFS ARC Statistics exported via kstat(1) +# For a definition of fields, or usage, use zarcstat -v +# +# This script was originally a fork of the original arcstat.pl (0.1) +# by Neelakanth Nadgir, originally published on his Sun blog on +# 09/18/2007 +# http://blogs.sun.com/realneel/entry/zfs_arc_statistics +# +# A new version aimed to improve upon the original by adding features +# and fixing bugs as needed. This version was maintained by Mike +# Harsch and was hosted in a public open source repository: +# http://github.com/mharsch/arcstat +# +# but has since moved to the illumos-gate repository. +# +# This Python port was written by John Hixson for FreeNAS, introduced +# in commit e2c29f: +# https://github.com/freenas/freenas +# +# and has been improved by many people since. +# +# CDDL HEADER START +# +# The contents of this file are subject to the terms of the +# Common Development and Distribution License, Version 1.0 only +# (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 +# +# +# Fields have a fixed width. Every interval, we fill the "v" +# hash with its corresponding value (v[field]=value) using calculate(). +# @hdr is the array of fields that needs to be printed, so we +# just iterate over this array and print the values using our pretty printer. +# +# This script must remain compatible with Python 3.6+. +# + +import sys +import time +import getopt +import re +import copy +import os + +from signal import signal, SIGINT, SIGWINCH, SIG_DFL + + +cols = { + # HDR: [Size, Scale, Description] + "time": [8, -1, "Time"], + "hits": [4, 1000, "ARC hits per second"], + "iohs": [4, 1000, "ARC I/O hits per second"], + "miss": [4, 1000, "ARC misses per second"], + "read": [4, 1000, "Total ARC accesses per second"], + "hit%": [4, 100, "ARC hit percentage"], + "ioh%": [4, 100, "ARC I/O hit percentage"], + "miss%": [5, 100, "ARC miss percentage"], + "dhit": [4, 1000, "Demand hits per second"], + "dioh": [4, 1000, "Demand I/O hits per second"], + "dmis": [4, 1000, "Demand misses per second"], + "dh%": [3, 100, "Demand hit percentage"], + "di%": [3, 100, "Demand I/O hit percentage"], + "dm%": [3, 100, "Demand miss percentage"], + "ddhit": [5, 1000, "Demand data hits per second"], + "ddioh": [5, 1000, "Demand data I/O hits per second"], + "ddmis": [5, 1000, "Demand data misses per second"], + "ddh%": [4, 100, "Demand data hit percentage"], + "ddi%": [4, 100, "Demand data I/O hit percentage"], + "ddm%": [4, 100, "Demand data miss percentage"], + "dmhit": [5, 1000, "Demand metadata hits per second"], + "dmioh": [5, 1000, "Demand metadata I/O hits per second"], + "dmmis": [5, 1000, "Demand metadata misses per second"], + "dmh%": [4, 100, "Demand metadata hit percentage"], + "dmi%": [4, 100, "Demand metadata I/O hit percentage"], + "dmm%": [4, 100, "Demand metadata miss percentage"], + "phit": [4, 1000, "Prefetch hits per second"], + "pioh": [4, 1000, "Prefetch I/O hits per second"], + "pmis": [4, 1000, "Prefetch misses per second"], + "ph%": [3, 100, "Prefetch hits percentage"], + "pi%": [3, 100, "Prefetch I/O hits percentage"], + "pm%": [3, 100, "Prefetch miss percentage"], + "pdhit": [5, 1000, "Prefetch data hits per second"], + "pdioh": [5, 1000, "Prefetch data I/O hits per second"], + "pdmis": [5, 1000, "Prefetch data misses per second"], + "pdh%": [4, 100, "Prefetch data hits percentage"], + "pdi%": [4, 100, "Prefetch data I/O hits percentage"], + "pdm%": [4, 100, "Prefetch data miss percentage"], + "pmhit": [5, 1000, "Prefetch metadata hits per second"], + "pmioh": [5, 1000, "Prefetch metadata I/O hits per second"], + "pmmis": [5, 1000, "Prefetch metadata misses per second"], + "pmh%": [4, 100, "Prefetch metadata hits percentage"], + "pmi%": [4, 100, "Prefetch metadata I/O hits percentage"], + "pmm%": [4, 100, "Prefetch metadata miss percentage"], + "mhit": [4, 1000, "Metadata hits per second"], + "mioh": [4, 1000, "Metadata I/O hits per second"], + "mmis": [4, 1000, "Metadata misses per second"], + "mread": [5, 1000, "Metadata accesses per second"], + "mh%": [3, 100, "Metadata hit percentage"], + "mi%": [3, 100, "Metadata I/O hit percentage"], + "mm%": [3, 100, "Metadata miss percentage"], + "arcsz": [5, 1024, "ARC size"], + "size": [5, 1024, "ARC size"], + "c": [5, 1024, "ARC target size"], + "mfu": [4, 1000, "MFU list hits per second"], + "mru": [4, 1000, "MRU list hits per second"], + "mfug": [4, 1000, "MFU ghost list hits per second"], + "mrug": [4, 1000, "MRU ghost list hits per second"], + "unc": [4, 1000, "Uncached list hits per second"], + "eskip": [5, 1000, "evict_skip per second"], + "el2skip": [7, 1000, "evict skip, due to l2 writes, per second"], + "el2cach": [7, 1024, "Size of L2 cached evictions per second"], + "el2el": [5, 1024, "Size of L2 eligible evictions per second"], + "el2mfu": [6, 1024, "Size of L2 eligible MFU evictions per second"], + "el2mru": [6, 1024, "Size of L2 eligible MRU evictions per second"], + "el2inel": [7, 1024, "Size of L2 ineligible evictions per second"], + "mtxmis": [6, 1000, "mutex_miss per second"], + "dread": [5, 1000, "Demand accesses per second"], + "ddread": [6, 1000, "Demand data accesses per second"], + "dmread": [6, 1000, "Demand metadata accesses per second"], + "pread": [5, 1000, "Prefetch accesses per second"], + "pdread": [6, 1000, "Prefetch data accesses per second"], + "pmread": [6, 1000, "Prefetch metadata accesses per second"], + "l2hits": [6, 1000, "L2ARC hits per second"], + "l2miss": [6, 1000, "L2ARC misses per second"], + "l2read": [6, 1000, "Total L2ARC accesses per second"], + "l2hit%": [6, 100, "L2ARC access hit percentage"], + "l2miss%": [7, 100, "L2ARC access miss percentage"], + "l2pref": [6, 1024, "L2ARC prefetch allocated size"], + "l2mfu": [5, 1024, "L2ARC MFU allocated size"], + "l2mru": [5, 1024, "L2ARC MRU allocated size"], + "l2data": [6, 1024, "L2ARC data allocated size"], + "l2meta": [6, 1024, "L2ARC metadata allocated size"], + "l2pref%": [7, 100, "L2ARC prefetch percentage"], + "l2mfu%": [6, 100, "L2ARC MFU percentage"], + "l2mru%": [6, 100, "L2ARC MRU percentage"], + "l2data%": [7, 100, "L2ARC data percentage"], + "l2meta%": [7, 100, "L2ARC metadata percentage"], + "l2asize": [7, 1024, "Actual (compressed) size of the L2ARC"], + "l2size": [6, 1024, "Size of the L2ARC"], + "l2bytes": [7, 1024, "Bytes read per second from the L2ARC"], + "l2wbytes": [8, 1024, "Bytes written per second to the L2ARC"], + "grow": [4, 1000, "ARC grow disabled"], + "need": [5, 1024, "ARC reclaim need"], + "free": [5, 1024, "ARC free memory"], + "avail": [5, 1024, "ARC available memory"], + "waste": [5, 1024, "Wasted memory due to round up to pagesize"], + "ztotal": [6, 1000, "zfetch total prefetcher calls per second"], + "zhits": [5, 1000, "zfetch stream hits per second"], + "zahead": [6, 1000, "zfetch hits ahead of streams per second"], + "zpast": [5, 1000, "zfetch hits behind streams per second"], + "zmisses": [7, 1000, "zfetch stream misses per second"], + "zmax": [4, 1000, "zfetch limit reached per second"], + "zfuture": [7, 1000, "zfetch stream future per second"], + "zstride": [7, 1000, "zfetch stream strides per second"], + "zissued": [7, 1000, "zfetch prefetches issued per second"], + "zactive": [7, 1000, "zfetch prefetches active per second"], +} + +# ARC structural breakdown from zarcsummary +structfields = { + "cmp": ["compressed", "Compressed"], + "ovh": ["overhead", "Overhead"], + "bon": ["bonus", "Bonus"], + "dno": ["dnode", "Dnode"], + "dbu": ["dbuf", "Dbuf"], + "hdr": ["hdr", "Header"], + "l2h": ["l2_hdr", "L2 header"], + "abd": ["abd_chunk_waste", "ABD chunk waste"], +} +structstats = { # size stats + "percent": "size", # percentage of this value + "sz": ["_size", "size"], +} + +# ARC types breakdown from zarcsummary +typefields = { + "data": ["data", "ARC data"], + "meta": ["metadata", "ARC metadata"], +} +typestats = { # size stats + "percent": "cachessz", # percentage of this value + "tg": ["_target", "target"], + "sz": ["_size", "size"], +} + +# ARC states breakdown from zarcsummary +statefields = { + "ano": ["anon", "Anonymous"], + "mfu": ["mfu", "MFU"], + "mru": ["mru", "MRU"], + "unc": ["uncached", "Uncached"], +} +targetstats = { + "percent": "cachessz", # percentage of this value + "fields": ["mfu", "mru"], # only applicable to these fields + "tg": ["_target", "target"], + "dt": ["_data_target", "data target"], + "mt": ["_metadata_target", "metadata target"], +} +statestats = { # size stats + "percent": "cachessz", # percentage of this value + "sz": ["_size", "size"], + "da": ["_data", "data size"], + "me": ["_metadata", "metadata size"], + "ed": ["_evictable_data", "evictable data size"], + "em": ["_evictable_metadata", "evictable metadata size"], +} +ghoststats = { + "fields": ["mfu", "mru"], # only applicable to these fields + "gsz": ["_ghost_size", "ghost size"], + "gd": ["_ghost_data", "ghost data size"], + "gm": ["_ghost_metadata", "ghost metadata size"], +} + +# fields and stats +fieldstats = [ + [structfields, structstats], + [typefields, typestats], + [statefields, targetstats, statestats, ghoststats], +] +for fs in fieldstats: + fields, stats = fs[0], fs[1:] + for field, fieldval in fields.items(): + for group in stats: + for stat, statval in group.items(): + if stat in ["fields", "percent"] or \ + ("fields" in group and field not in group["fields"]): + continue + colname = field + stat + coldesc = fieldval[1] + " " + statval[1] + cols[colname] = [len(colname), 1024, coldesc] + if "percent" in group: + cols[colname + "%"] = [len(colname) + 1, 100, \ + coldesc + " percentage"] + +v = {} +hdr = ["time", "read", "ddread", "ddh%", "dmread", "dmh%", "pread", "ph%", + "size", "c", "avail"] +xhdr = ["time", "mfu", "mru", "mfug", "mrug", "unc", "eskip", "mtxmis", + "dread", "pread", "read"] +zhdr = ["time", "ztotal", "zhits", "zahead", "zpast", "zmisses", "zmax", + "zfuture", "zstride", "zissued", "zactive"] +sint = 1 # Default interval is 1 second +count = 1 # Default count is 1 +hdr_intr = 20 # Print header every 20 lines of output +opfile = None +sep = " " # Default separator is 2 spaces +l2exist = False +cmd = ("Usage: zarcstat [-havxp] [-f fields] [-o file] [-s string] [interval " + "[count]]\n") +cur = {} +d = {} +out = None +kstat = None +pretty_print = True + + +if sys.platform.startswith('freebsd'): + # Requires py-sysctl on FreeBSD + import sysctl + + def kstat_update(): + global kstat + + k = [ctl for ctl in sysctl.filter('kstat.zfs.misc.arcstats') + if ctl.type != sysctl.CTLTYPE_NODE] + k += [ctl for ctl in sysctl.filter('kstat.zfs.misc.zfetchstats') + if ctl.type != sysctl.CTLTYPE_NODE] + + if not k: + sys.exit(1) + + kstat = {} + + for s in k: + if not s: + continue + + name, value = s.name, s.value + + if "arcstats" in name: + # Trims 'kstat.zfs.misc.arcstats' from the name + kstat[name[24:]] = int(value) + else: + kstat["zfetch_" + name[27:]] = int(value) + +elif sys.platform.startswith('linux'): + def kstat_update(): + global kstat + + k1 = [line.strip() for line in open('/proc/spl/kstat/zfs/arcstats')] + + k2 = ["zfetch_" + line.strip() for line in + open('/proc/spl/kstat/zfs/zfetchstats')] + + if k1 is None or k2 is None: + sys.exit(1) + + del k1[0:2] + del k2[0:2] + k = k1 + k2 + kstat = {} + + for s in k: + if not s: + continue + + name, unused, value = s.split() + kstat[name] = int(value) + + +def detailed_usage(): + sys.stderr.write("%s\n" % cmd) + sys.stderr.write("Field definitions are as follows:\n") + for key in cols: + sys.stderr.write("%11s : %s\n" % (key, cols[key][2])) + sys.stderr.write("\n") + + sys.exit(0) + + +def usage(): + sys.stderr.write("%s\n" % cmd) + sys.stderr.write("\t -h : Print this help message\n") + sys.stderr.write("\t -a : Print all possible stats\n") + sys.stderr.write("\t -v : List all possible field headers and definitions" + "\n") + sys.stderr.write("\t -x : Print extended stats\n") + sys.stderr.write("\t -z : Print zfetch stats\n") + sys.stderr.write("\t -f : Specify specific fields to print (see -v)\n") + sys.stderr.write("\t -o : Redirect output to the specified file\n") + sys.stderr.write("\t -s : Override default field separator with custom " + "character or string\n") + sys.stderr.write("\t -p : Disable auto-scaling of numerical fields\n") + sys.stderr.write("\nExamples:\n") + sys.stderr.write("\tzarcstat -o /tmp/a.log 2 10\n") + sys.stderr.write("\tzarcstat -s \",\" -o /tmp/a.log 2 10\n") + sys.stderr.write("\tzarcstat -v\n") + sys.stderr.write("\tzarcstat -f time,hit%,dh%,ph%,mh% 1\n") + sys.stderr.write("\n") + + sys.exit(1) + + +def snap_stats(): + global cur + global kstat + + prev = copy.deepcopy(cur) + kstat_update() + + cur = kstat + + # fill in additional values from zarcsummary + cur["caches_size"] = caches_size = cur["anon_data"]+cur["anon_metadata"]+\ + cur["mfu_data"]+cur["mfu_metadata"]+cur["mru_data"]+cur["mru_metadata"]+\ + cur["uncached_data"]+cur["uncached_metadata"] + s = 4294967296 + pd = cur["pd"] + pm = cur["pm"] + meta = cur["meta"] + v = (s-int(pd))*(s-int(meta))/s + cur["mfu_data_target"] = v / 65536 * caches_size / 65536 + v = (s-int(pm))*int(meta)/s + cur["mfu_metadata_target"] = v / 65536 * caches_size / 65536 + v = int(pd)*(s-int(meta))/s + cur["mru_data_target"] = v / 65536 * caches_size / 65536 + v = int(pm)*int(meta)/s + cur["mru_metadata_target"] = v / 65536 * caches_size / 65536 + + cur["data_target"] = cur["mfu_data_target"] + cur["mru_data_target"] + cur["metadata_target"] = cur["mfu_metadata_target"] + cur["mru_metadata_target"] + cur["mfu_target"] = cur["mfu_data_target"] + cur["mfu_metadata_target"] + cur["mru_target"] = cur["mru_data_target"] + cur["mru_metadata_target"] + + for key in cur: + if re.match(key, "class"): + continue + if key in prev: + d[key] = cur[key] - prev[key] + else: + d[key] = cur[key] + + +def isint(num): + if isinstance(num, float): + return num.is_integer() + if isinstance(num, int): + return True + return False + + +def prettynum(sz, scale, num=0): + suffix = ['', 'K', 'M', 'G', 'T', 'P', 'E', 'Z'] + index = 0 + + # Special case for date field + if scale == -1: + return "%s" % num + + if scale != 100: + while abs(num) > scale and index < 5: + num = num / scale + index += 1 + + width = sz - (0 if index == 0 else 1) + intlen = len("%.0f" % num) # %.0f rounds to nearest int + if sint == 1 and isint(num) or width < intlen + 2: + decimal = 0 + else: + decimal = 1 + return "%*.*f%s" % (width, decimal, num, suffix[index]) + + +def print_values(): + global hdr + global sep + global v + global pretty_print + + if pretty_print: + fmt = lambda col: prettynum(cols[col][0], cols[col][1], v[col]) + else: + fmt = lambda col: str(v[col]) + + sys.stdout.write(sep.join(fmt(col) for col in hdr)) + sys.stdout.write("\n") + sys.stdout.flush() + + +def print_header(): + global hdr + global sep + global pretty_print + + if pretty_print: + fmt = lambda col: "%*s" % (cols[col][0], col) + else: + fmt = lambda col: col + + sys.stdout.write(sep.join(fmt(col) for col in hdr)) + sys.stdout.write("\n") + + +def get_terminal_lines(): + try: + import fcntl + import termios + import struct + data = fcntl.ioctl(sys.stdout.fileno(), termios.TIOCGWINSZ, '1234') + sz = struct.unpack('hh', data) + return sz[0] + except Exception: + pass + + +def update_hdr_intr(): + global hdr_intr + + lines = get_terminal_lines() + if lines and lines > 3: + hdr_intr = lines - 3 + + +def resize_handler(signum, frame): + update_hdr_intr() + + +def init(): + global sint + global count + global hdr + global xhdr + global zhdr + global opfile + global sep + global out + global l2exist + global pretty_print + + desired_cols = None + aflag = False + xflag = False + hflag = False + vflag = False + zflag = False + i = 1 + + try: + opts, args = getopt.getopt( + sys.argv[1:], + "axzo:hvs:f:p", + [ + "all", + "extended", + "zfetch", + "outfile", + "help", + "verbose", + "separator", + "columns", + "parsable" + ] + ) + except getopt.error as msg: + sys.stderr.write("Error: %s\n" % str(msg)) + usage() + opts = None + + for opt, arg in opts: + if opt in ('-a', '--all'): + aflag = True + if opt in ('-x', '--extended'): + xflag = True + if opt in ('-o', '--outfile'): + opfile = arg + i += 1 + if opt in ('-h', '--help'): + hflag = True + if opt in ('-v', '--verbose'): + vflag = True + if opt in ('-s', '--separator'): + sep = arg + i += 1 + if opt in ('-f', '--columns'): + desired_cols = arg + i += 1 + if opt in ('-p', '--parsable'): + pretty_print = False + if opt in ('-z', '--zfetch'): + zflag = True + i += 1 + + argv = sys.argv[i:] + sint = int(argv[0]) if argv else sint + count = int(argv[1]) if len(argv) > 1 else (0 if len(argv) > 0 else 1) + + if hflag or (xflag and zflag) or ((zflag or xflag) and desired_cols): + usage() + + if vflag: + detailed_usage() + + if xflag: + hdr = xhdr + + if zflag: + hdr = zhdr + + update_hdr_intr() + + # check if L2ARC exists; fall back to l2_size for older kernels that + # do not export l2_ndev + snap_stats() + if cur.get("l2_ndev") or cur.get("l2_size"): + l2exist = True + + if desired_cols: + hdr = desired_cols.split(",") + + invalid = [] + incompat = [] + for ele in hdr: + if ele not in cols: + invalid.append(ele) + elif not l2exist and ele.startswith("l2"): + sys.stdout.write("No L2ARC Here\n%s\n" % ele) + incompat.append(ele) + + if len(invalid) > 0: + sys.stderr.write("Invalid column definition! -- %s\n" % invalid) + usage() + + if len(incompat) > 0: + sys.stderr.write("Incompatible field specified! -- %s\n" % + incompat) + usage() + + if aflag: + if l2exist: + hdr = cols.keys() + else: + hdr = [col for col in cols.keys() if not col.startswith("l2")] + + if opfile: + try: + out = open(opfile, "w") + sys.stdout = out + + except IOError: + sys.stderr.write("Cannot open %s for writing\n" % opfile) + sys.exit(1) + + +def calculate(): + global d + global v + global l2exist + + v = dict() + v["time"] = time.strftime("%H:%M:%S", time.localtime()) + v["hits"] = d["hits"] / sint + v["iohs"] = d["iohits"] / sint + v["miss"] = d["misses"] / sint + v["read"] = v["hits"] + v["iohs"] + v["miss"] + v["hit%"] = 100 * v["hits"] / v["read"] if v["read"] > 0 else 0 + v["ioh%"] = 100 * v["iohs"] / v["read"] if v["read"] > 0 else 0 + v["miss%"] = 100 - v["hit%"] - v["ioh%"] if v["read"] > 0 else 0 + + v["dhit"] = (d["demand_data_hits"] + d["demand_metadata_hits"]) / sint + v["dioh"] = (d["demand_data_iohits"] + d["demand_metadata_iohits"]) / sint + v["dmis"] = (d["demand_data_misses"] + d["demand_metadata_misses"]) / sint + + v["dread"] = v["dhit"] + v["dioh"] + v["dmis"] + v["dh%"] = 100 * v["dhit"] / v["dread"] if v["dread"] > 0 else 0 + v["di%"] = 100 * v["dioh"] / v["dread"] if v["dread"] > 0 else 0 + v["dm%"] = 100 - v["dh%"] - v["di%"] if v["dread"] > 0 else 0 + + v["ddhit"] = d["demand_data_hits"] / sint + v["ddioh"] = d["demand_data_iohits"] / sint + v["ddmis"] = d["demand_data_misses"] / sint + + v["ddread"] = v["ddhit"] + v["ddioh"] + v["ddmis"] + v["ddh%"] = 100 * v["ddhit"] / v["ddread"] if v["ddread"] > 0 else 0 + v["ddi%"] = 100 * v["ddioh"] / v["ddread"] if v["ddread"] > 0 else 0 + v["ddm%"] = 100 - v["ddh%"] - v["ddi%"] if v["ddread"] > 0 else 0 + + v["dmhit"] = d["demand_metadata_hits"] / sint + v["dmioh"] = d["demand_metadata_iohits"] / sint + v["dmmis"] = d["demand_metadata_misses"] / sint + + v["dmread"] = v["dmhit"] + v["dmioh"] + v["dmmis"] + v["dmh%"] = 100 * v["dmhit"] / v["dmread"] if v["dmread"] > 0 else 0 + v["dmi%"] = 100 * v["dmioh"] / v["dmread"] if v["dmread"] > 0 else 0 + v["dmm%"] = 100 - v["dmh%"] - v["dmi%"] if v["dmread"] > 0 else 0 + + v["phit"] = (d["prefetch_data_hits"] + d["prefetch_metadata_hits"]) / sint + v["pioh"] = (d["prefetch_data_iohits"] + + d["prefetch_metadata_iohits"]) / sint + v["pmis"] = (d["prefetch_data_misses"] + + d["prefetch_metadata_misses"]) / sint + + v["pread"] = v["phit"] + v["pioh"] + v["pmis"] + v["ph%"] = 100 * v["phit"] / v["pread"] if v["pread"] > 0 else 0 + v["pi%"] = 100 * v["pioh"] / v["pread"] if v["pread"] > 0 else 0 + v["pm%"] = 100 - v["ph%"] - v["pi%"] if v["pread"] > 0 else 0 + + v["pdhit"] = d["prefetch_data_hits"] / sint + v["pdioh"] = d["prefetch_data_iohits"] / sint + v["pdmis"] = d["prefetch_data_misses"] / sint + + v["pdread"] = v["pdhit"] + v["pdioh"] + v["pdmis"] + v["pdh%"] = 100 * v["pdhit"] / v["pdread"] if v["pdread"] > 0 else 0 + v["pdi%"] = 100 * v["pdioh"] / v["pdread"] if v["pdread"] > 0 else 0 + v["pdm%"] = 100 - v["pdh%"] - v["pdi%"] if v["pdread"] > 0 else 0 + + v["pmhit"] = d["prefetch_metadata_hits"] / sint + v["pmioh"] = d["prefetch_metadata_iohits"] / sint + v["pmmis"] = d["prefetch_metadata_misses"] / sint + + v["pmread"] = v["pmhit"] + v["pmioh"] + v["pmmis"] + v["pmh%"] = 100 * v["pmhit"] / v["pmread"] if v["pmread"] > 0 else 0 + v["pmi%"] = 100 * v["pmioh"] / v["pmread"] if v["pmread"] > 0 else 0 + v["pmm%"] = 100 - v["pmh%"] - v["pmi%"] if v["pmread"] > 0 else 0 + + v["mhit"] = (d["prefetch_metadata_hits"] + + d["demand_metadata_hits"]) / sint + v["mioh"] = (d["prefetch_metadata_iohits"] + + d["demand_metadata_iohits"]) / sint + v["mmis"] = (d["prefetch_metadata_misses"] + + d["demand_metadata_misses"]) / sint + + v["mread"] = v["mhit"] + v["mioh"] + v["mmis"] + v["mh%"] = 100 * v["mhit"] / v["mread"] if v["mread"] > 0 else 0 + v["mi%"] = 100 * v["mioh"] / v["mread"] if v["mread"] > 0 else 0 + v["mm%"] = 100 - v["mh%"] - v["mi%"] if v["mread"] > 0 else 0 + + v["arcsz"] = cur["size"] + v["size"] = cur["size"] + v["c"] = cur["c"] + v["mfu"] = d["mfu_hits"] / sint + v["mru"] = d["mru_hits"] / sint + v["mrug"] = d["mru_ghost_hits"] / sint + v["mfug"] = d["mfu_ghost_hits"] / sint + v["unc"] = d["uncached_hits"] / sint + v["eskip"] = d["evict_skip"] / sint + v["el2skip"] = d["evict_l2_skip"] / sint + v["el2cach"] = d["evict_l2_cached"] / sint + v["el2el"] = d["evict_l2_eligible"] / sint + v["el2mfu"] = d["evict_l2_eligible_mfu"] / sint + v["el2mru"] = d["evict_l2_eligible_mru"] / sint + v["el2inel"] = d["evict_l2_ineligible"] / sint + v["mtxmis"] = d["mutex_miss"] / sint + v["ztotal"] = (d["zfetch_hits"] + d["zfetch_future"] + d["zfetch_stride"] + + d["zfetch_past"] + d["zfetch_misses"]) / sint + v["zhits"] = d["zfetch_hits"] / sint + v["zahead"] = (d["zfetch_future"] + d["zfetch_stride"]) / sint + v["zpast"] = d["zfetch_past"] / sint + v["zmisses"] = d["zfetch_misses"] / sint + v["zmax"] = d["zfetch_max_streams"] / sint + v["zfuture"] = d["zfetch_future"] / sint + v["zstride"] = d["zfetch_stride"] / sint + v["zissued"] = d["zfetch_io_issued"] / sint + v["zactive"] = d["zfetch_io_active"] / sint + + # ARC structural breakdown, ARC types breakdown, ARC states breakdown + v["cachessz"] = cur["caches_size"] + for fs in fieldstats: + fields, stats = fs[0], fs[1:] + for field, fieldval in fields.items(): + for group in stats: + for stat, statval in group.items(): + if stat in ["fields", "percent"] or \ + ("fields" in group and field not in group["fields"]): + continue + colname = field + stat + v[colname] = cur[fieldval[0] + statval[0]] + if "percent" in group: + v[colname + "%"] = 100 * v[colname] / \ + v[group["percent"]] if v[group["percent"]] > 0 else 0 + + if l2exist: + l2asize = cur["l2_asize"] + v["l2hits"] = d["l2_hits"] / sint + v["l2miss"] = d["l2_misses"] / sint + v["l2read"] = v["l2hits"] + v["l2miss"] + v["l2hit%"] = 100 * v["l2hits"] / v["l2read"] if v["l2read"] > 0 else 0 + + v["l2miss%"] = 100 - v["l2hit%"] if v["l2read"] > 0 else 0 + v["l2asize"] = l2asize + v["l2size"] = cur["l2_size"] + v["l2bytes"] = d["l2_read_bytes"] / sint + v["l2wbytes"] = d["l2_write_bytes"] / sint + + v["l2pref"] = cur["l2_prefetch_asize"] + v["l2mfu"] = cur["l2_mfu_asize"] + v["l2mru"] = cur["l2_mru_asize"] + v["l2data"] = cur["l2_bufc_data_asize"] + v["l2meta"] = cur["l2_bufc_metadata_asize"] + v["l2pref%"] = 100 * v["l2pref"] / l2asize if l2asize > 0 else 0 + v["l2mfu%"] = 100 * v["l2mfu"] / l2asize if l2asize > 0 else 0 + v["l2mru%"] = 100 * v["l2mru"] / l2asize if l2asize > 0 else 0 + v["l2data%"] = 100 * v["l2data"] / l2asize if l2asize > 0 else 0 + v["l2meta%"] = 100 * v["l2meta"] / l2asize if l2asize > 0 else 0 + + v["grow"] = 0 if cur["arc_no_grow"] else 1 + v["need"] = cur["arc_need_free"] + v["free"] = cur["memory_free_bytes"] + v["avail"] = cur["memory_available_bytes"] + v["waste"] = cur["abd_chunk_waste_size"] + + +def main(): + + global sint + global count + global hdr_intr + + i = 0 + count_flag = 0 + + init() + if count > 0: + count_flag = 1 + + signal(SIGINT, SIG_DFL) + signal(SIGWINCH, resize_handler) + while True: + if i == 0: + print_header() + + snap_stats() + calculate() + print_values() + + if count_flag == 1: + if count <= 1: + break + count -= 1 + + i = 0 if i >= hdr_intr else i + 1 + time.sleep(sint) + + if out: + out.close() + + +if __name__ == '__main__': + main() diff --git a/sysutils/py-zfsstat/src/zarcsummary b/sysutils/py-zfsstat/src/zarcsummary new file mode 100644 index 000000000000..5b6e35465ea1 --- /dev/null +++ b/sysutils/py-zfsstat/src/zarcsummary @@ -0,0 +1,1076 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: BSD-2-Clause +# +# Copyright (c) 2008 Ben Rockwood <benr@cuddletech.com>, +# Copyright (c) 2010 Martin Matuska <mm@FreeBSD.org>, +# Copyright (c) 2010-2011 Jason J. Hellenthal <jhell@DataIX.net>, +# Copyright (c) 2017 Scot W. Stevenson <scot.stevenson@gmail.com> +# All rights reserved. +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions +# are met: +# +# 1. Redistributions of source code must retain the above copyright +# notice, this list of conditions and the following disclaimer. +# 2. Redistributions in binary form must reproduce the above copyright +# notice, this list of conditions and the following disclaimer in the +# documentation and/or other materials provided with the distribution. +# +# THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND +# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +# SUCH DAMAGE. +"""Print statistics on the ZFS ARC Cache and other information + +Provides basic information on the ARC, its efficiency, the L2ARC (if present), +the Data Management Unit (DMU), Virtual Devices (VDEVs), and tunables. See +the in-source documentation and code at +https://github.com/openzfs/zfs/blob/master/module/zfs/arc.c for details. +The original introduction to zarcsummary can be found at +http://cuddletech.com/?p=454 +""" + +import argparse +import os +import subprocess +import sys +import time +import errno + +# We can't use env -S portably, and we need python3 -u to handle pipes in +# the shell abruptly closing the way we want to, so... +import io +if isinstance(sys.__stderr__.buffer, io.BufferedWriter): + os.execv(sys.executable, [sys.executable, "-u"] + sys.argv) + +DESCRIPTION = 'Print ARC and other statistics for OpenZFS' +INDENT = ' '*8 +LINE_LENGTH = 72 +DATE_FORMAT = '%a %b %d %H:%M:%S %Y' +TITLE = 'ZFS Subsystem Report' + +SECTIONS = 'arc archits dmu l2arc spl tunables vdev zil'.split() +SECTION_HELP = 'print info from one section ('+' '.join(SECTIONS)+')' + +# Tunables and SPL are handled separately because they come from +# different sources +SECTION_PATHS = {'arc': 'arcstats', + 'dmu': 'dmu_tx', + 'l2arc': 'arcstats', # L2ARC stuff lives in arcstats + 'zfetch': 'zfetchstats', + 'zil': 'zil'} + +parser = argparse.ArgumentParser(description=DESCRIPTION) +parser.add_argument('-a', '--alternate', action='store_true', default=False, + help='use alternate formatting for tunables and SPL', + dest='alt') +parser.add_argument('-d', '--description', action='store_true', default=False, + help='print descriptions with tunables and SPL', + dest='desc') +parser.add_argument('-g', '--graph', action='store_true', default=False, + help='print graph on ARC use and exit', dest='graph') +parser.add_argument('-p', '--page', type=int, dest='page', + help='print page by number (DEPRECATED, use "-s")') +parser.add_argument('-r', '--raw', action='store_true', default=False, + help='dump all available data with minimal formatting', + dest='raw') +parser.add_argument('-s', '--section', dest='section', help=SECTION_HELP) +ARGS = parser.parse_args() + + +if sys.platform.startswith('freebsd'): + # Requires py36-sysctl on FreeBSD + import sysctl + + def is_value(ctl): + return ctl.type != sysctl.CTLTYPE_NODE + + def namefmt(ctl, base='vfs.zfs.'): + # base is removed from the name + cut = len(base) + return ctl.name[cut:] + + def load_kstats(section): + base = 'kstat.zfs.misc.{section}.'.format(section=section) + fmt = lambda kstat: '{name} : {value}'.format(name=namefmt(kstat, base), + value=kstat.value) + kstats = sysctl.filter(base) + return [fmt(kstat) for kstat in kstats if is_value(kstat)] + + def get_params(base): + ctls = sysctl.filter(base) + return {namefmt(ctl): str(ctl.value) for ctl in ctls if is_value(ctl)} + + def get_tunable_params(): + return get_params('vfs.zfs') + + def get_vdev_params(): + return get_params('vfs.zfs.vdev') + + def get_version_impl(request): + # FreeBSD reports versions for zpl and spa instead of zfs and spl. + name = {'zfs': 'zpl', + 'spl': 'spa'}[request] + mib = 'vfs.zfs.version.{}'.format(name) + version = sysctl.filter(mib)[0].value + return '{} version {}'.format(name, version) + + def get_descriptions(_request): + ctls = sysctl.filter('vfs.zfs') + return {namefmt(ctl): ctl.description for ctl in ctls if is_value(ctl)} + + +elif sys.platform.startswith('linux'): + KSTAT_PATH = '/proc/spl/kstat/zfs' + SPL_PATH = '/sys/module/spl/parameters' + TUNABLES_PATH = '/sys/module/zfs/parameters' + + def load_kstats(section): + path = os.path.join(KSTAT_PATH, section) + with open(path) as f: + return list(f)[2:] # Get rid of header + + def get_params(basepath): + """Collect information on the Solaris Porting Layer (SPL) or the + tunables, depending on the PATH given. Does not check if PATH is + legal. + """ + result = {} + for name in os.listdir(basepath): + path = os.path.join(basepath, name) + with open(path) as f: + value = f.read() + result[name] = value.strip() + return result + + def get_spl_params(): + return get_params(SPL_PATH) + + def get_tunable_params(): + return get_params(TUNABLES_PATH) + + def get_vdev_params(): + return get_params(TUNABLES_PATH) + + def get_version_impl(request): + # The original zarcsummary called /sbin/modinfo/{spl,zfs} to get + # the version information. We switch to /sys/module/{spl,zfs}/version + # to make sure we get what is really loaded in the kernel + try: + with open("/sys/module/{}/version".format(request)) as f: + return f.read().strip() + except: + return "(unknown)" + + def get_descriptions(request): + """Get the descriptions of the Solaris Porting Layer (SPL) or the + tunables, return with minimal formatting. + """ + + if request not in ('spl', 'zfs'): + print('ERROR: description of "{0}" requested)'.format(request)) + sys.exit(1) + + descs = {} + target_prefix = 'parm:' + + # We would prefer to do this with /sys/modules -- see the discussion at + # get_version() -- but there isn't a way to get the descriptions from + # there, so we fall back on modinfo + command = ["/sbin/modinfo", request, "-0"] + + info = '' + + try: + + info = subprocess.run(command, stdout=subprocess.PIPE, + check=True, universal_newlines=True) + raw_output = info.stdout.split('\0') + + except subprocess.CalledProcessError: + print("Error: Descriptions not available", + "(can't access kernel module)") + sys.exit(1) + + for line in raw_output: + + if not line.startswith(target_prefix): + continue + + line = line[len(target_prefix):].strip() + name, raw_desc = line.split(':', 1) + desc = raw_desc.rsplit('(', 1)[0] + + if desc == '': + desc = '(No description found)' + + descs[name.strip()] = desc.strip() + + return descs + +def handle_unraisableException(exc_type, exc_value=None, exc_traceback=None, + err_msg=None, object=None): + handle_Exception(exc_type, object, exc_traceback) + +def handle_Exception(ex_cls, ex, tb): + if ex_cls is KeyboardInterrupt: + sys.exit() + + if ex_cls is BrokenPipeError: + # It turns out that while sys.exit() triggers an exception + # not handled message on Python 3.8+, os._exit() does not. + os._exit(0) + + if ex_cls is OSError: + if ex.errno == errno.ENOTCONN: + sys.exit() + + raise ex + +if hasattr(sys,'unraisablehook'): # Python 3.8+ + sys.unraisablehook = handle_unraisableException +sys.excepthook = handle_Exception + + +def cleanup_line(single_line): + """Format a raw line of data from /proc and isolate the name value + part, returning a tuple with each. Currently, this gets rid of the + middle '4'. For example "arc_no_grow 4 0" returns the tuple + ("arc_no_grow", "0"). + """ + name, _, value = single_line.split() + + return name, value + + +def draw_graph(kstats_dict): + """Draw a primitive graph representing the basic information on the + ARC -- its size and the proportion used by MFU and MRU -- and quit. + We use max size of the ARC to calculate how full it is. This is a + very rough representation. + """ + + arc_stats = isolate_section('arcstats', kstats_dict) + + GRAPH_INDENT = ' '*4 + GRAPH_WIDTH = 70 + arc_max = int(arc_stats['c_max']) + arc_size = f_bytes(arc_stats['size']) + arc_perc = f_perc(arc_stats['size'], arc_max) + data_size = f_bytes(arc_stats['data_size']) + meta_size = f_bytes(arc_stats['metadata_size']) + dnode_size = f_bytes(arc_stats['dnode_size']) + + info_form = ('ARC: {0} ({1}) Data: {2} Meta: {3} Dnode: {4}') + info_line = info_form.format(arc_size, arc_perc, data_size, meta_size, + dnode_size) + info_spc = ' '*int((GRAPH_WIDTH-len(info_line))/2) + info_line = GRAPH_INDENT+info_spc+info_line + + graph_line = GRAPH_INDENT+'+'+('-'*(GRAPH_WIDTH-2))+'+' + + arc_perc = float(int(arc_stats['size'])/arc_max) + data_perc = float(int(arc_stats['data_size'])/arc_max) + meta_perc = float(int(arc_stats['metadata_size'])/arc_max) + dnode_perc = float(int(arc_stats['dnode_size'])/arc_max) + total_ticks = float(arc_perc)*GRAPH_WIDTH + data_ticks = data_perc*GRAPH_WIDTH + meta_ticks = meta_perc*GRAPH_WIDTH + dnode_ticks = dnode_perc*GRAPH_WIDTH + other_ticks = total_ticks-(data_ticks+meta_ticks+dnode_ticks) + + core_form = 'D'*int(data_ticks)+'M'*int(meta_ticks)+'N'*int(dnode_ticks)+\ + 'O'*int(other_ticks) + core_spc = ' '*(GRAPH_WIDTH-(2+len(core_form))) + core_line = GRAPH_INDENT+'|'+core_form+core_spc+'|' + + for line in ('', info_line, graph_line, core_line, graph_line, ''): + print(line) + + +def f_bytes(byte_string): + """Return human-readable representation of a byte value in + powers of 2 (eg "KiB" for "kibibytes", etc) to two decimal + points. Values smaller than one KiB are returned without + decimal points. Note "bytes" is a reserved keyword. + """ + + prefixes = ([2**80, "YiB"], # yobibytes (yotta) + [2**70, "ZiB"], # zebibytes (zetta) + [2**60, "EiB"], # exbibytes (exa) + [2**50, "PiB"], # pebibytes (peta) + [2**40, "TiB"], # tebibytes (tera) + [2**30, "GiB"], # gibibytes (giga) + [2**20, "MiB"], # mebibytes (mega) + [2**10, "KiB"]) # kibibytes (kilo) + + bites = int(byte_string) + + if bites >= 2**10: + for limit, unit in prefixes: + + if bites >= limit: + value = bites / limit + break + + result = '{0:.1f} {1}'.format(value, unit) + else: + result = '{0} Bytes'.format(bites) + + return result + + +def f_hits(hits_string): + """Create a human-readable representation of the number of hits. + The single-letter symbols used are SI to avoid the confusion caused + by the different "short scale" and "long scale" representations in + English, which use the same words for different values. See + https://en.wikipedia.org/wiki/Names_of_large_numbers and: + https://physics.nist.gov/cuu/Units/prefixes.html + """ + + numbers = ([10**24, 'Y'], # yotta (septillion) + [10**21, 'Z'], # zetta (sextillion) + [10**18, 'E'], # exa (quintrillion) + [10**15, 'P'], # peta (quadrillion) + [10**12, 'T'], # tera (trillion) + [10**9, 'G'], # giga (billion) + [10**6, 'M'], # mega (million) + [10**3, 'k']) # kilo (thousand) + + hits = int(hits_string) + + if hits >= 1000: + for limit, symbol in numbers: + + if hits >= limit: + value = hits/limit + break + + result = "%0.1f%s" % (value, symbol) + else: + result = "%d" % hits + + return result + + +def f_perc(value1, value2): + """Calculate percentage and return in human-readable form. If + rounding produces the result '0.0' though the first number is + not zero, include a 'less-than' symbol to avoid confusion. + Division by zero is handled by returning 'n/a'; no error + is called. + """ + + v1 = float(value1) + v2 = float(value2) + + try: + perc = 100 * v1/v2 + except ZeroDivisionError: + result = 'n/a' + else: + result = '{0:0.1f} %'.format(perc) + + if result == '0.0 %' and v1 > 0: + result = '< 0.1 %' + + return result + + +def format_raw_line(name, value): + """For the --raw option for the tunable and SPL outputs, decide on the + correct formatting based on the --alternate flag. + """ + + if ARGS.alt: + result = '{0}{1}={2}'.format(INDENT, name, value) + else: + # Right-align the value within the line length if it fits, + # otherwise just separate it from the name by a single space. + fit = LINE_LENGTH - len(INDENT) - len(name) + overflow = len(value) + 1 + w = max(fit, overflow) + result = '{0}{1}{2:>{w}}'.format(INDENT, name, value, w=w) + + return result + + +def get_kstats(): + """Collect information on the ZFS subsystem. The step does not perform any + further processing, giving us the option to only work on what is actually + needed. The name "kstat" is a holdover from the Solaris utility of the same + name. + """ + + result = {} + + for section in SECTION_PATHS.values(): + if section not in result: + result[section] = load_kstats(section) + + return result + + +def get_version(request): + """Get the version number of ZFS or SPL on this machine for header. + Returns an error string, but does not raise an error, if we can't + get the ZFS/SPL version. + """ + + if request not in ('spl', 'zfs'): + error_msg = '(ERROR: "{0}" requested)'.format(request) + return error_msg + + return get_version_impl(request) + + +def print_header(): + """Print the initial heading with date and time as well as info on the + kernel and ZFS versions. This is not called for the graph. + """ + + # datetime is now recommended over time but we keep the exact formatting + # from the older version of zarcsummary in case there are scripts + # that expect it in this way + daydate = time.strftime(DATE_FORMAT) + spc_date = LINE_LENGTH-len(daydate) + sys_version = os.uname() + + sys_msg = sys_version.sysname+' '+sys_version.release + zfs = get_version('zfs') + spc_zfs = LINE_LENGTH-len(zfs) + + machine_msg = 'Machine: '+sys_version.nodename+' ('+sys_version.machine+')' + spl = get_version('spl') + spc_spl = LINE_LENGTH-len(spl) + + print('\n'+('-'*LINE_LENGTH)) + print('{0:<{spc}}{1}'.format(TITLE, daydate, spc=spc_date)) + print('{0:<{spc}}{1}'.format(sys_msg, zfs, spc=spc_zfs)) + print('{0:<{spc}}{1}\n'.format(machine_msg, spl, spc=spc_spl)) + + +def print_raw(kstats_dict): + """Print all available data from the system in a minimally sorted format. + This can be used as a source to be piped through 'grep'. + """ + + sections = sorted(kstats_dict.keys()) + + for section in sections: + + print('\n{0}:'.format(section.upper())) + lines = sorted(kstats_dict[section]) + + for line in lines: + name, value = cleanup_line(line) + print(format_raw_line(name, value)) + + # Tunables and SPL must be handled separately because they come from a + # different source and have descriptions the user might request + print() + section_spl() + section_tunables() + + +def isolate_section(section_name, kstats_dict): + """From the complete information on all sections, retrieve only those + for one section. + """ + + try: + section_data = kstats_dict[section_name] + except KeyError: + print('ERROR: Data on {0} not available'.format(section_data)) + sys.exit(1) + + section_dict = dict(cleanup_line(l) for l in section_data) + + return section_dict + + +# Formatted output helper functions + + +def prt_1(text, value): + """Print text and one value, no indent""" + spc = ' '*(LINE_LENGTH-(len(text)+len(value))) + print('{0}{spc}{1}'.format(text, value, spc=spc)) + + +def prt_i1(text, value): + """Print text and one value, with indent""" + spc = ' '*(LINE_LENGTH-(len(INDENT)+len(text)+len(value))) + print(INDENT+'{0}{spc}{1}'.format(text, value, spc=spc)) + + +def prt_2(text, value1, value2): + """Print text and two values, no indent""" + values = '{0:>9} {1:>9}'.format(value1, value2) + spc = ' '*(LINE_LENGTH-(len(text)+len(values)+2)) + print('{0}{spc} {1}'.format(text, values, spc=spc)) + + +def prt_i2(text, value1, value2): + """Print text and two values, with indent""" + values = '{0:>9} {1:>9}'.format(value1, value2) + spc = ' '*(LINE_LENGTH-(len(INDENT)+len(text)+len(values)+2)) + print(INDENT+'{0}{spc} {1}'.format(text, values, spc=spc)) + + +# The section output concentrates on important parameters instead of +# being exhaustive (that is what the --raw parameter is for) + + +def section_arc(kstats_dict): + """Give basic information on the ARC, MRU and MFU. This is the first + and most used section. + """ + + arc_stats = isolate_section('arcstats', kstats_dict) + + memory_all = arc_stats['memory_all_bytes'] + memory_free = arc_stats['memory_free_bytes'] + memory_avail = arc_stats['memory_available_bytes'] + arc_size = arc_stats['size'] + arc_target_size = arc_stats['c'] + arc_max = arc_stats['c_max'] + arc_min = arc_stats['c_min'] + dnode_limit = arc_stats['arc_dnode_limit'] + + print('ARC status:') + prt_i1('Total memory size:', f_bytes(memory_all)) + prt_i2('Min target size:', f_perc(arc_min, memory_all), f_bytes(arc_min)) + prt_i2('Max target size:', f_perc(arc_max, memory_all), f_bytes(arc_max)) + prt_i2('Target size (adaptive):', + f_perc(arc_size, arc_max), f_bytes(arc_target_size)) + prt_i2('Current size:', f_perc(arc_size, arc_max), f_bytes(arc_size)) + prt_i1('Free memory size:', f_bytes(memory_free)) + prt_i1('Available memory size:', f_bytes(memory_avail)) + print() + + compressed_size = arc_stats['compressed_size'] + uncompressed_size = arc_stats['uncompressed_size'] + overhead_size = arc_stats['overhead_size'] + bonus_size = arc_stats['bonus_size'] + dnode_size = arc_stats['dnode_size'] + dbuf_size = arc_stats['dbuf_size'] + hdr_size = arc_stats['hdr_size'] + l2_hdr_size = arc_stats['l2_hdr_size'] + abd_chunk_waste_size = arc_stats['abd_chunk_waste_size'] + + prt_1('ARC structural breakdown (current size):', f_bytes(arc_size)) + prt_i2('Compressed size:', + f_perc(compressed_size, arc_size), f_bytes(compressed_size)) + prt_i2('Overhead size:', + f_perc(overhead_size, arc_size), f_bytes(overhead_size)) + prt_i2('Bonus size:', + f_perc(bonus_size, arc_size), f_bytes(bonus_size)) + prt_i2('Dnode size:', + f_perc(dnode_size, arc_size), f_bytes(dnode_size)) + prt_i2('Dbuf size:', + f_perc(dbuf_size, arc_size), f_bytes(dbuf_size)) + prt_i2('Header size:', + f_perc(hdr_size, arc_size), f_bytes(hdr_size)) + prt_i2('L2 header size:', + f_perc(l2_hdr_size, arc_size), f_bytes(l2_hdr_size)) + prt_i2('ABD chunk waste size:', + f_perc(abd_chunk_waste_size, arc_size), f_bytes(abd_chunk_waste_size)) + print() + + meta = arc_stats['meta'] + pd = arc_stats['pd'] + pm = arc_stats['pm'] + data_size = arc_stats['data_size'] + metadata_size = arc_stats['metadata_size'] + anon_data = arc_stats['anon_data'] + anon_metadata = arc_stats['anon_metadata'] + mfu_data = arc_stats['mfu_data'] + mfu_metadata = arc_stats['mfu_metadata'] + mfu_edata = arc_stats['mfu_evictable_data'] + mfu_emetadata = arc_stats['mfu_evictable_metadata'] + mru_data = arc_stats['mru_data'] + mru_metadata = arc_stats['mru_metadata'] + mru_edata = arc_stats['mru_evictable_data'] + mru_emetadata = arc_stats['mru_evictable_metadata'] + mfug_data = arc_stats['mfu_ghost_data'] + mfug_metadata = arc_stats['mfu_ghost_metadata'] + mrug_data = arc_stats['mru_ghost_data'] + mrug_metadata = arc_stats['mru_ghost_metadata'] + unc_data = arc_stats['uncached_data'] + unc_metadata = arc_stats['uncached_metadata'] + caches_size = int(anon_data)+int(anon_metadata)+\ + int(mfu_data)+int(mfu_metadata)+int(mru_data)+int(mru_metadata)+\ + int(unc_data)+int(unc_metadata) + + prt_1('ARC types breakdown (compressed + overhead):', f_bytes(caches_size)) + prt_i2('Data size:', + f_perc(data_size, caches_size), f_bytes(data_size)) + prt_i2('Metadata size:', + f_perc(metadata_size, caches_size), f_bytes(metadata_size)) + print() + + prt_1('ARC states breakdown (compressed + overhead):', f_bytes(caches_size)) + prt_i2('Anonymous data size:', + f_perc(anon_data, caches_size), f_bytes(anon_data)) + prt_i2('Anonymous metadata size:', + f_perc(anon_metadata, caches_size), f_bytes(anon_metadata)) + s = 4294967296 + v = (s-int(pd))*(s-int(meta))/s + prt_i2('MFU data target:', f_perc(v, s), + f_bytes(v / 65536 * caches_size / 65536)) + prt_i2('MFU data size:', + f_perc(mfu_data, caches_size), f_bytes(mfu_data)) + prt_i2('MFU evictable data size:', + f_perc(mfu_edata, caches_size), f_bytes(mfu_edata)) + prt_i1('MFU ghost data size:', f_bytes(mfug_data)) + v = (s-int(pm))*int(meta)/s + prt_i2('MFU metadata target:', f_perc(v, s), + f_bytes(v / 65536 * caches_size / 65536)) + prt_i2('MFU metadata size:', + f_perc(mfu_metadata, caches_size), f_bytes(mfu_metadata)) + prt_i2('MFU evictable metadata size:', + f_perc(mfu_emetadata, caches_size), f_bytes(mfu_emetadata)) + prt_i1('MFU ghost metadata size:', f_bytes(mfug_metadata)) + v = int(pd)*(s-int(meta))/s + prt_i2('MRU data target:', f_perc(v, s), + f_bytes(v / 65536 * caches_size / 65536)) + prt_i2('MRU data size:', + f_perc(mru_data, caches_size), f_bytes(mru_data)) + prt_i2('MRU evictable data size:', + f_perc(mru_edata, caches_size), f_bytes(mru_edata)) + prt_i1('MRU ghost data size:', f_bytes(mrug_data)) + v = int(pm)*int(meta)/s + prt_i2('MRU metadata target:', f_perc(v, s), + f_bytes(v / 65536 * caches_size / 65536)) + prt_i2('MRU metadata size:', + f_perc(mru_metadata, caches_size), f_bytes(mru_metadata)) + prt_i2('MRU evictable metadata size:', + f_perc(mru_emetadata, caches_size), f_bytes(mru_emetadata)) + prt_i1('MRU ghost metadata size:', f_bytes(mrug_metadata)) + prt_i2('Uncached data size:', + f_perc(unc_data, caches_size), f_bytes(unc_data)) + prt_i2('Uncached metadata size:', + f_perc(unc_metadata, caches_size), f_bytes(unc_metadata)) + print() + + print('ARC hash breakdown:') + prt_i1('Elements:', f_hits(arc_stats['hash_elements'])) + prt_i1('Collisions:', f_hits(arc_stats['hash_collisions'])) + + prt_i1('Chain max:', f_hits(arc_stats['hash_chain_max'])) + prt_i1('Chains:', f_hits(arc_stats['hash_chains'])) + print() + + print('ARC misc:') + prt_i2('Uncompressed size:', f_perc(uncompressed_size, compressed_size), + f_bytes(uncompressed_size)) + prt_i1('Memory throttles:', arc_stats['memory_throttle_count']) + prt_i1('Memory direct reclaims:', arc_stats['memory_direct_count']) + prt_i1('Memory indirect reclaims:', arc_stats['memory_indirect_count']) + prt_i1('Deleted:', f_hits(arc_stats['deleted'])) + prt_i1('Mutex misses:', f_hits(arc_stats['mutex_miss'])) + prt_i1('Eviction skips:', f_hits(arc_stats['evict_skip'])) + prt_i1('Eviction skips due to L2 writes:', + f_hits(arc_stats['evict_l2_skip'])) + prt_i1('L2 cached evictions:', f_bytes(arc_stats['evict_l2_cached'])) + prt_i1('L2 eligible evictions:', f_bytes(arc_stats['evict_l2_eligible'])) + prt_i2('L2 eligible MFU evictions:', + f_perc(arc_stats['evict_l2_eligible_mfu'], + arc_stats['evict_l2_eligible']), + f_bytes(arc_stats['evict_l2_eligible_mfu'])) + prt_i2('L2 eligible MRU evictions:', + f_perc(arc_stats['evict_l2_eligible_mru'], + arc_stats['evict_l2_eligible']), + f_bytes(arc_stats['evict_l2_eligible_mru'])) + prt_i1('L2 ineligible evictions:', + f_bytes(arc_stats['evict_l2_ineligible'])) + print() + + +def section_archits(kstats_dict): + """Print information on how the caches are accessed ("arc hits"). + """ + + arc_stats = isolate_section('arcstats', kstats_dict) + all_accesses = int(arc_stats['hits'])+int(arc_stats['iohits'])+\ + int(arc_stats['misses']) + + prt_1('ARC total accesses:', f_hits(all_accesses)) + ta_todo = (('Total hits:', arc_stats['hits']), + ('Total I/O hits:', arc_stats['iohits']), + ('Total misses:', arc_stats['misses'])) + for title, value in ta_todo: + prt_i2(title, f_perc(value, all_accesses), f_hits(value)) + print() + + dd_total = int(arc_stats['demand_data_hits']) +\ + int(arc_stats['demand_data_iohits']) +\ + int(arc_stats['demand_data_misses']) + prt_2('ARC demand data accesses:', f_perc(dd_total, all_accesses), + f_hits(dd_total)) + dd_todo = (('Demand data hits:', arc_stats['demand_data_hits']), + ('Demand data I/O hits:', arc_stats['demand_data_iohits']), + ('Demand data misses:', arc_stats['demand_data_misses'])) + for title, value in dd_todo: + prt_i2(title, f_perc(value, dd_total), f_hits(value)) + print() + + dm_total = int(arc_stats['demand_metadata_hits']) +\ + int(arc_stats['demand_metadata_iohits']) +\ + int(arc_stats['demand_metadata_misses']) + prt_2('ARC demand metadata accesses:', f_perc(dm_total, all_accesses), + f_hits(dm_total)) + dm_todo = (('Demand metadata hits:', arc_stats['demand_metadata_hits']), + ('Demand metadata I/O hits:', + arc_stats['demand_metadata_iohits']), + ('Demand metadata misses:', arc_stats['demand_metadata_misses'])) + for title, value in dm_todo: + prt_i2(title, f_perc(value, dm_total), f_hits(value)) + print() + + pd_total = int(arc_stats['prefetch_data_hits']) +\ + int(arc_stats['prefetch_data_iohits']) +\ + int(arc_stats['prefetch_data_misses']) + prt_2('ARC prefetch data accesses:', f_perc(pd_total, all_accesses), + f_hits(pd_total)) + pd_todo = (('Prefetch data hits:', arc_stats['prefetch_data_hits']), + ('Prefetch data I/O hits:', arc_stats['prefetch_data_iohits']), + ('Prefetch data misses:', arc_stats['prefetch_data_misses'])) + for title, value in pd_todo: + prt_i2(title, f_perc(value, pd_total), f_hits(value)) + print() + + pm_total = int(arc_stats['prefetch_metadata_hits']) +\ + int(arc_stats['prefetch_metadata_iohits']) +\ + int(arc_stats['prefetch_metadata_misses']) + prt_2('ARC prefetch metadata accesses:', f_perc(pm_total, all_accesses), + f_hits(pm_total)) + pm_todo = (('Prefetch metadata hits:', + arc_stats['prefetch_metadata_hits']), + ('Prefetch metadata I/O hits:', + arc_stats['prefetch_metadata_iohits']), + ('Prefetch metadata misses:', + arc_stats['prefetch_metadata_misses'])) + for title, value in pm_todo: + prt_i2(title, f_perc(value, pm_total), f_hits(value)) + print() + + all_prefetches = int(arc_stats['predictive_prefetch'])+\ + int(arc_stats['prescient_prefetch']) + prt_2('ARC predictive prefetches:', + f_perc(arc_stats['predictive_prefetch'], all_prefetches), + f_hits(arc_stats['predictive_prefetch'])) + prt_i2('Demand hits after predictive:', + f_perc(arc_stats['demand_hit_predictive_prefetch'], + arc_stats['predictive_prefetch']), + f_hits(arc_stats['demand_hit_predictive_prefetch'])) + prt_i2('Demand I/O hits after predictive:', + f_perc(arc_stats['demand_iohit_predictive_prefetch'], + arc_stats['predictive_prefetch']), + f_hits(arc_stats['demand_iohit_predictive_prefetch'])) + never = int(arc_stats['predictive_prefetch']) -\ + int(arc_stats['demand_hit_predictive_prefetch']) -\ + int(arc_stats['demand_iohit_predictive_prefetch']) + prt_i2('Never demanded after predictive:', + f_perc(never, arc_stats['predictive_prefetch']), + f_hits(never)) + print() + + prt_2('ARC prescient prefetches:', + f_perc(arc_stats['prescient_prefetch'], all_prefetches), + f_hits(arc_stats['prescient_prefetch'])) + prt_i2('Demand hits after prescient:', + f_perc(arc_stats['demand_hit_prescient_prefetch'], + arc_stats['prescient_prefetch']), + f_hits(arc_stats['demand_hit_prescient_prefetch'])) + prt_i2('Demand I/O hits after prescient:', + f_perc(arc_stats['demand_iohit_prescient_prefetch'], + arc_stats['prescient_prefetch']), + f_hits(arc_stats['demand_iohit_prescient_prefetch'])) + never = int(arc_stats['prescient_prefetch'])-\ + int(arc_stats['demand_hit_prescient_prefetch'])-\ + int(arc_stats['demand_iohit_prescient_prefetch']) + prt_i2('Never demanded after prescient:', + f_perc(never, arc_stats['prescient_prefetch']), + f_hits(never)) + print() + + print('ARC states hits of all accesses:') + cl_todo = (('Most frequently used (MFU):', arc_stats['mfu_hits']), + ('Most recently used (MRU):', arc_stats['mru_hits']), + ('Most frequently used (MFU) ghost:', + arc_stats['mfu_ghost_hits']), + ('Most recently used (MRU) ghost:', + arc_stats['mru_ghost_hits']), + ('Uncached:', arc_stats['uncached_hits'])) + for title, value in cl_todo: + prt_i2(title, f_perc(value, all_accesses), f_hits(value)) + print() + + +def section_dmu(kstats_dict): + """Collect information on the DMU""" + + zfetch_stats = isolate_section('zfetchstats', kstats_dict) + + zfetch_access_total = int(zfetch_stats['hits']) +\ + int(zfetch_stats['future']) + int(zfetch_stats['stride']) +\ + int(zfetch_stats['past']) + int(zfetch_stats['misses']) + + prt_1('DMU predictive prefetcher calls:', f_hits(zfetch_access_total)) + prt_i2('Stream hits:', + f_perc(zfetch_stats['hits'], zfetch_access_total), + f_hits(zfetch_stats['hits'])) + future = int(zfetch_stats['future']) + int(zfetch_stats['stride']) + prt_i2('Hits ahead of stream:', f_perc(future, zfetch_access_total), + f_hits(future)) + prt_i2('Hits behind stream:', + f_perc(zfetch_stats['past'], zfetch_access_total), + f_hits(zfetch_stats['past'])) + prt_i2('Stream misses:', + f_perc(zfetch_stats['misses'], zfetch_access_total), + f_hits(zfetch_stats['misses'])) + prt_i2('Streams limit reached:', + f_perc(zfetch_stats['max_streams'], zfetch_stats['misses']), + f_hits(zfetch_stats['max_streams'])) + prt_i1('Stream strides:', f_hits(zfetch_stats['stride'])) + prt_i1('Prefetches issued', f_hits(zfetch_stats['io_issued'])) + print() + + +def section_l2arc(kstats_dict): + """Collect information on L2ARC device if present. If not, tell user + that we're skipping the section. + """ + + # The L2ARC statistics live in the same section as the normal ARC stuff + arc_stats = isolate_section('arcstats', kstats_dict) + + # Skip the section only when no cache device is attached. Fall back to + # l2_size for older kernels that do not export l2_ndev. + if arc_stats.get('l2_ndev', '0') == '0' and \ + arc_stats['l2_size'] == '0': + print('L2ARC not detected, skipping section\n') + return + + l2_errors = int(arc_stats['l2_writes_error']) +\ + int(arc_stats['l2_cksum_bad']) +\ + int(arc_stats['l2_io_error']) + + l2_access_total = int(arc_stats['l2_hits'])+int(arc_stats['l2_misses']) + health = 'HEALTHY' + + if l2_errors > 0: + health = 'DEGRADED' + + prt_1('L2ARC status:', health) + + l2_todo = (('Low memory aborts:', 'l2_abort_lowmem'), + ('Free on write:', 'l2_free_on_write'), + ('R/W clashes:', 'l2_rw_clash'), + ('Bad checksums:', 'l2_cksum_bad'), + ('Read errors:', 'l2_io_error'), + ('Write errors:', 'l2_writes_error')) + + for title, value in l2_todo: + prt_i1(title, f_hits(arc_stats[value])) + + print() + prt_1('L2ARC size (adaptive):', f_bytes(arc_stats['l2_size'])) + prt_i2('Compressed:', f_perc(arc_stats['l2_asize'], arc_stats['l2_size']), + f_bytes(arc_stats['l2_asize'])) + prt_i2('Header size:', + f_perc(arc_stats['l2_hdr_size'], arc_stats['l2_size']), + f_bytes(arc_stats['l2_hdr_size'])) + prt_i2('MFU allocated size:', + f_perc(arc_stats['l2_mfu_asize'], arc_stats['l2_asize']), + f_bytes(arc_stats['l2_mfu_asize'])) + prt_i2('MRU allocated size:', + f_perc(arc_stats['l2_mru_asize'], arc_stats['l2_asize']), + f_bytes(arc_stats['l2_mru_asize'])) + prt_i2('Prefetch allocated size:', + f_perc(arc_stats['l2_prefetch_asize'], arc_stats['l2_asize']), + f_bytes(arc_stats['l2_prefetch_asize'])) + prt_i2('Data (buffer content) allocated size:', + f_perc(arc_stats['l2_bufc_data_asize'], arc_stats['l2_asize']), + f_bytes(arc_stats['l2_bufc_data_asize'])) + prt_i2('Metadata (buffer content) allocated size:', + f_perc(arc_stats['l2_bufc_metadata_asize'], arc_stats['l2_asize']), + f_bytes(arc_stats['l2_bufc_metadata_asize'])) + + print() + prt_1('L2ARC breakdown:', f_hits(l2_access_total)) + prt_i2('Hit ratio:', + f_perc(arc_stats['l2_hits'], l2_access_total), + f_hits(arc_stats['l2_hits'])) + prt_i2('Miss ratio:', + f_perc(arc_stats['l2_misses'], l2_access_total), + f_hits(arc_stats['l2_misses'])) + + print() + print('L2ARC I/O:') + prt_i2('Reads:', + f_bytes(arc_stats['l2_read_bytes']), + f_hits(arc_stats['l2_hits'])) + prt_i2('Writes:', + f_bytes(arc_stats['l2_write_bytes']), + f_hits(arc_stats['l2_writes_sent'])) + + print() + print('L2ARC evicts:') + prt_i1('L1 cached:', f_hits(arc_stats['l2_evict_l1cached'])) + prt_i1('While reading:', f_hits(arc_stats['l2_evict_reading'])) + print() + + +def section_spl(*_): + """Print the SPL parameters, if requested with alternative format + and/or descriptions. This does not use kstats. + """ + + if sys.platform.startswith('freebsd'): + # No SPL support in FreeBSD + return + + spls = get_spl_params() + keylist = sorted(spls.keys()) + print('Solaris Porting Layer (SPL):') + + if ARGS.desc: + descriptions = get_descriptions('spl') + + for key in keylist: + value = spls[key] + + if ARGS.desc: + try: + print(INDENT+'#', descriptions[key]) + except KeyError: + print(INDENT+'# (No description found)') # paranoid + + print(format_raw_line(key, value)) + + print() + + +def section_tunables(*_): + """Print the tunables, if requested with alternative format and/or + descriptions. This does not use kstasts. + """ + + tunables = get_tunable_params() + keylist = sorted(tunables.keys()) + print('Tunables:') + + if ARGS.desc: + descriptions = get_descriptions('zfs') + + for key in keylist: + value = tunables[key] + + if ARGS.desc: + try: + print(INDENT+'#', descriptions[key]) + except KeyError: + print(INDENT+'# (No description found)') # paranoid + + print(format_raw_line(key, value)) + + print() + + +def section_zil(kstats_dict): + """Collect information on the ZFS Intent Log. Some of the information + taken from https://github.com/openzfs/zfs/blob/master/include/sys/zil.h + """ + + zil_stats = isolate_section('zil', kstats_dict) + + prt_1('ZIL committed transactions:', + f_hits(zil_stats['zil_itx_count'])) + prt_i1('Commit requests:', f_hits(zil_stats['zil_commit_count'])) + prt_i1('Flushes to stable storage:', + f_hits(zil_stats['zil_commit_writer_count'])) + prt_i2('Transactions to SLOG storage pool:', + f_bytes(zil_stats['zil_itx_metaslab_slog_bytes']), + f_hits(zil_stats['zil_itx_metaslab_slog_count'])) + prt_i2('Transactions to non-SLOG storage pool:', + f_bytes(zil_stats['zil_itx_metaslab_normal_bytes']), + f_hits(zil_stats['zil_itx_metaslab_normal_count'])) + print() + + +section_calls = {'arc': section_arc, + 'archits': section_archits, + 'dmu': section_dmu, + 'l2arc': section_l2arc, + 'spl': section_spl, + 'tunables': section_tunables, + 'zil': section_zil} + + +def main(): + """Run program. The options to draw a graph and to print all data raw are + treated separately because they come with their own call. + """ + + kstats = get_kstats() + + if ARGS.graph: + draw_graph(kstats) + sys.exit(0) + + print_header() + + if ARGS.raw: + print_raw(kstats) + + elif ARGS.section: + + try: + section_calls[ARGS.section](kstats) + except KeyError: + print('Error: Section "{0}" unknown'.format(ARGS.section)) + sys.exit(1) + + elif ARGS.page: + print('WARNING: Pages are deprecated, please use "--section"\n') + + pages_to_calls = {1: 'arc', + 2: 'archits', + 3: 'l2arc', + 4: 'dmu', + 5: 'vdev', + 6: 'tunables'} + + try: + call = pages_to_calls[ARGS.page] + except KeyError: + print('Error: Page "{0}" not supported'.format(ARGS.page)) + sys.exit(1) + else: + section_calls[call](kstats) + + else: + # If no parameters were given, we print all sections. We might want to + # change the sequence by hand + calls = sorted(section_calls.keys()) + + for section in calls: + section_calls[section](kstats) + + sys.exit(0) + + +if __name__ == '__main__': + main() diff --git a/sysutils/py-zfsstat/src/zarcsummary.1 b/sysutils/py-zfsstat/src/zarcsummary.1 new file mode 100644 index 000000000000..79905b56a947 --- /dev/null +++ b/sysutils/py-zfsstat/src/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 +.\" https://opensource.org/license/CDDL-1.0. +.\" +.\" 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 . diff --git a/sysutils/py-zfsstat/src/zilstat.1 b/sysutils/py-zfsstat/src/zilstat.1 new file mode 100644 index 000000000000..3dc73eaad57f --- /dev/null +++ b/sysutils/py-zfsstat/src/zilstat.1 @@ -0,0 +1,180 @@ +.\" 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 +.\" https://opensource.org/license/CDDL-1.0. +.\" +.\" Copyright (c) 2026 Christos Longros. All rights reserved. +.\" +.Dd March 9, 2026 +.Dt ZILSTAT 1 +.Os +. +.Sh NAME +.Nm zilstat +.Nd report ZFS Intent Log statistics +.Sh SYNOPSIS +.Nm +.Op Fl v +.Op Fl a Ns | Ns Fl p Ar pool Ns | Ns Fl d Ar dataset Ns Op , Ns Ar dataset Ns … +.Op Fl f Ar field Ns Op , Ns Ar field Ns … +.Op Fl s Ar separator +.Op Fl i Ar interval +. +.Sh DESCRIPTION +.Nm +prints statistics about the ZFS Intent Log (ZIL). +The ZIL is used to log synchronous write operations and is replayed on +pool import if the system crashes before those writes are committed to +the main pool. +.Pp +By default, global ZIL statistics are displayed. +When a pool or dataset is specified, per-dataset statistics are shown +instead. +.Pp +If an +.Ar interval +is specified, the output is repeated every +.Ar interval +seconds showing the change in values since the previous sample. +Without an interval, cumulative values are displayed. +.Pp +The following fields are available: +.Bl -tag -compact -offset Ds -width "imnw" +.It Sy time +Current time +.It Sy pool +Pool name +.It Sy ds +Dataset name +.It Sy obj +Objset ID +.It Sy cc +Commit count +.It Sy cwc +Commit writer count +.It Sy cec +Commit error count +.It Sy csc +Commit stall count +.It Sy cSc +Commit suspend count +.It Sy cCc +Commit crash count +.It Sy ic +In-transaction count +.It Sy iic +Indirect in-transaction count +.It Sy iib +Indirect in-transaction bytes +.It Sy icc +Copied in-transaction count +.It Sy icb +Copied in-transaction bytes +.It Sy inc +Needcopy in-transaction count +.It Sy inb +Needcopy in-transaction bytes +.It Sy idc +Direct (copied + needcopy) count +.It Sy idb +Direct (copied + needcopy) bytes +.It Sy iwc +Total write (indirect + direct) count +.It Sy iwb +Total write (indirect + direct) bytes +.It Sy imnc +Normal metaslab count +.It Sy imnb +Normal metaslab bytes +.It Sy imnw +Normal metaslab write bytes +.It Sy imna +Normal metaslab alloc bytes +.It Sy imsc +SLOG metaslab count +.It Sy imsb +SLOG metaslab bytes +.It Sy imsw +SLOG metaslab write bytes +.It Sy imsa +SLOG metaslab alloc bytes +.It Sy imc +Total metaslab (normal + SLOG) count +.It Sy imb +Total metaslab (normal + SLOG) bytes +.It Sy imw +Total metaslab (normal + SLOG) write bytes +.It Sy ima +Total metaslab (normal + SLOG) alloc bytes +.It Sy se% +Space efficiency percentage (bytes / alloc) +.It Sy sen% +Normal space efficiency percentage +.It Sy ses% +SLOG space efficiency percentage +.It Sy te% +Total efficiency percentage (bytes / write) +.It Sy ten% +Normal total efficiency percentage +.It Sy tes% +SLOG total efficiency percentage +.El +. +.Sh OPTIONS +.Bl -tag -width "-s" +.It Fl h +Display a help message. +.It Fl a +Print statistics for all datasets across all pools. +.It Fl d Ar dataset +Print statistics for the specified dataset(s). +Multiple datasets may be given as a comma-separated list. +.It Fl f Ar field +Display only the specified fields. +Multiple fields may be given as a comma-separated list. +See +.Sx DESCRIPTION +for available fields. +.It Fl i Ar interval +Print statistics every +.Ar interval +seconds. +Values are reported as rates per second. +.It Fl p Ar pool +Print statistics for all datasets in the specified pool. +.It Fl s Ar separator +Override the default field separator +.Pq two spaces +with a custom string. +.It Fl v +List all available field headers and their definitions. +.El +. +.Sh ENVIRONMENT +.Bl -tag -width "Linux" +.It Sy Linux +Statistics are read from +.Pa /proc/spl/kstat/zfs/zil +for global stats and from per-pool objset files under +.Pa /proc/spl/kstat/zfs/ Ns Ar pool Ns Pa / . +.It Sy FreeBSD +Statistics are read via +.Xr sysctl 8 +from the +.Sy kstat.zfs +tree. +.El +. +.Sh SEE ALSO +.Xr zarcstat 1 , +.Xr zpool-status 8 +. +.Sh AUTHORS +This manual page was written by +.An Christos Longros Aq Mt chris.longros@gmail.com . diff --git a/sysutils/py-zfsstat/src/zilstat.in b/sysutils/py-zfsstat/src/zilstat.in new file mode 100644 index 000000000000..d01db9b0914b --- /dev/null +++ b/sysutils/py-zfsstat/src/zilstat.in @@ -0,0 +1,556 @@ +#!/usr/bin/env @PYTHON_SHEBANG@ +# SPDX-License-Identifier: CDDL-1.0 +# +# Print out statistics for all zil stats. This information is +# available through the zil kstat. +# +# CDDL HEADER START +# +# The contents of this file are subject to the terms of the +# Common Development and Distribution License, Version 1.0 only +# (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] +# +# This script must remain compatible with Python 3.6+. +# + +import sys +import subprocess +import time +import copy +import os +import re +import signal +from collections import defaultdict +import argparse +from argparse import RawTextHelpFormatter + +cols = { + # hdr: [size, scale, kstat name] + "time": [8, -1, "time"], + "pool": [12, -1, "pool"], + "ds": [12, -1, "dataset_name"], + "obj": [12, -1, "objset"], + "cc": [5, 1000, "zil_commit_count"], + "cwc": [5, 1000, "zil_commit_writer_count"], + "cec": [5, 1000, "zil_commit_error_count"], + "csc": [5, 1000, "zil_commit_stall_count"], + "cSc": [5, 1000, "zil_commit_suspend_count"], + "cCc": [5, 1000, "zil_commit_crash_count"], + "ic": [5, 1000, "zil_itx_count"], + "iic": [5, 1000, "zil_itx_indirect_count"], + "iib": [5, 1024, "zil_itx_indirect_bytes"], + "icc": [5, 1000, "zil_itx_copied_count"], + "icb": [5, 1024, "zil_itx_copied_bytes"], + "inc": [5, 1000, "zil_itx_needcopy_count"], + "inb": [5, 1024, "zil_itx_needcopy_bytes"], + "idc": [5, 1000, "icc+inc"], + "idb": [5, 1024, "icb+inb"], + "iwc": [5, 1000, "iic+idc"], + "iwb": [5, 1024, "iib+idb"], + "imnc": [6, 1000, "zil_itx_metaslab_normal_count"], + "imnb": [6, 1024, "zil_itx_metaslab_normal_bytes"], + "imnw": [6, 1024, "zil_itx_metaslab_normal_write"], + "imna": [6, 1024, "zil_itx_metaslab_normal_alloc"], + "imsc": [6, 1000, "zil_itx_metaslab_slog_count"], + "imsb": [6, 1024, "zil_itx_metaslab_slog_bytes"], + "imsw": [6, 1024, "zil_itx_metaslab_slog_write"], + "imsa": [6, 1024, "zil_itx_metaslab_slog_alloc"], + "imc": [5, 1000, "imnc+imsc"], + "imb": [5, 1024, "imnb+imsb"], + "imw": [5, 1024, "imnw+imsw"], + "ima": [5, 1024, "imna+imsa"], + "se%": [3, 100, "imb/ima"], + "sen%": [4, 100, "imnb/imna"], + "ses%": [4, 100, "imsb/imsa"], + "te%": [3, 100, "imb/imw"], + "ten%": [4, 100, "imnb/imnw"], + "tes%": [4, 100, "imsb/imsw"], +} + +hdr = ["time", "ds", "cc", "ic", "idc", "idb", "iic", "iib", + "imnc", "imnw", "imsc", "imsw"] + +ghdr = ["time", "cc", "ic", "idc", "idb", "iic", "iib", + "imnc", "imnw", "imsc", "imsw"] + +cmd = ("Usage: zilstat [-hgdv] [-i interval] [-p pool_name]") + +curr = {} +diff = {} +kstat = {} +ds_pairs = {} +pool_name = None +dataset_name = None +interval = 0 +sep = " " +gFlag = True +dsFlag = False + +def prettynum(sz, scale, num=0): + suffix = [' ', 'K', 'M', 'G', 'T', 'P', 'E', 'Z'] + index = 0 + save = 0 + + if scale == -1: + return "%*s" % (sz, num) + + # Rounding error, return 0 + elif 0 < num < 1: + num = 0 + + while num > scale and index < 5: + save = num + num = num / scale + index += 1 + + if index == 0: + return "%*d" % (sz, num) + + if (save / scale) < 10: + return "%*.1f%s" % (sz - 1, num, suffix[index]) + else: + return "%*d%s" % (sz - 1, num, suffix[index]) + +def print_header(): + global hdr + global sep + for col in hdr: + new_col = col + if interval > 0 and cols[col][1] > 100: + new_col += "/s" + sys.stdout.write("%*s%s" % (cols[col][0], new_col, sep)) + sys.stdout.write("\n") + +def print_values(v): + global hdr + global sep + for col in hdr: + val = v[cols[col][2]] + if interval > 0 and cols[col][1] > 100: + val = v[cols[col][2]] // interval + sys.stdout.write("%s%s" % ( + prettynum(cols[col][0], cols[col][1], val), sep)) + sys.stdout.write("\n") + +def print_dict(d): + for pool in d: + for objset in d[pool]: + print_values(d[pool][objset]) + +def detailed_usage(): + sys.stderr.write("%s\n" % cmd) + sys.stderr.write("Field definitions are as follows:\n") + for key in cols: + sys.stderr.write("%11s : %s\n" % (key, cols[key][2])) + sys.stderr.write("\n") + sys.exit(0) + +def init(): + global pool_name + global dataset_name + global interval + global hdr + global curr + global gFlag + global sep + + curr = dict() + + parser = argparse.ArgumentParser(description='Program to print zilstats', + add_help=True, + formatter_class=RawTextHelpFormatter, + epilog="\nUsage Examples\n"\ + "Note: Global zilstats is shown by default,"\ + " if none of a|p|d option is not provided\n"\ + "\tzilstat -a\n"\ + '\tzilstat -v\n'\ + '\tzilstat -p tank\n'\ + '\tzilstat -d tank/d1,tank/d2,tank/zv1\n'\ + '\tzilstat -i 1\n'\ + '\tzilstat -s \"***\"\n'\ + '\tzilstat -f zcwc,zimnb,zimsb\n') + + parser.add_argument( + "-v", "--verbose", + action="store_true", + help="List field headers and definitions" + ) + + pool_grp = parser.add_mutually_exclusive_group() + + pool_grp.add_argument( + "-a", "--all", + action="store_true", + dest="all", + help="Print all dataset stats" + ) + + pool_grp.add_argument( + "-p", "--pool", + type=str, + help="Print stats for all datasets of a speicfied pool" + ) + + pool_grp.add_argument( + "-d", "--dataset", + type=str, + help="Print given dataset(s) (Comma separated)" + ) + + parser.add_argument( + "-f", "--columns", + type=str, + help="Specify specific fields to print (see -v)" + ) + + parser.add_argument( + "-s", "--separator", + type=str, + help="Override default field separator with custom " + "character or string" + ) + + parser.add_argument( + "-i", "--interval", + type=int, + dest="interval", + help="Print stats between specified interval" + " (in seconds)" + ) + + parsed_args = parser.parse_args() + + if parsed_args.verbose: + detailed_usage() + + if parsed_args.all: + gFlag = False + + if parsed_args.interval: + interval = parsed_args.interval + + if parsed_args.pool: + pool_name = parsed_args.pool + gFlag = False + + if parsed_args.dataset: + dataset_name = parsed_args.dataset + gFlag = False + + if parsed_args.separator: + sep = parsed_args.separator + + if gFlag: + hdr = ghdr + + if parsed_args.columns: + hdr = parsed_args.columns.split(",") + + invalid = [] + for ele in hdr: + if ele not in cols: + invalid.append(ele) + + if len(invalid) > 0: + sys.stderr.write("Invalid column definition! -- %s\n" % invalid) + sys.exit(1) + + if pool_name and dataset_name: + print ("Error: Can not filter both dataset and pool") + sys.exit(1) + +def FileCheck(fname): + try: + return (open(fname)) + except IOError: + print ("Unable to open zilstat proc file: " + fname) + sys.exit(1) + +if sys.platform.startswith('freebsd'): + # Requires py-sysctl on FreeBSD + import sysctl + + def kstat_update(pool = None, objid = None): + global kstat + kstat = {} + if not pool: + file = "kstat.zfs.misc.zil" + k = [ctl for ctl in sysctl.filter(file) \ + if ctl.type != sysctl.CTLTYPE_NODE] + kstat_process_str(k, file, "GLOBAL", len(file + ".")) + elif objid: + file = "kstat.zfs." + pool + ".dataset.objset-" + objid + k = [ctl for ctl in sysctl.filter(file) if ctl.type \ + != sysctl.CTLTYPE_NODE] + kstat_process_str(k, file, objid, len(file + ".")) + else: + file = "kstat.zfs." + pool + ".dataset" + zil_start = len(file + ".") + obj_start = len("kstat.zfs." + pool + ".") + k = [ctl for ctl in sysctl.filter(file) + if ctl.type != sysctl.CTLTYPE_NODE] + for s in k: + if not s or (s.name.find("zil") == -1 and \ + s.name.find("dataset_name") == -1): + continue + name, value = s.name, s.value + objid = re.findall(r'0x[0-9A-F]+', \ + name[obj_start:], re.I)[0] + if objid not in kstat: + kstat[objid] = dict() + zil_start = len(file + ".objset-" + \ + objid + ".") + kstat[objid][name[zil_start:]] = value \ + if (name.find("dataset_name")) \ + else int(value) + + def kstat_process_str(k, file, objset = "GLOBAL", zil_start = 0): + global kstat + if not k: + print("Unable to process kstat for: " + file) + sys.exit(1) + kstat[objset] = dict() + for s in k: + if not s or (s.name.find("zil") == -1 and \ + s.name.find("dataset_name") == -1): + continue + name, value = s.name, s.value + kstat[objset][name[zil_start:]] = value \ + if (name.find("dataset_name")) else int(value) + +elif sys.platform.startswith('linux'): + def kstat_update(pool = None, objid = None): + global kstat + kstat = {} + if not pool: + k = [line.strip() for line in \ + FileCheck("/proc/spl/kstat/zfs/zil")] + kstat_process_str(k, "/proc/spl/kstat/zfs/zil") + elif objid: + file = "/proc/spl/kstat/zfs/" + pool + "/objset-" + objid + k = [line.strip() for line in FileCheck(file)] + kstat_process_str(k, file, objid) + else: + if not os.path.exists(f"/proc/spl/kstat/zfs/{pool}"): + print("Pool \"" + pool + "\" does not exist, Exitting") + sys.exit(1) + objsets = os.listdir(f'/proc/spl/kstat/zfs/{pool}') + for objid in objsets: + if objid.find("objset-") == -1: + continue + file = "/proc/spl/kstat/zfs/" + pool + "/" + objid + k = [line.strip() for line in FileCheck(file)] + kstat_process_str(k, file, objid.replace("objset-", "")) + + def kstat_process_str(k, file, objset = "GLOBAL", zil_start = 0): + global kstat + if not k: + print("Unable to process kstat for: " + file) + sys.exit(1) + + kstat[objset] = dict() + for s in k: + if not s or (s.find("zil") == -1 and \ + s.find("dataset_name") == -1): + continue + name, unused, value = s.split() + kstat[objset][name] = value \ + if (name == "dataset_name") else int(value) + +def zil_process_kstat(): + global curr, pool_name, dataset_name, dsFlag, ds_pairs + curr.clear() + if gFlag == True: + kstat_update() + zil_build_dict() + else: + if pool_name: + kstat_update(pool_name) + zil_build_dict(pool_name) + elif dataset_name: + if dsFlag == False: + dsFlag = True + datasets = dataset_name.split(',') + ds_pairs = defaultdict(list) + for ds in datasets: + try: + objid = subprocess.check_output(['zfs', + 'list', '-Hpo', 'objsetid', ds], \ + stderr=subprocess.DEVNULL) \ + .decode('utf-8').strip() + except subprocess.CalledProcessError as e: + print("Command: \"zfs list -Hpo objset "\ + + str(ds) + "\" failed with error code:"\ + + str(e.returncode)) + print("Please make sure that dataset \""\ + + str(ds) + "\" exists") + sys.exit(1) + if not objid: + continue + ds_pairs[ds.split('/')[0]]. \ + append(hex(int(objid))) + for pool, objids in ds_pairs.items(): + for objid in objids: + kstat_update(pool, objid) + zil_build_dict(pool) + else: + try: + pools = subprocess.check_output(['zpool', 'list', '-Hpo',\ + 'name']).decode('utf-8').split() + except subprocess.CalledProcessError as e: + print("Command: \"zpool list -Hpo name\" failed with error"\ + "code: " + str(e.returncode)) + sys.exit(1) + for pool in pools: + kstat_update(pool) + zil_build_dict(pool) + +def calculate_diff(): + global curr, diff + prev = copy.deepcopy(curr) + zil_process_kstat() + diff = copy.deepcopy(curr) + for pool in curr: + for objset in curr[pool]: + for key in curr[pool][objset]: + if not isinstance(diff[pool][objset][key], int): + continue + # If prev is NULL, this is the + # first time we are here + if not prev: + diff[pool][objset][key] = 0 + else: + diff[pool][objset][key] \ + = curr[pool][objset][key] \ + - prev[pool][objset][key] + +def zil_build_dict(pool = "GLOBAL"): + global kstat + for objset in kstat: + for key in kstat[objset]: + val = kstat[objset][key] + if pool not in curr: + curr[pool] = dict() + if objset not in curr[pool]: + curr[pool][objset] = dict() + curr[pool][objset][key] = val + +def zil_extend_dict(): + global diff + for pool in diff: + for objset in diff[pool]: + diff[pool][objset]["pool"] = pool + diff[pool][objset]["objset"] = objset + diff[pool][objset]["time"] = time.strftime("%H:%M:%S", \ + time.localtime()) + diff[pool][objset]["icc+inc"] = \ + diff[pool][objset]["zil_itx_copied_count"] + \ + diff[pool][objset]["zil_itx_needcopy_count"] + diff[pool][objset]["icb+inb"] = \ + diff[pool][objset]["zil_itx_copied_bytes"] + \ + diff[pool][objset]["zil_itx_needcopy_bytes"] + diff[pool][objset]["iic+idc"] = \ + diff[pool][objset]["zil_itx_indirect_count"] + \ + diff[pool][objset]["zil_itx_copied_count"] + \ + diff[pool][objset]["zil_itx_needcopy_count"] + diff[pool][objset]["iib+idb"] = \ + diff[pool][objset]["zil_itx_indirect_bytes"] + \ + diff[pool][objset]["zil_itx_copied_bytes"] + \ + diff[pool][objset]["zil_itx_needcopy_bytes"] + diff[pool][objset]["imnc+imsc"] = \ + diff[pool][objset]["zil_itx_metaslab_normal_count"] + \ + diff[pool][objset]["zil_itx_metaslab_slog_count"] + diff[pool][objset]["imnb+imsb"] = \ + diff[pool][objset]["zil_itx_metaslab_normal_bytes"] + \ + diff[pool][objset]["zil_itx_metaslab_slog_bytes"] + diff[pool][objset]["imnw+imsw"] = \ + diff[pool][objset]["zil_itx_metaslab_normal_write"] + \ + diff[pool][objset]["zil_itx_metaslab_slog_write"] + diff[pool][objset]["imna+imsa"] = \ + diff[pool][objset]["zil_itx_metaslab_normal_alloc"] + \ + diff[pool][objset]["zil_itx_metaslab_slog_alloc"] + if diff[pool][objset]["imna+imsa"] > 0: + diff[pool][objset]["imb/ima"] = 100 * \ + diff[pool][objset]["imnb+imsb"] // \ + diff[pool][objset]["imna+imsa"] + else: + diff[pool][objset]["imb/ima"] = 100 + if diff[pool][objset]["zil_itx_metaslab_normal_alloc"] > 0: + diff[pool][objset]["imnb/imna"] = 100 * \ + diff[pool][objset]["zil_itx_metaslab_normal_bytes"] // \ + diff[pool][objset]["zil_itx_metaslab_normal_alloc"] + else: + diff[pool][objset]["imnb/imna"] = 100 + if diff[pool][objset]["zil_itx_metaslab_slog_alloc"] > 0: + diff[pool][objset]["imsb/imsa"] = 100 * \ + diff[pool][objset]["zil_itx_metaslab_slog_bytes"] // \ + diff[pool][objset]["zil_itx_metaslab_slog_alloc"] + else: + diff[pool][objset]["imsb/imsa"] = 100 + if diff[pool][objset]["imnw+imsw"] > 0: + diff[pool][objset]["imb/imw"] = 100 * \ + diff[pool][objset]["imnb+imsb"] // \ + diff[pool][objset]["imnw+imsw"] + else: + diff[pool][objset]["imb/imw"] = 100 + if diff[pool][objset]["zil_itx_metaslab_normal_alloc"] > 0: + diff[pool][objset]["imnb/imnw"] = 100 * \ + diff[pool][objset]["zil_itx_metaslab_normal_bytes"] // \ + diff[pool][objset]["zil_itx_metaslab_normal_write"] + else: + diff[pool][objset]["imnb/imnw"] = 100 + if diff[pool][objset]["zil_itx_metaslab_slog_alloc"] > 0: + diff[pool][objset]["imsb/imsw"] = 100 * \ + diff[pool][objset]["zil_itx_metaslab_slog_bytes"] // \ + diff[pool][objset]["zil_itx_metaslab_slog_write"] + else: + diff[pool][objset]["imsb/imsw"] = 100 + +def sign_handler_epipe(sig, frame): + print("Caught EPIPE signal: " + str(frame)) + print("Exitting...") + sys.exit(0) + +def main(): + global interval + global curr, diff + hprint = False + init() + signal.signal(signal.SIGINT, signal.SIG_DFL) + signal.signal(signal.SIGPIPE, sign_handler_epipe) + + zil_process_kstat() + if not curr: + print ("Error: No stats to show") + sys.exit(0) + print_header() + if interval > 0: + time.sleep(interval) + while True: + calculate_diff() + if not diff: + print ("Error: No stats to show") + sys.exit(0) + zil_extend_dict() + print_dict(diff) + time.sleep(interval) + else: + diff = curr + zil_extend_dict() + print_dict(diff) + +if __name__ == '__main__': + main() + |
