er_archive - archive the associated application binaries and source for a Performance Analyzer experiment
er_archive [ –nqF ] [–[d|r] path] [–s option [–m regexp ] ] experiment-name
er_archive -V
er_archive copies application binaries and source into a Performance Analyzer experiment to make the experiment self-contained and portable.
When -s all or -s used is specified, sources and object files are archived. Source archives are required to perform experiment comparison when the profiled applications have source-level differences.
By default, binaries are archived automatically when an experiment is created. However, archiving does not occur in the following circumstances:
if the profiled application is terminated before it exits normally
if you are profiling a running process
if you explicitly disabled archiving when profiling (for example by using collect -A off)
In such cases, you must run er_archive explicitly on the same machine where the profiling data was recorded.
Archiving of experiment at collection time, especially for experiments with many descendant processes, can be very expensive. A better strategy is to collect the data with –A off, and later, when the profiling is done,archive the experiment using er_archive –s all. In this case all binaries and source files will be saved in the experiment.
If during the archiving you receive error messages that some binaries or source files are not found, then use an addpath directive to add the path for those files to the .er.rc file, and archive the experiment again. The archiving can be repeated as many times as necessary to archive all files.
Archiving should be done on the same machine as used to collect the experiment. If some files cannot be accessed from this machine (e.g. sources or object files), then additional archiving can be done using another machine that can access them, for example, the machine where the application was built.
Some Java applications store shared objects in jar files. By default, such shared objects are not automatically archived. To archive shared objects contained in jar files, you must include the addpath directive in an .er.rc file. The addpath directive should give the path to the jar file including the jar file itself. The .er.rc file should be saved in the user home directory or experiment parent directory.
By default, application source files are not archived into the experiment. Run er_archive -s all or er_archive -s used on each experiment before comparing experiments if you want to examine source-level differences. This also ensures that source files are available in the experiment even if original source files become modified or inaccessible.
er_archive -s reports which source files were not found. To archive files that could not be found, you should add the addpath and pathmap directives to an .er.rc file. See the er_print(1) man page for more details about addpath and pathmap.
You can set the environment variable SP_ARCHIVE_ARGS to cause archiving of sources to be done automatically when the experiment completes. The SP_ARCHIVE_ARGS environment variable can contain -s and -m arguments, as pairs of argument and options separated by one or more blanks. If more than one -s argument appears on the command line, the last one prevails. If -s is both passed on the command line, and set by the environment variable, the option from the environment variable prevails.
Note that if you enable automatic source archiving during data collection using either the SP_ARCHIVE_ARGS variable or using collect -A src or collect -A usedsrc, you should confirm that source files have been correctly resolved by running er_archive -s all or er_archive -s used.
Archive the named experiment only, not any of its descendants.
Do not write any warnings to stderr. Warnings are incorporated into the .archive file, and shown in the analyzer or er_print output.
Force writing or rewriting of .archive files. If –F is passed to er_archive, then er_archive will remove all archived files and recreate them, except in the following cases:
–n option is passed
–m option is passed
Experiment name is not the founder experiment, but a subexperiment
Experiment is an MPI experiment
No longer needed, and ignored if used.
Specify archiving of source files. The allowed values of option are:
Do not archive any source files
Archive all source, object, and .anc files that can be found.
Archive source, object and .anc files for functions against which data was recorded in the experiment, and that can be found.
If more than one -s argument is given on the command line, or specified in the environment variable, the specified option for all must be the same. If not, er_archive will exit with an error.
This option specifies the location of a common archive. The value is the absolute path path to a common archive, which is a directory that contains archived files. If the directory does not exist, then it will be created. Files are saved in the common archive directory, and a symbolic link is created in the experiment archive.
Environment variable SP_ARCHIVE_COMMON_DIR can be used to specify the location of the common archive. This can be very convenient if you use scripts to profile applications. The following is an example.
SP_ARCHIVE_COMMON_DIR=/export/CommonArchive export SP_ARCHIVE_COMMON_DIR /bin/sh run_profiling.sh # a script that invokes "collect" or "er_kernel" to profile applications
This option specifies the location of a common archive. The value is the relative path path to a common archive, which is a directory that contains archived files. If the directory does not exist, then it will be created. Files are saved in the common archive directory, and a symbolic link is created in the experiment archive.
Environment variable SP_ARCHIVE_COMMON_DIR can be used to specify the location of the common archive.This can be very convenient if you use scripts to profile applications. The following is an example.
SP_ARCHIVE_COMMON_DIR=./CommonArchive export SP_ARCHIVE_COMMON_DIR /bin/sh run_profiling.sh # a script that invokes "collect" or "er_kernel" to profile applications
Archive only those source, object, and .anc files as specified by the -s flag, and whose full pathname, as recorded in the executable or shared object, matches the given regex. For more information on regex, see the regex(5) man page.
Multiple –m arguments can be supplied on the command line or in the environment variable. A source file will be archived if it matches the expression from any of them.
Write version number information for er_archive and exit.
er_archive does not work on experiments recorded with earlier versions of the tools. If invoked on such experiments, a warning is printed. Use the version of er_archive from the release with which the experiment was recorded.
analyzer(1), collect(1), collector(1), er_print(1)
Performance Analyzer manual