'\"macro stdmacro
.\"
.\" Copyright (c) 2012-2013 Red Hat.
.\" Copyright (c) 2010 Ken McDonell.  All Rights Reserved.
.\" 
.\" 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 SAR2PCP 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3sar2pcp\f1 \- import sar data and create a PCP archive
.SH SYNOPSIS
\f3sar2pcp\f1 \fIinfile\fR \fIoutfile\fR
.SH DESCRIPTION
\&\fBsar2pcp\fR is intended to read a binary System Activity Reporting
(sar) data file
as created by \fBsadc\fR(1) (\fIinfile\fR) and translate this into a Performance
Co-Pilot (\s-1PCP\s0) archive with the basename \fIoutfile\fR.
.PP
However, if \fIinfile\fR has the suffix ``.xml'', then it will be considered
already in \s-1XML\s0 format and \fBsar2pcp\fR will operate directly on it.
.PP
The resultant \s-1PCP\s0 achive 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 \fBsar2pcp\fR will \fBnot\fR overwrite them and will exit with an error
message of the form
.PP
_\|_pmLogNewFile: ``blah.0'' already exists, not over-written
.PP
\&\fBsar2pcp\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.
A Python wrapper module is also available.
.SH "CAVEATS"
.IX Header "CAVEATS"
When not using the \s-1XML\s0 input option, \fBsar2pcp\fR requires \fIinfile\fR to
have been created by a version of \fBsadc\fR(1) from
<http://sebastien.godard.pagesperso\-orange.fr/>
which includes the \fBsadf\fR(1) utility
to translate \fIinfile\fR into an \s-1XML\s0 stream (any since version 6);
\&\fBsar2pcp\fR will automatically run \fBsadf\fR(1) and translate the resultant
\&\s-1XML\s0 into a \s-1PCP\s0 archive.
.PP
When using binary \fBsadc\fR files
it is important to ensure the installed \fBsadf\fR is compatible with the
version of \fBsadc\fR that originally generated the binary files.  Simply
assuming a newer installed version will work is unfortunately far too
optimistic, and nor should one assume that binary data from different
platforms (e.g. different endianness) will work \- these issues are due
to limitations in \fBsadc\fR and \fBsadf\fR, and not in \fBsar2pcp\fR itself.
.PP
Fortunately, the \fBsadf\fR message indicating that an incompatibility has
been detected is consistent across versions, and is always prefixed
.PP
Invalid system activity file
.PP
Using an \s-1XML\s0 \fIinfile\fR has the advantage that the installed version
of \fBsadf\fR is completely bypassed.  \fBsar2pcp\fR undertakes to transform
any valid \s-1XML\s0 produced by any of the different variations of \fBsadf\fR
into a valid \s-1PCP\s0 archive.  Any version of \s-1PCP\s0 will be able to interpret
the archive files produced by any version of \fBsar2pcp\fR, and you are
also free to move the binary \s-1PCP\s0 archive between different platforms,
different hardware, even different operating systems \- it Just Works (\s-1TM\s0).
.SH "PCP ENVIRONMENT"
Environment variables with the prefix
.B PCP_
are used to parameterize the file and directory names
used by PCP.
On each installation, the file
.I /etc/pcp.conf
contains the local values for these variables.
The
.B $PCP_CONF
variable may be used to specify an alternative
configuration file,
as described in
.BR pcp.conf (5).
.SH SEE ALSO
.BR pmie (1),
.BR pmchart (1),
.BR pmlogger (1),
.BR pmlogextract (1),
.BR pmlogsummary (1),
.BR sadc (1),
.BR sadf (1),
.BR sar (1),
.BR Date::Parse (3pm),
.BR Date::Format (3pm),
.BR PCP::LogImport (3pm),
.BR XML::TokeParser (3pm)
and
.BR LOGIMPORT (3).