/ 
App-plstrace-0.06
River stage one • 1 direct dependent • 1 total dependent
/ plstrace

NAME

plstrace - Trace Perl function calls

VERSION

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

SYNOPSIS

% plstrace --help (or -h)
% plstrace --version (or -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 --options

Show time spent inside each subroutine:

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

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

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

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

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

-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.

--(no)hshow-entry

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

--(no)show-exit

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

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/perlancar/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

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by perlancar@cpan.org.

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