NAME

Log::Any::For::Package - Add logging to package

VERSION

This document describes version 0.27 of Log::Any::For::Package (from Perl distribution Log-Any-For-Class), released on 2015-09-03.

SYNOPSIS

Add log to some existing packages (in other words, modules that are already loaded):

 use Foo;
 use Bar;
 use Log::Any::For::Package qw(Foo Bar);
 ...

Now calls to your module functions are logged, by default at level 'trace'. To see the logs, use e.g. Log::Any::App in command-line:

 % TRACE=1 perl -MLog::Any::App -MFoo -MBar -MLog::Any::For::Package=Foo,Bar \
     -e'Foo::func(1, 2, 3)'
 ---> Foo::func([1, 2, 3])
  ---> Bar::nested()
  <--- Bar::nested()
 <--- Foo::func() = 'result'

Use add_logging_to_package() which gives more options, e.g. to add log to multiple packages specified by regex:

 use Log::Any::For::Package qw(add_logging_to_package);
 add_logging_to_package(packages => [qw/Foo::.*/]);

To install an import (@INC) hook so that subsequent modules loaded will be logged:

 add_logging_to_package(packages => [...], import_hook=>1);

or, via import:

 % TRACE=1 perl -MLog::Any::App -MLog::Any::For::Package=-hook,1,.* ...

FAQ

How do I know that logging has been added to a package?

Log::Any::For::Package logs a trace statement like this after it added logging to a package:

 Added logging to package Foo (subs ["sub1","sub2",...])

If you use Log::Any::App to enable logging, you might not see this log message because it is produced during compile-time after use Foo. To see this statement, you can do require Foo instead or setup the logging at compile-time yourself instead of at the init-phase like what Log::Any::App is doing.

ENVIRONMENT

LOG_PACKAGE_INCLUDE_SUB_RE (str)

LOG_PACKAGE_EXCLUDE_SUB_RE (str)

LOG_SUB_ARGS (bool)

LOG_SUB_RESULT (bool)

CREDITS

Some code portion taken from Devel::TraceMethods.

SEE ALSO

Log::Any::For::Class

For some modules, use the appropriate Log::Any::For::*, for example: Log::Any::For::DBI, Log::Any::For::LWP.

FUNCTIONS

add_logging_to_package(%args) -> any

Add logging to package.

Logging will be done using Log::Any.

Currently this function adds logging around function calls, e.g.:

 ---> Package::func(ARGS)
 <--- Package::func() = RESULT
 ...

Arguments ('*' denotes required arguments):

• filter_subs => re|code

  Filter subroutines to add logging to.

  The default is to read from environment LOG_PACKAGE_INCLUDE_SUB_RE and LOG_PACKAGE_EXCLUDE_SUB_RE (these should contain regex that will be matched against fully-qualified subroutine/method name), or, if those environment are undefined, add logging to all non-private subroutines (private subroutines are those prefixed by _). For example.

• import_hook => bool (default: 0)

  Whether to install import (@INC) hook instead.

  If this setting is true, then instead of installing logging to all existing packages, an @INC import hook will be installed instead so that subsequent modules that are loaded and that match packages will be logged. So to log all subsequent loaded modules, you can set packages to ['.*'].

• logger_args => any

  Pass arguments to logger.

  This allows passing arguments to logger routine.

• packages* => array[str]

  Packages to add logging to.

  Each element can be the name of a package or a regex pattern (any non-valid package name will be regarded as a regex). If the package is (comes from) a module, the module must already be loaded. This function will not load modules for you.

• postcall_logger => code

  Supply custom postcall logger.

  Just like precall_logger, but code will be called after subroutine/method is called. Code will be given a hashref argument \%args containing these keys: args (arrayref, a shallow copy of the original @_), orig (coderef, the original subroutine/method), name (string, the fully-qualified subroutine/method name), result (arrayref, the subroutine/method result), logger_args (arguments given when adding logging).

  You can use this mechanism to customize logging.

• precall_logger => code

  Supply custom precall logger.

  Code will be called when logging subroutine/method call. Code will be given a hashref argument \%args containing these keys: args (arrayref, a shallow copy of the original @_), orig (coderef, the original subroutine/method), name (string, the fully-qualified subroutine/method name), logger_args (arguments given when adding logging).

  You can use this mechanism to customize logging.

  The default logger accepts these arguments (can be supplied via logger_args):

  • indent => INT (default: 0)

  Indent according to nesting level.

  • max_depth => INT (default: -1)

  Only log to this nesting level. -1 means unlimited.

  • log_sub_args => BOOL (default: 1)

  Whether to display subroutine arguments when logging subroutine entry. The default can also be supplied via environment LOG_SUB_ARGS.

  • log_sub_result => BOOL (default: 1)

  Whether to display subroutine result when logging subroutine exit. The default can also be set via environment LOG_SUB_RESULT.

Return value: (any)

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Log-Any-For-Class.

SOURCE

Source repository is at https://github.com/perlancar/perl-Log-Any-For-Class.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Log-Any-For-Class

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

cpanm Log::Any::For::Class

perl -MCPAN -e shell
install Log::Any::For::Class