NAME

LWP::ConsoleLogger::Everywhere - LWP tracing everywhere

VERSION

version 1.000001

SYNOPSIS

    use LWP::ConsoleLogger::Everywhere;

    # somewhere deep down in the guts of your program
    # there is some other module that creates an LWP::UserAgent
    # and now it will tell you what it's up to

    # somewhere else you can access and fine-tune those loggers
    # individually:
    my $loggers = LWP::ConsoleLogger::Everywhere->loggers;
    $loggers->[0]->pretty(0);

    # or all of them at once:
    LWP::ConsoleLogger::Everywhere->set( pretty => 1);

    # Redact sensitive data for all user agents
    $ENV{LWPCL_REDACT_HEADERS} = 'Authorization,Foo,Bar';
    $ENV{LWPCL_REDACT_PARAMS} = 'seekrit,password,credit_card';

    # Or observe without changing your code
    PERL5OPT="-MLWP::ConsoleLogger::Everywhere" carton install

    perl -MLWP::ConsoleLogger::Everywhere my-script.pl

DESCRIPTION

This module turns on LWP::ConsoleLogger::Easy debugging for every LWP::UserAgent or Mojo::UserAgent based user agent anywhere in your code. It doesn't matter what package or class it is in, or if you have access to the object itself. All you need to do is use this module anywhere in your code and it will work.

You can access and configure the loggers individually after they have been created using the loggers class method. To change all of them at once, use the set class method instead.

See https://www.olafalders.com/2021/12/01/observing-network-traffic-with-lwp-consolelogger-everywhere/ for a practical example of how to use this module.

CLASS METHODS

set( <setting> => <value> )

    LWP::ConsoleLogger::Everywhere->set( dump_content => 0 );

This class method changes the given setting on all logger objects that have been created so far. The first argument is the accessor name of the setting you want to change, and the second argument is the new value. This cannot be used to access current values. See "METHODS" in LWP::ConsoleLogger#SUBROUTINES for what those settings are.

loggers

    my $loggers = LWP::ConsoleLogger::Everywhere->loggers;
    foreach my $logger ( @{ $loggers } ) {
        # stop dumping headers
        $logger->dump_headers( 0 );
    }

This class method returns an array reference of all LWP::ConsoleLogger objects that have been created so far, with the newest one last. You can use them to fine-tune settings. If there is more than one user agent in your application you will need to figure out which one is which. Since this is for debugging only, trial and error is a good strategy here.

ENVIRONMENT VARIABLES

LWPCL_LOGFILE

By default all data will be dumped to your console (as the name of this module implies) using Log::Dispatch. You may change this behavior though. The general approach is to do it from within your script, for example like this:

    use LWP::ConsoleLogger::Everywhere;
    my $loggers = LWP::ConsoleLogger::Everywhere->loggers;
    my $log_dispatch = Log::Dispatch->new(
      outputs => [
          [ 'File',   min_level => 'debug', filename => 'log_file.txt' ],
          [ 'Screen', min_level => 'debug' ],
      ],
    );
    foreach my $logger ( @{ $loggers } ) {
        $logger->logger($log_dispatch);
    }

The second approach is simpler and is done via an environment variable, for example you can run your script like this:

    LWPCL_LOGFILE=foo.log perl -MLWP::ConsoleLogger::Everywhere foo.pl

this will be equivalent to the first approach with the following Log::Dispatch logger:

    my $log_dispatch = Log::Dispatch->new(
        outputs => [ [ 'File', min_level => 'debug', filename => 'foo.log' ]  ],
    );

CAVEATS

If there are several different user agents in your application, you will get debug output from all of them. This could be quite cluttered.

Since LWP::ConsoleLogger::Everywhere does its magic during compile time it will most likely catch every user agent in your application, unless you use LWP::ConsoleLogger::Everywhere inside a file that gets loaded at runtime. If the user agent you wanted to debug had already been created at that time it cannot hook into the constructor any more.

LWP::ConsoleLogger::Everywhere works by catching new user agents directly in LWP::UserAgent when they are created. That way all properly implemented sub classes like WWW::Mechanize will go through it. But if you encounter one that installs its own handlers into the user agent after calling new in LWP::UserAgent that might overwrite the ones LWP::ConsoleLogger installed.

LWP::ConsoleLogger::Everywhere will keep references to all user agents that were ever created during for the lifetime of your application. If you have a lot of lexical user agents that you recycle all the time they will not actually go away and might consume memory.

SEE ALSO

For more information or if you want more detailed control see LWP::ConsoleLogger.

AUTHOR

Olaf Alders <olaf@wundercounter.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2014 by MaxMind, Inc.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

cpanm LWP::ConsoleLogger

perl -MCPAN -e shell
install LWP::ConsoleLogger