NAME

AProf - is a profiler for periodically running processes

VERSION

0.6

SYNOPSIS

 use AProf;

 use AProf logfile => '/path/to/logfile';

 use AProf logfile => '/path/to/logfile',
            recursive => 1;

 use AProf logfile => 'STDOUT';

 use AProf logfile => 'NULL';

 my $report = AProf::full_log();

DESCRIPTION

This module is assigned for receiving statistics from periodically running perl-programms when it is difficult to organize many test starts for them.

For using this profiler one should include into tested modules the directive:

 use AProf;

The module will calculate the run time of each function of a tested module and after finishing it will create a report in the logfile. If the logfile isn't defined then STDERR is used.

The following variants may be used as logfile:

'STDOUT' or 'STDERR'

To create a report in STDOUT or STDERR (the latter is used on default).

'NULL'

Not to create a report anywhere (similarly to /dev/null).

file_name

To add a report into the file with the stated name (the main usage).

You may write a report by yourself (for example if You want to keep it in data base and not in a file). In this case You should set 'NULL' in the logfile and receive a report by calling the function:

 my $report = AProf::full_log();

Note: AProf controls the operating time of functions included in the module which it uses.

Other modules are not controlled. Other profiles usually allow to control them also. In order to make AProf controlling all the used modules You should use the option recursive => 1 as it is shown in examples above.

Note: Remember that at recursive control the interception of some functions is rather difficult or impossible. For example there are some problems when setting hooks on AUTOLOAD functions etc. The list of modules and functions excluded from control can be found in the beginning of AProf.pm file in SKIP_MODULES and SKIP_FUNCTIONS arrays.

PROFILE FORMAT

When first writing into the file (a new report file) and also when calling the function Aprof::full_log in the very beginning there's produced two lines of a headline with a description of the meaning of report fields. The information is outputted into few columns:

Function

The name of the function which was controlled by the profiler.

calls

The number of calls of the function during the whole working time.

average

The average time needed for a single function performance.

max

Maximum time of the performance of this function.

min

Minimum time of the performance of this function.

Before writing of a next data portion there's inserted a temporary label like '** Profiled at 2008-12-10 12:32:37 **' into the log; the logs' parser may use such labels for creating the diagrams of the dependence of the function's run time from the current time, time of the day etc.

When writing a report into the log there isn't generated a record about those functions which have been never called during the work of the profiler. However the function AProf::full_log includes into the report all the controlled functions.

Parsing of logs.

For parsing logs and receiving the summary info from the profiler use the module AProf::EasyParser.

Example: perl -MAProf::EasyParser -e 'print aprof_report("filename.log")'

LICENSE

This profiler 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 3 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.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

AUTHOR

Copyright (C) 2008 Dmitry E. Oboukhov <unera@debian.org>

cpanm AProf

perl -MCPAN -e shell
install AProf