NAME
plstrace - Trace Perl function calls
VERSION
This document describes version 0.01 of plstrace (from Perl distribution App-plstrace), released on 2014-06-23.
SYNOPSIS
Usage:
% plstrace [--help | -h]
% plstrace [--version | -v]
% plstrace [PLSTRACE OPTIONS] <PROG> [PROG OPTIONS]Basic example (the only required option is -e trace=... to specify which subroutines should be traced, the below example means all subroutines in the main package (*) and all subroutines in the Foo package (Foo::*)):
% plstrace -e trace=*,Foo::* your_program.pl --your --prog --optionsShow time spent inside each subroutine:
% plstrace -e trace=... -T your_program.pl ...More options:
% plstrace -hSample output (using --reltime -t options):
000.009660 > main::foo("some arg", "1")
000.020905 > main::bar()
000.020905 < main::bar()
000.009660 < main::foo("some arg", "1")
000.034183 > main::foo("some arg", "2")
000.041502 > main::bar()
000.041502 < main::bar()
000.034183 < main::foo("some arg", "2")
000.071704 > main::foo("some arg", "3")
000.088051 > main::bar()
000.088051 < main::bar()
000.071704 < main::foo("some arg", "3")The main difference with strace output is that each sub is displayed twice, during entry and exit.
DESCRIPTION
plstrace is "strace for your Perl functions". Its interface and output is similar to Unix utility strace. But only a few strace options are currently supported.
Some notes (caveats, limitations):
Currently implemented by wrapping Perl subroutines with Perl subroutines during INIT phase
caller() has been adjusted so the wrapped subroutines does not see the trace wrappers (see Hook::LexWrap).
There are other low-level approaches for tracing (that might be used), see "SEE ALSO".
Perl builtin functions are not traced, only user-defined subroutines
O/S system calls or external programs are not traced
Time spent in each subroutine (-T) is inclusive
This means if A calls B and B calls C, A's time will include B and C.
Timing overhead currently has not been adjusted
So for small time amounts (microseconds or smaller) you should understand that the times are not very accurate.
OPTIONS
Unless specified otherwise, these options follow its strace counterpart. The long options are the ones that are added and different from strace.
-s SIZE(int)
-T
-t
-e trace=SUB_SPECS(str)
<SUB SPECS> is a comma-separated sub spec. Each sub spec is either /\w+/ (e.g. foo) to mean a named subroutine in the main package, * to mean all subroutines in the main package, /\w+(::\w+)+/ (e.g. Foo::func, Foo::Bar::blah) to mean a fully-qualified named subroutine, or /\w+(::\w+)*::\*/ (e.g. Foo::*) to mean all subroutines in a package.
--reltime
When under -t, show relative time against program start (in seconds, down to microseconds). Program start is measured right before plstrace exec's perl with Debug::LTrace::plstrace and your program. So the overhead of exec, perl startup, module and program compilation are all counted.
SEE ALSO
strace, the inspiration for this program.
Debug::LTrace::plstrace which currently actually implements the tracing, and which in turn is based on Debug::LTrace.
Other subroutine tracing modules: Devel::TraceCalls, Runops::Trace, Devel::TraceSubs, Devel::STrace (and others).
HOMEPAGE
Please visit the project's homepage at https://metacpan.org/release/App-plstrace.
SOURCE
Source repository is at https://github.com/sharyanto/perl-App-plstrace.
BUGS
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=App-plstrace
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
AUTHOR
Steven Haryanto <stevenharyanto@gmail.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2014 by Steven Haryanto.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.