.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IOSTAT2PCP 1"
.TH IOSTAT2PCP 1 "Performance Co-Pilot" "3.9.10" "Performance Co-Pilot"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
iostat2pcp \- Import iostat data and create a PCP archive
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBiostat2pcp\fR [\fB\-v\fR] [\fB\-S\fR \fIstart\fR] [\fB\-t\fR \fIinterval\fR] [\fB\-Z\fR \fItimezone\fR] \fIinfile\fR \fIoutfile\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBiostat2pcp\fR reads a text file created with
\&\fBiostat\fR(1) (\fIinfile\fR) and translates this into a Performance
Co-Pilot (\s-1PCP\s0) archive with the basename \fIoutfile\fR.
If \fIinfile\fR is \*(L"\-\*(R" then \fIiostat2pcp\fR reads for
standard input, allowing easy preprocessing of the \fIiostat\fR(1) output
with \fIsed\fR(1) or similar.
.PP
The resultant \s-1PCP\s0 archive may be used with all the \s-1PCP\s0 client tools
to graph subsets of the data using \fBpmchart\fR(1),
perform data reduction and reporting, filter with
the \s-1PCP\s0 inference engine \fBpmie\fR(1), etc.
.PP
A series of physical files will be created with the prefix \fIoutfile\fR.
These are \fIoutfile\fR\fB.0\fR (the performance data),
\&\fIoutfile\fR\fB.meta\fR (the metadata that describes the performance data) and
\&\fIoutfile\fR\fB.index\fR (a temporal index to improve efficiency of replay
operations for the archive).  If any of these files exists already,
then \fBiostat2pcp\fR will \fBnot\fR overwrite them and will exit with an error
message.
.PP
The first output sample from \fIiostat\fR(1) contains a statistical summary
since boot time and is ignored by \fIiostat2pcp\fR, so the first real data
set is the second one in the \fIiostat\fR(1) output.
.PP
The best results are obtained when \fIiostat\fR(1) was run with its own \fB\-t\fR
flag, so each output sample is prefixed with a timestamp.  Even better
is \fB\-t\fR with $\fBS_TIME_FORMAT=ISO\fR set in environment when \fIiostat\fR(1)
is run, in which case the timestamp includes the timezone.
.PP
Note that if $\fBS_TIME_FORMAT=ISO\fR is \fBnot\fR used with the \fB\-t\fR option
then \fIiostat\fR(1) may produce a timestamp controlled by \fB\s-1LC_TIME\s0\fR from
the locale that is in a format \fIiostat2pcp\fR cannot parse.  The formats
for the timestamp that \fIiostat2pcp\fR accepts are illustrated by these
examples:
.IP "\fB2013\-07\-06T21:34:39+1000\fR" 4
.IX Item "2013-07-06T21:34:39+1000"
(for the $\fBS_TIME_FORMAT=ISO\fR).
.IP "\fB2013\-07\-06 21:34:39\fR" 4
.IX Item "2013-07-06 21:34:39"
(for some of the European formats, e.g. de_AT,
de_BE, de_LU and en_DK.utf8).
.IP "\fB06/07/13 21:34:39\fR" 4
.IX Item "06/07/13 21:34:39"
(for all of the $\fB\s-1LC_TIME\s0\fR 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).
.PP
In particular, note that some common North American $\fB\s-1LC_TIME\s0\fR settings will
\&\fBnot\fR work with \fIiostat2pcp\fR (namely, en_US, \s-1POSIX\s0 and C) because they
use the \s-1MM/DD\s0 format which may be incorrectly converted with the
assumed \s-1DD/MM\s0 format.  This is another reason to recommend setting
$\fBS_TIME_FORMAT=ISO\fR.
.PP
If there are no timestamps in the input stream, \fIiostat2pcp\fR will
try and deduce the sample interval if basic Disk data (\fB\-d\fR
option for \fIiostat\fR(1)) is found.  If this fails, then the \fB\-t\fR option may be
used to specify the sample \fIinterval\fR in seconds.
This option is ignored if timestamps are found in the input stream.
.PP
The \fB\-S\fR option may be used to specify as start time for the
first real sample in \fIinfile\fR, where \fIstart\fR must have the format
\&\s-1HH:MM:SS.\s0
This option is ignored if timestamps are found in the input stream.
.PP
The \fB\-Z\fR option may be used to specify a timezone.  It must have the
format +HHMM (for hours and minutes East of \s-1UTC\s0) or \-HHMM (for hours
and minutes West of \s-1UTC\s0).  Note in particular that \fBneither\fR the \fBzoneinfo\fR
(aka Olson) format, e.g. Europe/Paris, nor the Posix \fB\s-1TZ\s0\fR format, e.g.
\&\s-1EST+5\s0 is allowed for the \fB\-Z\fR option.
This option is ignored if \s-1ISO\s0 timestamps are found in the input stream.
If the timezone is not specified and cannot be deduced, it defaults to
\&\*(L"\s-1UTC\*(R".\s0
.PP
Some additional diagnostic output is generated with the \fB\-v\fR option.
.PP
\&\fBiostat2pcp\fR is a Perl script that uses the PCP::LogImport Perl wrapper
around the \s-1PCP \s0\fIlibpcp_import\fR
library, and as such could be used as an example to develop new
tools to import other types of performance data and create \s-1PCP\s0 archives.
.SH "CAVEAT"
.IX Header "CAVEAT"
\&\fBiostat2pcp\fR requires \fIinfile\fR to have been created by the version
of \fBiostat\fR(1) from
<http://freshmeat.net/projects/sysstat>.
.PP
\&\fBiostat2pcp\fR handles the \fB\-c\fR (\s-1CPU\s0), \fB\-d\fR (Disk), \fB\-x\fR (eXtended
Disk) and \fB\-p\fR (Partition) report formats (including their \fB\-k\fR, \fB\-m\fR,
\&\fB\-z\fR and
\&\fB\s-1ALL\s0\fR variants), but does not accommodate the \fB\-n\fR (Network Filesystem)
report format from \fBiostat\fR(1); this is a demand-driven limitation rather
than a technical limitation.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBDate::Format\fR(3pm),
\&\fBDate::Parse\fR(3pm),
\&\fBiostat\fR(1),
\&\fB\s-1LOGIMPORT\s0\fR(3),
\&\fBPCP::LogImport\fR(3pm),
\&\fBpmchart\fR(1),
\&\fBpmie\fR(1),
\&\fBpmlogger\fR(1) and
\&\fBsed\fR(1).