.TH mmpmon 02/16/06
mmpmon Command
.SH "Name"
.PP
\fBmmpmon\fR - Manages performance monitoring and displays
performance information.
.SH "Synopsis"
.PP
\fBmmpmon\fR [\fB-i\fR \fICommandFile\fR]
[\fB-d\fR \fIIntegerDelayValue\fR] [\fB-p\fR]
[\fB-r\fR \fIIntegerRepeatValue\fR] [\fB-s\fR]
[\fB-t\fR \fIIntegerTimeoutValue\fR]
.SH "Description"
.PP
Before attempting to use \fBmmpmon\fR, IBM suggests that you
review this command entry, then read the entire chapter,
\fIMonitoring GPFS I/O performance with the mmpmon
command\fR in
\fIGeneral Parallel File
System: Advanced Administration Guide\fR.
.PP
Use the \fBmmpmon\fR command to manage GPFS performance monitoring
functions and display performance monitoring data. The \fBmmpmon\fR
command reads requests from an input file or standard input (stdin), and
writes responses to standard output (stdout). Error messages go to
standard error (stderr). Prompts, if not suppressed, go to
stderr.
.PP
When running \fBmmpmon\fR in such a way that it continually reads input
from a pipe (the driving script or application never intends to send an
end-of-file to \fBmmpmon\fR), set the \fB-r\fR option value to 1 (or use
the default value of 1) to prevent \fBmmpmon\fR from caching the input
records. This avoids unnecessary memory consumption.
.PP
\fBResults\fR
.PP
The performance monitoring request is sent to the GPFS daemon running on
the same node that is running the \fBmmpmon\fR command.
.PP
All results from the request are written to stdout.
.PP
There are two output formats:
.RS +3
.HP 3
\(bu Human readable, intended for direct viewing.
.sp
In this format, the results are keywords that describe the value presented,
followed by the value. For example: 
.sp
.nf
disks: 2
.fi
.sp
.HP 3
\(bu Machine readable, an easily parsed format intended for further analysis by
scripts or applications.
.sp
In this format, the results are strings with values presented as
keyword/value pairs. The keywords are delimited by underscores (_) and
blanks to make them easier to locate.
.RE
.PP
For details on how to interpret the \fBmmpmon\fR command results,
see
\fIMonitoring GPFS I/O performance with the
mmpmon command\fR in
\fIGeneral
Parallel File System: Advanced Administration
Guide\fR.
.SH "Parameters"
.PP
.RS +3
\fB-i \fICommandFile\fR
\fR
.RE
.RS +9
The input file contains \fBmmpmon\fR command requests, one per
line. Use of the \fB-i\fR flag implies use of the \fB-s\fR
flag. For interactive use, just omit the \fB-i\fR flag. In
this case, the input is then read from stdin, allowing \fBmmpmon\fR to take
keyboard input or output piped from a user script or application
program. 
.PP
Leading blanks in the input file are ignored. A line beginning with
a pound sign (#) is treated as a comment. Leading blanks in a line
whose first non-blank character is a pound sign (#) are ignored.
.PP
This table describes the \fBmmpmon\fR requests.
.br
.PP
\fBTable 7. Input requests to the mmpmon command\fR
.br
.sp
.RS +0.1i
.nf
.TS
tab(~);
 l l.
Request                             Description
--------------------------------------------------------
fs_io_s                 Display I/O statistics
                        per mounted file system
io_s                    Display I/O statistics
                        for the entire node
nlist add \fIname\fR[\fIname\fR...] Add node names to a list 
                        of nodes for processing
nlist del               Delete a node list
nlist new \fIname\fR[\fIname\fR...] Create a new node list
nlist s                 Show the contents of the
                        current node list
nlist sub \fIname\fR[\fIname\fR...] Delete node names from a
                        list of nodes for processing 
once \fIrequest\fR            Indicates that the request 
                        is to be performed only once
reset                   Reset statistics to zero
rhist nr                Change the request histogram
                        facility request size and 
                        latency ranges
rhist off               Disable the request histogram
                        facility. This is the default.
rhist on                Enable the request histogram
                        facility
rhist p                 Display the request histogram
                        facility pattern
rhist reset             Reset the request histogram
                        facility data to zero
rhist s                 Display the request histogram
                        facility statistics values
source \fIfilename\fR         Read \fBmmpmon\fR requests from
                        a file
ver                     Display \fBmmpmon\fR version
.TE
.sp
.fi
.RE
.RE
.SH "Options"
.PP
.RS +3
\fB-d \fIIntegerDelayValue\fR
\fR
.RE
.RS +9
Specifies a number of milliseconds to sleep after one invocation of all
the requests in the input file. The default value is 1000. This
value must be an integer greater than or equal to 500 and less than or equal
to 8000000.
.PP
The input file is processed as follows: The first request is
processed, it is sent to the GPFS daemon, the responses for this request are
received and processed, the results for this request are displayed, and then
the next request is processed and so forth. When all requests from the
input file have been processed once, the \fBmmpmon\fR command sleeps for
the specified number of milliseconds. When this time elapses,
\fBmmpmon\fR wakes up and processes the input file again, depending on the
value of the \fB-r\fR flag.
.RE
.PP
.RS +3
\fB-p
\fR
.RE
.RS +9
Indicates to generate output that can be parsed by a script or
program. If this option is not specified, human readable output is
produced.
.RE
.PP
.RS +3
\fB-r \fIIntegerRepeatValue\fR
\fR
.RE
.RS +9
Specifies the number of times to run all the requests in the input
file. 
.PP
The default value is one. Specify an integer between zero and
8000000. Zero means to run forever, in which case processing continues
until it is interrupted. This feature is used, for example, by a
driving script or application program that repeatedly reads the result from a
pipe.
.PP
The \fBonce\fR prefix directive can be used to override the
\fB-r\fR flag. See the description of \fBonce\fR in
\fIMonitoring GPFS I/O performance with the mmpmon
command\fR in
\fIGeneral Parallel File
System: Advanced Administration Guide\fR.
.RE
.PP
.RS +3
\fB-s
\fR
.RE
.RS +9
Indicates to suppress the prompt on input. 
.PP
Use of the \fB-i\fR flag implies use of the \fB-s\fR flag. For
use in a pipe or with redirected input (<), the \fB-s\fR flag is
preferred. If not suppressed, the prompts go to standard error
(stderr).
.RE
.PP
.RS +3
\fB-t \fIIntegerTimeoutValue\fR
\fR
.RE
.RS +9
Specifies a number of seconds to wait for responses from the GPFS daemon
before considering the connection to have failed. 
.PP
The default value is 60. This value must be an integer greater than
or equal to 1 and less than or equal to 8000000.
.RE
.SH "Exit status"
.PP
.PP
.RS +3
\fB0
\fR
.RE
.RS +9
Successful completion.
.RE
.PP
.RS +3
\fB1
\fR
.RE
.RS +9
Various errors (insufficient memory, input file not found, incorrect
option, and so forth).
.RE
.PP
.RS +3
\fB3
\fR
.RE
.RS +9
Either no commands were entered interactively, or there were no
\fBmmpmon\fR commands in the input file. The input file was empty,
or consisted of all blanks or comments.
.RE
.PP
.RS +3
\fB4
\fR
.RE
.RS +9
\fBmmpmon\fR terminated due to a request that was not valid.
.RE
.PP
.RS +3
\fB5
\fR
.RE
.RS +9
An internal error has occurred.
.RE
.PP
.RS +3
\fB111
\fR
.RE
.RS +9
An internal error has occurred. A message will follow.
.RE
.PP
\fBRestrictions\fR
.RS +3
.HP 3
1. Up to five instances of \fBmmpmon\fR may be run on a given node
concurrently. However, concurrent users may interfere with each
other. See
\fIMonitoring GPFS I/O
performance with the mmpmon command\fR in
\fIGeneral Parallel File System: Advanced
Administration Guide\fR.
.HP 3
2. Do not alter the input file while \fBmmpmon\fR is running.
.HP 3
3. The input file must contain valid input requests, one per line.
When an incorrect request is detected by \fBmmpmon\fR, it issues an error
message and terminates. Input requests that appear in the input file
before the first incorrect request are processed by \fBmmpmon\fR.
.RE
.SH "Security"
.PP
The \fBmmpmon\fR command must be run by a user with root authority, on
the node for which statistics are desired.
.SH "Examples"
.RS +3
.HP 3
1. Assume that \fBinfile\fR contains these requests:
.sp
.nf
ver
io_s
fs_io_s
rhist off
.fi
.sp
and this command is issued:
.sp
.nf
mmpmon -i infile -r 10 -d 5000
.fi
.sp
The output (sent to stdout) is similar to this:
.sp
.nf
mmpmon node 192.168.1.8 name node1 version 3.1.0
mmpmon node 192.168.1.8 name node1 io_s OK
timestamp:      1083350358/935524
bytes read:              0
bytes written:           0
opens:                   0
closes:                  0
reads:                   0
writes:                  0
readdir:                 0
inode updates:           0
mmpmon node 192.168.1.8 name node1 fs_io_s status 1
no file systems mounted
mmpmon node 192.168.1.8 name node1 rhist off OK
.fi
.sp
.sp
The requests in the input file are run 10 times, with a delay of 5000
milliseconds (5 seconds) between invocations.
.HP 3
2. Here is the previous example with the \fB-p\fR flag:
.sp
.nf
mmpmon -i infile -p -r 10 -d 5000
.fi
.sp
The output (sent to stdout) is similar to this:
.sp
.nf
_ver_ _n_ 192.168.1.8 _nn_ node1 _v_ 2 _lv_ 3 _vt_ 0
_io_s_ _n_ 192.168.1.8 _nn_ node1 _rc_ 0 _t_ 1084195701 _tu_ 350714 _br_ 0 _bw_ 0 _oc_ 0
     _cc_ 0 _rdc_ 0 _wc_ 0 _dir_ 0 _iu_ 0
_fs_io_s_ _n_ 192.168.1.8 _nn_ node1 _rc_ 1 _t_ 1084195701 _tu_ 364489 _cl_ - _fs_ -_rhist_\ 
     _n_ 192.168.1.8 _nn_ node1 _req_ off _rc_ 0 _t_ 1084195701 _tu_ 378217
.fi
.sp
.HP 3
3. This is an example of \fBfs_io_s\fR with a mounted file system:
.sp
.nf
mmpmon node 198.168.1.8 name node1 fs_io_s OK
cluster: node1.localdomain
filesystem: gpfs1
disks: 1
timestamp: 1093352136/799285
bytes read: 52428800
bytes written: 87031808
opens: 6
closes: 4
reads: 51
writes: 83
readdir: 0
inode updates: 11
mmpmon node 198.168.1.8 name node1 fs_io_s OK
cluster: node1.localdomain
filesystem: gpfs2
disks: 2
timestamp: 1093352136/799285
bytes read: 87031808
bytes written: 52428800
opens: 4
closes: 3
reads: 12834
writes: 50
readdir: 0
inode updates: 9
.fi
.sp
.HP 3
4. Here is the previous example with the \fB-p\fR flag:
.sp
.nf
_fs_io_s_ _n_ 198.168.1.8 _nn_ node1 _rc_ 0 _t_ 1093352061 _tu_ 93867 _cl_ node1.localdomain
 _fs_ gpfs1 _d_ 1 _br_ 52428800 _bw_ 87031808 _oc_ 6 _cc_ 4 _rdc_ 51 _wc_ 83 _dir_ 0 _iu_ 10
_fs_io_s_ _n_ 198.168.1.8 _nn_ node1 _rc_ 0 _t_ 1093352061 _tu_ 93867 _cl_ node1.localdomain
  _fs_ gpfs2 _d_ 2 _br_ 87031808 _bw_ 52428800 _oc_ 4 _cc_ 3 _rdc_ 12834 _wc_ 50 _dir_ 0 _iu_ 8
.fi
.sp
This output consists of two strings.
.HP 3
5. This is an example of \fBio_s\fR with a mounted file system:
.sp
.nf
mmpmon node 198.168.1.8 name node1 io_s OK
timestamp: 1093351951/587570
bytes read: 139460608
bytes written: 139460608
opens: 10
closes: 7
reads: 12885
writes: 133
readdir: 0
inode updates: 14
.fi
.sp
.HP 3
6. Here is the previous example with the \fB-p\fR flag:
.sp
.nf
_io_s_ _n_ 198.168.1.8 _nn_ node1 _rc_ 0 _t_ 1093351982 _tu_ 356420 _br_ 139460608\ 
 _bw_ 139460608 _oc_ 10 _cc_ 7 _rdc_ 0 _wc_ 133 _dir_ 0 _iu_ 14
.fi
.sp
This output consists of one string.
.RE
.PP
For several more examples, see
\fIMonitoring GPFS I/O performance with the mmpmon
command\fR in
\fIGeneral Parallel File
System: Advanced Administration Guide\fR.
.SH "Location"
.PP
\fB/usr/lpp/mmfs/bin\fR
.PP