/ 
Devel-NYTProf-1.12
River stage two • 36 direct dependents • 46 total dependents
/ Devel::NYTProf::Reader

NAME

Devel::NYTProf::Reader - Tranforms Devel::NYTProf output into comprehensive, easy to read reports in (nearly) arbitrary format.

SYNOPSIS

# This module comes with two scripts that implement it:
#
# nytprofhtml - create an html report with statistics highlighting
# nytprofcsv - create a basic comma delimited report
#
# They are in the bin directory of your perl path, so add that to your PATH.
#
# The csv script is simple, and really only provided as a starting point
# for creating other custom reports. You should refer to the html script
# for advanced usage and statistics.

# First run some code through the profiler to generate the nytprof database.
perl -d:NYTProf some_perl.pl

# To create an HTML report in ./profiler 
nytprofhtml

# To create a csv report in ./profiler 
nytprofcsv

# Or to generate a simple comma delimited report manually
use Devel::NYTProf::Reader;
my $reporter = new Devel::NYTProf::Reader('nytprof.out');

# place to store the output
$reporter->outputDir($file);

# set other options and parameters
$reporter->addRegexp('^\s*', ''); # trim leading spaces

# generate the report
$reporter->report();

# many configuration options exist.  See nytprofhtml, advanced example.

HISTORY

A bit of history and a shameless plug...

NYTProf stands for 'New York Times Profiler'. Indeed, this module was developed by The New York Times Co. to help our developers quickly identify bottlenecks in large Perl applications. The NY Times loves Perl and we hope the community will benefit from our work as much as we have from theirs.

Please visit http://open.nytimes.com, our open source blog to see what we are up to, http://code.nytimes.com to see some of our open projects and then check out htt://nytimes.com for the latest news!

DESCRIPTION

Devel::NYTProf is a speedy line-by-line code profiler for Perl, written in C. This module is a complex framework that processes the output file generated by Devel::NYTProf

It is capable of producing reports of arbitrary format and varying complexity.

Basically, for each line of code that was executed and reported, this module will provide the following statistics:

  • Total calls

  • Total time

  • Average time per call

  • Deviation of all of the above

  • Line number

  • Source code

Devel::NYTProf::Reader will process each source file that it can find in your @INC one-by-one. For each line it processes, it will preform transformation and output based instructions that you can optionally provide. The configuration is very robust, supporting variations in field ordering, pattern substitutions (like converting ascii spaces to html spaces), and user callback functions to give you total control.

CONSTRUCTOR

$reporter = Devel::NYTProf::Reader->new( );
$reporter = Devel::NYTProf::Reader->new( $FILE );

This method constructs a new Devel::NYTProf::Reader object, parses $FILE and return the new object. By default $FILE will evaluate to './nytprof.out'.

See: Devel::NYTProf for how the profiler works.

PARAMETERS

Numerous parameters can be set to modify the behavior of Devel::NYTProf::Reader. The following methods are provided:

$reporter->outputDir( $output_directory );

Set the directory that generated files should be placed in. [Default: .]

$reporter->addRegexp( $pattern, $replace );

Add a regular expression to the top of the pattern stack. Ever line of output will be run through each entry in the pattern stack.

For example, to replace spaces, < and > with html entities, you might do:

$reporter->addRegexp(' ', '&nbsp;');
$reporter->addRegexp('<', '&lt;');
$reporter->addRegexp('>', '&gt;');
$reporter->setParam( $parameter, $value );

Changes the internal value of $parameter to $value. If $value is omitted, returns the current value of parameter.

Basic Parameters:

Paramter       Description
------------   --------------
suffix         The file suffix for the output file
header         Text printed at the start of the output file
taintmsg       Text printed ONLY IF source file modification date is 
                 later than the profile database modification date.
                 Printed just after header
datastart      Text printed just before report output and after
                 taintmsg
