Skip to content

start:

write-calc-doc.pl

The Perl script write-calc-doc.pl transforms a log file into a Calc document containing two data sheets for every thread. The first sheet displays a pretty printed version of the raw data. The second sheet is made up by a table that contains for each function or other scope the minimal, maximal, average, and total time and the number of calls.

Synopsis

write-calc-doc.pl <log-file-name> [<calc-document-name>]

The two arguments specify the name of the log-file to process and an optional name under which to write the report. If that name is not given explicetly, then it is derived from the log-file name by replacing the suffix .log by the suffix .sxc.

write-calc-doc.pl understands the following option parameters that may stand anywhere on the command line (but of course behind the script name):

  • -h prints a short help text describing the command line parameters.

  • -i <filename> specifies a file that contains regular expressions (in Perl style). Every time stamp in the log file that matches at least one of these expressions is included into the report.

  • -e <filename> specifies a file that contains regular expressions (in Perl style). Every time stamp in the log file that matches at least one of these expressions is not included into the report.

Configuration

There are several configuration features which the script tries to determine automatically. If that fails you have to specify them explicitly:

  • If the perl interpreter is not found you have to specify it on the command line: use <perl-path>/perl write-calc-doc.pl <arguments> instead of write-calc-doc.pl <arguments>.

  • The Perl script uses several modules in the sub-directory LogFile. If that sub-directory is not in your Perl search path and can't be deduced automatically from the script's own name then you have to pass that directory with the -I command line option to the perl interpreter: use <perl-path>/perl -I<src-path>/tools/contrib/profiling write-calc-doc.pl <arguments>.

  • A zip executable is used to pack all XML files into a single archive. If no zip executable with the base name „zip“ is found in the current search path, then you have to set the environment variables LOG_FILE_ZIP_COMMAND to the path name of the zip executable. The variable LOG_FILE_ZIP_FLAGS can be used to control it's behaviour.

Usually it should be sufficient to say

<src-path>/tools/contrib/profiling/write-calc-document.pl /tmp/profiling_1234.log

It creates the Calc document /tmp/profiling_1234.sxc.

Filtering the log file

On the command line you can specify two files with regular expressions. These expressions are used to filter the time stamps in the log file. A time stamp is taken into account for the report generation if it a) matches at least one regular expression in the inclusion filter file or that file is empty and b) matches none of the regular expressions in the exclusion filter file or that file is empty. The expressions in the filter files have to be written in the Perl syntax.

Filter Examples

An inclusion filter file containing only the line

\(af119097\)

includes exactly those time stamps into the report that belong the author with Sun id af119097.

An exclusion filter file containing only the line

^sch\b

removes all time stamps from the report that belong to the chart project.

Further documentation

Follow the links below to the documentation contained in the Perl scripts write-calc-document.pl and the modules loaded by it. It has been created by running pod2html on the script files.

References

For writing filters suitable for a given task you should have a look at the specification of the general time stamp format and the documentation of the time stamps emitted from the individual projects.