# pcp-tapestat

## NAME



           **pcp-tapestat** - report tape I/O statistics
    


## SYNOPSIS



           **pcp**[_pcp options_] **tapestat**[**-u?**]  [**-G** _method_] [**-P** _precision_] [**-R**
           _pattern_] [**-x**[t][,h][,noidle]]
    


## DESCRIPTION



           **pcp-tapestat** reports I/O statistics for tape devices.
    


## OPTIONS



           When invoked via the pcp(1) command, the _pcp options_ **-A** /**--align** ,
           **-a** /**--archive** , **-h** /**--host** , **-O** /**--origin** , **-S** /**--start** , **-s** /**--samples** ,
           **-t** /**--interval** , **-T** /**--finish** , **-V** /**--version** , **-Z** /**--timezone** and
           **-z** /**--hostzone** become indirectly available; refer to PCPIntro(1)
           for a complete description of these options.
    
           The additional command line options available for **pcp-tapestat**
           are:
    
           **-G** _method_ , **--aggregate** =_method_
                Specifies that statistics for device names matching the
                regular expression specified with the **-R** _regex_ option should
                be aggregated according to _method_.  Note this is aggregation
                based on matching device names (not temporal aggregation).
                When **-G** is used, the device name column is reported as
                _method_(_regex_), e.g.  if **-G sum -R 'st(0|1)$'** is specified,
                the device column will be **sum**(**st(0|1)$)** and summed statistics
                for **st0** and **st1** will be reported in the remaining columns.
                If **-G** is specified but **-R** is not specified, then the default
                _regex_ is **.*** , i.e. matching all device names.  If _method_ is
                **sum** then the statistics are summed.  If _method_ is **avg** then
                the statistics are summed and then averaged by dividing by
                the number of matching device names.  If _method_ is **min** or
                **max** , the minimum or maximum statistics for matching devices
                are reported, respectively.
    
           **-P** _N_ , **--precision** =_N_
                This indicates the precision (number of decimal places) to
                report.  The default precision _N_ may be set to something
                other than the default (2).  Note that the **avgrq-sz** and
                **avgqu-sz** fields are always reported with _N_ +1 decimals of
                precision.  These fields typically have values less than 1.
    
           **-R** _pattern_ , **--regex** =_pattern_
                This restricts the report to device names matching a regular
                expression _pattern_.  The given _pattern_ is searched as a perl
                style regular expression, and will match any portion of a
                device name.  e.g. '^st[0-9]+' will match all device names
                starting with 'st' followed by one or more numbers.  e.g.
                '^st(0|1)$' will only match 'st0' and 'st1'.  e.g. 'st0$'
                will match 'st0' but not 'st1'.  See also the **-G** option for
                aggregation options.
    
           **-u** , **--no-interpolation**
                When replaying a set of archives, by default values are
                reported according to the requested sample interval (**-t**
                option), not according to the actual interval recorded in the
                archive(s).  Without this option PCP interpolates the values
                to be reported based on the records in the set of archives,
                which is particularly useful when the **-t** option is used to
                replay a set of archives with a longer sampling interval than
                that with which the archive(s) was originally recorded with.
                With the **-u** option, uninterpolated reporting is enabled -
                every value is reported according to the native recording
                interval in the set of archives.  When the **-u** option is
                specified, the **-t** option makes no sense and is incompatible
                because the replay interval is always the same as the
                recording interval in the set of archive.  In addition, **-u**
                only makes sense when replaying archives, see the **-a** option
                on PCPIntro(1), and so if **-u** is specified then **-a** must also
                be specified.
    
           **-V** , **--version**
                Display version number and exit.
    
           **-x** _comma-separated-options_
                Specifies a comma-separated list of one or more extended
                reporting options as follows:
                **t** - prefix every line in the report with a timestamp in
                _ctime_(3) format,
                **h** - omit the heading, which is otherwise reported every 24
                samples,
                **noidle** - Do not display statistics for idle devices.
    
           **-?** , **--help**
                Display usage message and exit.
    


## REPORT



           The columns in the **pcp-tapestat** report have the following
           interpretation:
    
           **Timestamp**
                  When the **-x t** option is specified, this column is the
                  timestamp in ctime(3) format.
    
           **Device** Specifies the tape device name.  When **-G** is specified, this
                  is replaced by the aggregation method and regular
                  expression - see the **-G** and **-R** options above.
    
           **r/s** The number of reads issued expressed as the number per
                  second averaged over the interval.
    
           **w/s** The number of writes issued expressed as the number per
                  second averaged over the interval.
    
           **kb_r/s** The amount of data read expressed in kilobytes per second
                  averaged over the interval.
    
           **kb_w/s** The amount of data written expressed in kilobytes per
                  second averaged over the interval.
    
           **r_pct** Read percentage wait - the percentage of time over the
                  interval spent waiting for read requests to complete.  The
                  time is measured from when the request is dispatched to the
                  SCSI mid-layer until it signals that it completed.
    
           **w_pct** Write percentage wait - the percentage of time over the
                  interval spent waiting for write requests to complete.  The
                  time is measured from when the request is dispatched to the
                  SCSI mid-layer until it signals that it completed.
    
           **o_pct** Overall percentage wait - the percentage of time over the
                  interval spent waiting for any I/O request to complete
                  (read, write, and other).
    
           **Rs/s** The number of I/Os, expressed as the number per second
                  averaged over the interval, where a non-zero residual value
                  was encountered.
    
           **o_cnt** The  number of I/Os, expressed as the number per second
                  averaged over the interval, that were included as "other".
                  Other I/O includes ioctl calls made to the tape driver and
                  implicit operations performed by the tape driver such as
                  rewind on close (for tape devices that implement rewind on
                  close).  It does not include any I/O performed using
                  methods outside of the tape driver (e.g. via sg ioctls).
    


## PCP ENVIRONMENT



           Environment variables with the prefix **PCP_** are used to
           parameterize the file and directory names used by PCP.  On each
           installation, the file _/etc/pcp.conf_ contains the local values for
           these variables.  The **$PCP_CONF** variable may be used to specify an
           alternative configuration file, as described in pcp.conf(5).
    
           For environment variables affecting PCP tools, see
           pmGetOptions(3).
    


## DEBUGGING OPTIONS



           The **-D** or **--debug** pcp option enables the output of additional
           diagnostics on _stderr_ to help triage problems, although the
           information is sometimes cryptic and primarily intended to provide
           guidance for developers rather end-users.  _debug_ is a comma
           separated list of debugging options; use pmdbg(1) with the **-l**
           option to obtain a list of the available debugging options and
           their meaning.
    


* * *