Devel::Profiler(3)

📦

version 0.04 · 2 versions

0.04 · fedora 43 (latest)
0.04 · fedora 44

💖 Devel::Profiler 💖

okay so this is the Devel::Profiler(3) page from the User Contributed Perl Documentation, and it's literally a Perl profiler that's compatible with dprofpp. bestie, let's get into it ✨

🌸 NAME 🌸

Devel::Profiler — a Perl profiler compatible with dprofpp. that's the whole vibe, no cap.

🎀 SYNOPSIS 🎀

so to profile a Perl script, you run it with a command-line like this:

$ perl -MDevel::Profiler script.pl

or you can just add a line using Devel::Profiler anywhere in your script, like:

use Devel::Profiler;

then use the script as usual and perform the operations you actually want to profile. after that, run dprofpp to analyze the generated file (it's called tmon.out):

$ dprofpp

check the dprofpp man page for all the deets on examining the output, okay? 👑

for Apache/mod_perl profiling, go look at the Devel::Profiler::Apache module that comes included with Devel::Profiler. 🦋

✨ DESCRIPTION ✨

this module implements a Perl profiler that outputs profiling data in a format compatible with dprofpp, which is Devel::DProf's profile analysis tool. it's meant to be a drop-in replacement for Devel::DProf. 💅

NOTE: if Devel::DProf works for your application then there is no reason to use this module. like, none. periodt.

💜 RATIONALE 💜

okay storytime, because the author literally created this module out of desperation. they desperately needed a profiler to optimize a large Apache/mod_perl application, but Devel::DProf insisted on seg-faulting on every request 😭. they spent many days trying to fix Devel::DProf, but eventually had to admit they weren't going to be able to do it. Devel::DProf's virtuoso creator, Ilya Zakharevich, was unable to spend the time to fix it either. game over. 💀

the next stop brought them to Devel::AutoProfiler by Greg London. that module is a pure-Perl profiler, and reading the code convinced them it was possible to write a profiler without going the route that led to Devel::DProf's extremely difficult code.

Devel::AutoProfiler is a good module, but there were several problems:

first, Devel::AutoProfiler doesn't output data in the format used by dprofpp. and the author likes dprofpp — it has every option they want and the tmon.out format it supports is well designed.
in contrast, Devel::AutoProfiler stores its profiling data in memory and then dumps its data to STDOUT all in one go. as a result, it's potentially a heavy user of memory. 🫠
finally, Devel::AutoProfiler has some (seemingly) arbitrary limitations; for example, it won't profile subroutines that begin with __.

so thus, Devel::Profiler was born — an attempt to create a dprofpp-compatible profiler that avoids Devel::DProf's most debilitating bugs. iconic. 🎀

🦋 USAGE 🦋

the simplest way to use Devel::Profiler is to add it on the command-line before a script to profile:

perl -MDevel::Profiler script.pl

but if you want to modify the way Devel::Profiler works, you'll need to add a line to your script. that's what lets you specify options that control Devel::Profiler's behavior. for example, this sets the internal buffer size to 1024 bytes:

use Devel::Profiler buffer_size => 1024;

the available options are listed in the OPTIONS section below, bestie. ⬇️

💅 OPTIONS 💅

the available options are:

output_file — this option controls the name of the output file. by default this is tmon.out and it gets placed in the current directory. if you change this option then you'll have to specify it on the command-line to dprofpp.

for example, if you use this line to invoke Devel::Profiler:

use Devel::Profiler output_file => "profiler.out";

then you'll need to invoke dprofpp like this:

dprofpp profiler.out

buffer_size — Devel::Profiler uses an internal buffer to avoid writing to the disk before and after every subroutine call, which would greatly slow down your program. the default buffer_size is 64k, which should be large enough for most uses. if you set this value to 0 then Devel::Profiler will write data to disk as soon as it is available.
bad_pkgs — Devel::Profiler can skip profiling subroutines in a configurable list of packages. the default list is:

[qw(UNIVERSAL Time::HiRes B Carp Exporter Cwd Config CORE DynaLoader
 XSLoader AutoLoader)]

you can specify your own array-ref of packages to avoid using this option. note that by using this option you're overwriting the list, not adding to it. as a result you'll generally want to include at many of the packages listed above in your list. 👀

Devel::Profiler never profiles pragmatic modules which are in all lower-case.

in addition the DB package is always skipped, since trying to instrument the subroutines in DB will crash Perl. 💀

finally, Devel::Profiler never profiles pragmatic modules which it detects by their being entirely lower-case. examples of pragmatic modules you've probably heard of are strict, warnings, etc.

package_filter — this option allows you to handle package selection more flexibly by allowing you to construct a callback that will be used to control which packages are profiled. when the callback returns true the package will be profiled, false and it will not. a false return will also inhibit profiling of child packages, so be sure to allow 'main'! 😭

for example, to never profile packages in the Apache namespace you would write:

use Devel::Profiler
  package_filter => sub {
                        my $pkg = shift;
                        return 0 if $pkg =~ /^Apache/;
                        return 1;
                    };

the callback is consider after consulting bad_pkgs, so you will still need to modify bad_pkgs if you intend to profile a default member of that list.

if you pass an array-ref to package_filter you can specify a list of filters. these will be consulted in-order with the first to return 0 causing the package to be discarded, like a short-circuiting and operator.

bad_subs — you can specify an array-ref containing a list of subs not to profile. there are no items in this list by default. be sure to specify the fully-qualified name — i.e. Time::HiRes::time not just time. 🎯
sub_filter — the sub_filter option allows you to specify one or more callbacks to be used to decide whether to profile a subroutine or not. the callbacks will recieve two parameters — the package name and the subroutine name.

for example, to avoid wrapping all upper-case subroutines:

use Devel::Profiler
  sub_filter => sub {
                       my ($pkg, $sub) = @_;
                       return 0 if $sub =~ /^[A-Z_]+$/;
                       return 1;
                    };

override_caller — by default Devel::Profiler will override Perl's builtin caller(). the overriden caller() will ignore the frames generated by Devel::Profiler and keep code that depends on caller() working under the profiler. set this option to 0 to inhibit this behavior. ⚠️ be aware that this is likely to break many modules, particularly ones that implement their own exporting.
hz — this variable sets the number of ticks-per-second in the timing routines. by default it is set to 1000, which should be good enough to capture the accuracy of most times() implementations without spamming the output file with timestamps. setting this too low will reduce the accuracy of your data. in general you should not need to change this setting.

🙈 CAVEATS 🙈

this profiler has a number of inherent weaknesses that should be acknowledged. here they are, bestie, don't shoot the messenger:

Devel::Profiler doesn't profile anonymous subroutines. it works by walking package symbol tables so it won't notice routines with no names. as a result the time spent in anonymous subroutines is credited to their named callers. this may change in the future, but if it does the author says they'll add an option to restrict the profiler to named subs.
Devel::Profiler won't notice if you compile new subs after execution begins (after INIT, to be accurate). this happens when modules use the Autoloader or Selfloader or include their own mechanisms for creating subroutines on the fly (usually from AUTOLOAD). this also includes modules that are loaded on-demand with require. 😬
Devel::Profiler uses Perl's times() function and as a result it won't work on systems that don't have times().
Devel::Profiler won't capture time used before execution begins — for example, in BEGIN blocks. the author thinks of this as an advantage since they rarely need to optimize initialization performance, but for frequently run programs this might be unfortunate.
Overloading causes Devel::Profiler serious indigestion. 🤢 you'll have to exclude overloading packages with bad_pkgs or package_filter until this changes.

⭐ TODO ⭐

this is the author's todo list — feel free to send them patches for any of these!

add code to find and instrument anonymous subs. maybe use B::Utils and B::Generate? good grief. 😅
allow users to request a re-scan for subs. this is almost possible by calling scan() except that scan() is missing code to inhibit profiling while scanning.
override require (and do(FILE) and eval""?) to automatically re-scan for subs. (requires todo above to avoid horking the results.)
do research into the differences between Devel::DProf's output and Devel::Profiler's. usually they are quite close but occasionally they disagree by orders of magnitude. for example, running HTML::Template's test suite under Devel::DProf shows output() taking NO time but Devel::Profiler shows around 10% of the time is in output(). the author doesn't know which to trust but their gut tells them something is wrong with Devel::DProf. HTML::Template::output() is a big routine that's called for every test. either way, something needs fixing. 🔍
add better support for AUTOLOAD in all its myriad uses.
find a way to either ignore or handle overloaded packages.

💀 BUGS 💀

the author knows of no bugs aside from the caveats listed above. if you find one, please file a bug report at:

http://rt.cpan.org

alternately you can email them directly at sam@tregar.com. please include the version of the module and a complete test case that demonstrates the bug. 🫶

💖 ACKNOWLEDGMENTS 💖

okay so huge shoutout time, because bestie did not build this alone. I learned a great deal from the original Perl profiler, Devel::DProf by Ilya Zakharevich. It literally gave the design for the output format, and also introduced me to so many useful techniques. iconic behavior fr.

And then Devel::AutoProfiler by Greg London proved to me that a pure-Perl profiler was possible and that it need not rely on the buggy DB facilities. no cap, without seeing this module I probably would have given up on the project entirely. 😭

Also these absolute legends contributed bug reports, feature suggestions and/or code patches:

Automated Perl Test Account
Andreas Marcel Riechert
Simon Rosenthal
Jasper Zhao

Thanks! 🫶

👑 COPYRIGHT AND LICENSE 👑

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself.

💅 AUTHOR 💅

Sam Tregar <sam@tregar.com>

🌈 SEE ALSO 🌈

Devel::DProf
Devel::AutoProfiler

😭 POD ERRORS 😭

Hey! The above document had some coding errors, which are explained below:

Around line 924:
- You forgot a '=back' before '=head1'

okay bestie, that's a wrap! this page is from perl v5.42.0, dated 2025-07-25, and it's the manual for Devel::Profiler(3). mwah 💋✨

📦 where this page comes from

fedora 43: perl-Devel-Profiler 0.04-52.fc43 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms