Devel::NYTProf::Reader - Tranforms Devel::NYTProf output into comprehensive, easy to read reports in (nearly) arbitrary format.
# 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 ./nytprof nytprofhtml # To create a csv report in ./nytprof 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->output_dir($file); # set other options and parameters $reporter->add_regexp('^\s*', ''); # trim leading spaces # generate the report $reporter->report(); # many configuration options exist. See nytprofhtml, advanced example.
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.
Note: This module may be deprecated in future as the Devel::NYTProf::Data and Devel::NYTProf::Util modules evolve and offer higher levels of abstraction. It should then be easy to write reports directly without needing to fit into the model assumed by this module.
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.
Devel::NYTProf::Reader
@INC
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.
Numerous parameters can be set to modify the behavior of Devel::NYTProf::Reader. The following methods are provided:
Set the directory that generated files should be placed in. [Default: .]
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->add_regexp(' ', ' '); $reporter->add_regexp('<', '<'); $reporter->add_regexp('>', '>');
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
Basic Parameters Defaults:
Parameter Default -------------- -------------- suffix '.csv' header "# Profile data generated by Devel::NYTProf::Reader # Version: v$Devel::NYTProf::Core::VERSION # More information at http://search.cpan.org/dist/Devel-NYTProf/ # Format: time,calls,time/call,code" 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
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.
When called after calling $reporter->report(), will return a hash containing the cumulative totals for each file.
$reporter->report()
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.
Calculates the standard deviation and mean of the values in @stats, returns them as a list.
Calculates the absolute median deviation and mean of the values in @stats, returns them as a list.
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.
None by default. Object Oriented.
See also Devel::NYTProf.
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 use 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.
Adam Kaplan, <akaplan at nytimes.com> Tim Bunce, http://www.tim.bunce.name and http://blog.timbunce.org Steve Peters, <steve at fisharerojo.org>
<akaplan at nytimes.com>
<steve at fisharerojo.org>
Copyright (C) 2008 by Adam Kaplan and The New York Times Company. Copyright (C) 2008 by Tim Bunce, Ireland.
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.
To install Devel::NYTProf, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Devel::NYTProf
CPAN shell
perl -MCPAN -e shell install Devel::NYTProf
For more information on module installation, please visit the detailed CPAN module installation guide.