dataend        Text printed just after report output
footer         Text printed at the very end of report output
callsfunc      Reference to a function which must accept a scalar
                 representing the total calls for a line and returns the
                 output string for that field
timesfunc      Reference to a function which must accept a scalar
                 representing the total time for a line and returns the
                 output string for that field
time/callsfunc Reference to a function which must accept a scalar
                 representing the average time per call for a line and 
                 returns the output string for that field

Advanced Parameters:

 Paramter         Description
 --------------   --------------
 linestart        Printed at the start of each report line
 lineend          Printed at the end of each report line
 column1          |
 column2          | The four parameters define what to print in each of
 column3          | the four output fields. See below
 column4          |

Each of these parameters must be set to a hash reference with any of the
following key/value pairs:

 Key              Value
 -------------    -------------
 start            string printed at the start of the field
 end              string printed at the end of the field
 value            identifier for the value that this field will hold
                    (can be: time, calls, time/calls, source)
 default          string to be used when there is no value for the field
                    specified in the 'value' key

Basic Parameters Defaults:

Parameter         Default
--------------   --------------
suffix           '.csv'
header           "# Profile data generated by Devel::NYTProf::Reader 
                 v.$VERSION\n # Author: Adam Kaplan. More information at 
                 http://search.cpan.org/~akaplan\n# Format: time,calls,
                 code\n"
taintmsg         "# WARNING!\n# The source file used in generating this 
                 report has been modified\n# since generating the profiler 
                 database.  It might be out of sync\n"
datastart        ''
dataend          ''
footer           ''
callsfunc        undef
timefunc         undef
time/callsfunc   undef

Advanced Parameters Defaults:

Parameter         Default
--------------   --------------
linestart        {}
lineend          { end => "\n" }
column1          { value => 'time',      end => ',', default => '0'}
column2          { value => 'calls',      end => ',', default => '0'}
column3          { value => 'time/call',  end => ',', default => '0'}
column4          { value => 'source',    end => '',  default => '' }

SUBROUTINES

$reporter->report( );

Trigger data processing and report generation. This method will die with a message if it fails. The return value is not defined. This is where all of the work is done.

$reporter->getFileStats( );

When called after calling $reporter->report(), will return a hash containing the cumulative totals for each file.

my $stats = $reporter->getStats();
$stats->{FILENAME}->{time}; # might hold 0.25, the total runtime of this file>>

Fields are time, calls, time/call, html-safe.

Devel::NYTProf::Reader::calculate_sd( @stats );

Calculates the standard deviation and mean of the values in @stats, returns them as a list.

Devel::NYTProf::Reader::calculate_median_absolute_deviation( @stats );

Calculates the absolute median deviation and mean of the values in @stats, returns them as a list.

$reporter->_output_additional( $file, @data );

If you need to create a static file in the output directory, you can use this subroutine. It is currently used to dump the CSS file into the html output

$reporter->getDatabaseTime( );

Implemented in XS. This function returns the time that the NYTProf database was created. You should not need to use this.

$reporter->process( $file );

Implemented in XS. This function tell does the actual parsing of the database. It's fairly complicated and you're better off letting <Devel::NYTProf::Reader-new()>> invoke it for you. The return value is a series of nested hash refs and array refs containing the parsed data.

BUGS

Windows support. I have no idea if it will work, but the profiler will NOT.

EXPORT

None by default. Object Oriented.

SEE ALSO

Mailing list and discussion at http://groups.google.com/group/develnytprof-dev

Public SVN Repository and hacking instructions at http://code.google.com/p/perl-devel-nytprof/

Take a look at the scripts which implement this module, nytprofhtml and nytprofcsv. They are probably all that you will need and provide an excellent jumping point into writing your own custom reports.

You'll need to install and run Devel::NYTProf before you can use anything that implements this module... but this is easy (see "SYNOPSIS")

AUTHOR

Adam Kaplan, akaplan at nytimes dotcom

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Adam Kaplan and The New York Times Company.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.