view release on metacpan or  search on metacpan

bin/plstrace  view on Meta::CPAN

__END__

=pod

=encoding UTF-8

=head1 NAME

plstrace - Trace Perl function calls

=head1 VERSION

This document describes version 0.06 of plstrace (from Perl distribution App-plstrace), released on 2014-12-10.

=head1 SYNOPSIS

 % plstrace --help (or -h)
 % plstrace --version (or -v)
 % plstrace [PLSTRACE OPTIONS] <PROG> [PROG OPTIONS]

Basic example (the only required option is C<-e trace=...> to specify which
subroutines should be traced, the below example means all subroutines in the
main package (C<*>) and all subroutines in the C<Foo> package (C<Foo::*>)):

 % plstrace -e trace=*,Foo::* your_program.pl --your --prog --options

Show time spent inside each subroutine:

 % plstrace -e trace=... -T your_program.pl ...

Sample output (using C<-tttt> 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.

=head1 DESCRIPTION

B<plstrace> is "strace for your Perl functions". Its interface and output is
similar to Unix utility B<strace>. But only a few strace options are currently
supported.

Some notes (caveats, limitations):

=over

=item * 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 L<Hook::LexWrap>).

There are other low-level approaches for tracing (that might be used), see
L</"SEE ALSO">.

=item * Perl builtin functions are not traced, only user-defined subroutines

=item * O/S system calls or external programs are not traced

=item * 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.

=item * 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.

=back

=head1 OPTIONS

Unless specified otherwise, these options follow its strace counterpart. The
long options are the ones that are added and different from strace.

=head2 -s SIZE(int)

=head2 -T

=head2 -t

Like in strace, if specified once (C<-t>) will show time of day down to the
second, if specified twice (C<-tt>) will show time of day with microseconds, if
specified three times (C<-ttt>) will print epoch with microseconds.

plstrace adds two more styles: four times (C<-tttt>) will show relative time to
pogram start with microseconds, five times (C<-ttttt>) will show relative time
to I<previous message> with microseconds.

=head2 -e trace=SUB_SPECS(str)

C<< <SUB SPECS> >> is a comma-separated sub spec. Each sub spec is either
C</\w+/> (e.g. C<foo>) to mean a named subroutine in the C<main> package, C<*>
to mean all subroutines in the C<main> package, C</\w+(::\w+)+/> (e.g.
C<Foo::func>, C<Foo::Bar::blah>) to mean a fully-qualified named subroutine, or
C</\w+(::\w+)*::\*/> (e.g. C<Foo::*>) to mean all subroutines in a package.

=head2 --(no)hshow-entry

Whether to show subroutine entry. Default is true. Use C<--noshow-entry> to hide
showing entry traces.

=head2 --(no)show-exit

Whether to show subroutine exit. Default is true. Use C<--noshow-exit> to hide
showing exit traces.

=head1 SEE ALSO

B<strace>, the inspiration for this program.