# iostat2pcp

## NAME



           **iostat2pcp** - import iostat data and create a PCP archive
    


## SYNOPSIS



           **iostat2pcp**[**-v**] [**-S** _start_] [**-t** _interval_] [**-V** _version_] [**-Z**
           _timezone_] _infile outfile_
    


## DESCRIPTION



           **iostat2pcp** reads a text file created with iostat(1) (_infile_) and
           translates this into a Performance Co-Pilot (PCP) archive with the
           basename _outfile_.  If _infile_ is ``-'' then _iostat2pcp_ reads from
           standard input, allowing easy preprocessing of the iostat(1)
           output with sed(1) or similar.
    
           The resultant PCP archive may be used with all the PCP client
           tools to graph subsets of the data using pmchart(1), perform data
           reduction and reporting, filter with the PCP inference engine
           pmie(1), etc.
    
           A series of physical files will be created with the prefix
           _outfile_.  These are _outfile_**.0**(the performance data), _outfile_**.meta**
           (the metadata that describes the performance data) and
           _outfile_**.index**(a temporal index to improve efficiency of replay
           operations for the archive).  If any of these files exists
           already, then **iostat2pcp** will **not** overwrite them and will exit
           with an error message.
    
           The first output sample from iostat(1) contains a statistical
           summary since boot time and is ignored by _iostat2pcp_ , so the first
           real data set is the second one in the iostat(1) output.
    
           The best results are obtained when iostat(1) was run with its own
           **-t** flag, so each output sample is prefixed with a timestamp.  Even
           better is **-t** with $**S_TIME_FORMAT=ISO** set in environment when
           iostat(1) is run, in which case the timestamp includes the
           timezone.
    
           Note that if $**S_TIME_FORMAT=ISO** is **not** used with the **-t** option
           then iostat(1) may produce a timestamp controlled by **LC_TIME** from
           the locale that is in a format _iostat2pcp_ cannot parse.  The
           formats for the timestamp that _iostat2pcp_ accepts are illustrated
           by these examples:
    
           **2013-07-06T21:34:39+1000**
               (for the $**S_TIME_FORMAT=ISO**).
    
           **2013-07-06 21:34:39**
               (for some of the European formats, e.g. de_AT, de_BE, de_LU
               and en_DK.utf8).
    
           **06/07/13 21:34:39**
               (for all of the $**LC_TIME** settings for English locales outside
               North America, e.g. en_AU, en_GB, en_IE, en_NZ, en_SG and
               en_ZA, and all the Spanish locales, e.g. es_ES, es_MX and
               es_AR).
    
           In particular, note that some common North American $**LC_TIME**
           settings will **not** work with _iostat2pcp_ (namely, en_US, POSIX and
           C) because they use the MM/DD format which may be incorrectly
           converted with the assumed DD/MM format.  This is another reason
           to recommend setting $**S_TIME_FORMAT=ISO**.
    
           If there are no timestamps in the input stream, _iostat2pcp_ will
           try and deduce the sample interval if basic Disk data (**-d** option
           for iostat(1)) is found.  If this fails, then the **-t** option may be
           used to specify the sample _interval_ in seconds.  This option is
           ignored if timestamps are found in the input stream.
    
           The **-S** option may be used to specify as start time for the first
           real sample in _infile_ , where _start_ must have the format HH:MM:SS.
           This option is ignored if timestamps are found in the input
           stream.
    
           The **-V** option specifies the version for the output PCP archive.
           By default the archive version **$PCP_ARCHIVE_VERSION**(set to 3 in
           current PCP releases) is used, and the only values currently
           supported for _version_ are 2 or 3.
    
           The **-Z** option may be used to specify a timezone.  It must have the
           format +HHMM (for hours and minutes East of UTC) or -HHMM (for
           hours and minutes West of UTC).  Note in particular that **neither**
           the **zoneinfo**(aka Olson) format, e.g. Europe/Paris, nor the Posix
           **TZ** format, e.g.  EST+5 is allowed for the **-Z** option.  This option
           is ignored if ISO timestamps are found in the input stream.  If
           the timezone is not specified and cannot be deduced, it defaults
           to ``UTC''.
    
           Some additional diagnostic output is generated with the **-v** option.
    
           **iostat2pcp** is a Perl script that uses the PCP::LogImport Perl
           wrapper around the PCP _libpcp_import_ library, and as such could be
           used as an example to develop new tools to import other types of
           performance data and create PCP archives.
    


## OPTIONS



           The available command line options are:
    
           **-S** _start_
                Specify the _start_ time for the first sample.
    
           **-t** _interval_
                Specify the sample _interval_ in seconds.
    
           **-v** Print verbose output.
    
           **-Z** _timezone_
                Specify the _timezone_ to use, see above.
    


## CAVEATS



           **iostat2pcp** requires _infile_ to have been created by the version of
           iostat(1) from **http://freshmeat.net/projects/sysstat **.
    
           **iostat2pcp** handles the **-c**(CPU), **-d**(Disk), **-x**(eXtended Disk) and
           **-p**(Partition) report formats (including their **-k** , **-m** , **-z** and **ALL**
           variants), but does not accommodate the **-n**(Network Filesystem)
           report format from iostat(1); this is a demand-driven limitation
           rather than a technical limitation.
    


## 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).
    


* * *