'\" t
.\"
.\" Copyright (c) 2026 Red Hat.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.TH PMDABTRFS 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmdabtrfs\f1 \- btrfs filesystem performance metrics domain agent (PMDA)
.SH SYNOPSIS
\f3$PCP_PMDAS_DIR/btrfs/pmdabtrfs\f1
[\f3\-D\f1 \f2debug\f1]
[\f3\-d\f1 \f2domain\f1]
[\f3\-l\f1 \f2logfile\f1]
.SH DESCRIPTION
.B pmdabtrfs
is a Performance Metrics Domain Agent (PMDA) which extracts
performance metrics from the btrfs filesystem via sysfs
.RB ( /sys/fs/btrfs ).
.PP
The
.B btrfs
PMDA exports metrics covering filesystem information
(label, sizes, generation, checksum algorithm),
transaction commit statistics,
space allocation for data, metadata and system block groups,
per-device error statistics,
and async discard statistics.
.PP
Metrics are organized into two instance domains: one for
btrfs filesystems (keyed by UUID) and one for devices
(keyed by UUID::devid).
Labels are provided for each instance, including the
filesystem UUID, label, and device ID where applicable.
.PP
A brief description of the
.B pmdabtrfs
command line options follows:
.TP 5
.B \-d
The performance metrics
.I domain
number must be set to a unique value.
.TP
.B \-l
Location of the log file.
By default, a log file named
.I btrfs.log
is written in the current directory of
.BR pmcd (1)
when
.B pmdabtrfs
is started, i.e.
.BR $PCP_LOG_DIR/pmcd .
If the log file cannot
be created or is not writable, output is written to the standard error instead.
.SH INSTALLATION
The btrfs PMDA requires a Linux system with one or more mounted
btrfs filesystems.
The PMDA reads statistics from sysfs and does not require root privileges.
.PP
Install the PMDA using the Install script:
.PP
.ft CR
.nf
.in +0.5i
# cd $PCP_PMDAS_DIR/btrfs
# ./Install
.in
.fi
.ft 1
.PP
To remove the PMDA use the Remove script:
.PP
.ft CR
.nf
.in +0.5i
# cd $PCP_PMDAS_DIR/btrfs
# ./Remove
.in
.fi
.ft 1
.SH DEBUGGING OPTIONS
The
.B \-D
or
.B \-\-debug
option enables the output of additional diagnostics on
.I stderr
to help triage problems, although the information is sometimes cryptic and
primarily intended to provide guidance for developers rather end-users.
.I debug
is a comma separated list of debugging options; use
.BR pmdbg (1)
with the
.B \-l
option to obtain
a list of the available debugging options and their meaning.
.PP
Debugging options specific to
.B pmdabtrfs
are as follows:
.TS
box;
lf(B) | lf(B)
lf(B) | lf(R) .
Option	Description
_
appl0	warn if the btrfs sysfs directory cannot be found
.TE
.SH ENVIRONMENT
The
.B BTRFS_PATH
environment variable can be set to override the default
sysfs path
.RB ( /sys/fs/btrfs )
for testing purposes.
.SH SEE ALSO
.BR PCPIntro (1),
.BR pmcd (1),
.BR pcp.conf (5)
and
.BR pcp.env (5).

.\" control lines for scripts/man-spell
.\" +ok+ pmdabtrfs btrfs sysfs devid UUID