NAME

Thorium::Roles::Trace - Add code tracing and argument dumping to your class

VERSION

version 0.510

SYNOPSIS

    package MyModule;
    
    use Moose;
    with qw(Thorium::Roles::Trace);
    
    # ... methods, attributes and such

Then when using an object of your class

    use MyModule;
    
    # new object, with tracing turned on
    
    my $obj = MyModule->new(tacing => 1);
    
    $obj->method(); # method and all calls from $self interally are traced
    # ##### Entering MyModule::method #####
    # ##### Leaving MyModule::method #####
    
    $obj->dump_args_in(1);
    
    $obj->method2({one => 1}); # dump arguments being passed into methods
    # ##### Entering MyModule::method2 #####
    # *** method2 args ***
    # $VAR1 = [                    
    #           {
    #             'one' => 1
    #           }
    #         ];
    # ##### Leaving MyModule::method2 #####

Note that methods added after tracing is set will not be logged until tracing is set again. Methods set with *MyModule::method = sub {} will never be seen; use $meta-add_method> instead!

DESCRIPTION

This role adds tracing to arguments, sub-routines entering/leaving and returned data to Thorium::Log logging or STDERR if no logging sub-system found.

WARNING!

Do not keep tracing enabled in production. It has measurable performance penalties! Tracing should be a temporary debugging action. Proper logging is a permanent debugging action.

MORE WARNING!

Once you turn on tracing it is not possible to turn off as the original references to the sub-routines are embedded into new sub-routines and as a result, lost. It is technically possible add the ability to turn off tracing, but for the sake of simplicity and for the note listed in "WARNING!" the feature is absent.

ATTRIBUTES

Optional Attributes

• tracing (rw, Bool)

  Turn tracing on or off by setting this attribute to true. Defaults to false.

• trace_meta (rw, Bool)

  Include calls to the objects meta method (Class::MOP) in trace output. Defaults to false.

• dump_args (rw, Bool)

  Dump arguments being passed in and out of every method. Note, argument dumping will turn on tracing as well. Defaults to false.

• dump_args_in (rw, Bool)

  Dump arguments being passed in to a method. Defaults to false.

• dump_args_out (rw, Bool)

  Dump arguments being passed out of a method. Defaults to false.

• dump_maxdepth (rw, Maybe[Int])

  Maximum depth of argument dump - sets $Data::Dumper::Maxdepth locally. Defaults to false.

• dump_skip_self (rw, Bool)

  Do not include $self in dump. This is true by default. Note, this just blindly skips the first argument in @_!

• trace_dbi_calls (rw, DBH|Bool)

  Add simple tracing callbacks to some DBI methods:

  • connect

  • prepare

  • do

  • disconnect

PUBLIC API METHODS

None. This is a Moose::Role.

AUTHOR

Adam Flott <adam@npjh.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Adam Flott <adam@npjh.com>, CIDC.

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