NAME

Log::Any::Plugin::ContextStack - Stack of context items that get prepended to each log message

VERSION

version 0.012

SYNOPSIS

    # Set up some kind of logger.
    use Log::Any::Adapter;
    Log::Any::Adapter->set('SomeAdapter');

    # Apply the Levels plugin to your logger
    use Log::Any::Plugin;
    Log::Any::Plugin->add('ContextStack');


    # In your modules
    use Log::Any qw($log);

    $log->push_context('foo');
    $log->info('Hello');  # [foo] Hello
    $log->push_context('bar');
    $log->info('Hello');  # [foo:bar] Hello
    $log->pop_context;
    $log->info('Hello');  # [foo] Hello

    {
        # Must capture return value from push_scoped_context
        my $ctx = $log->push_scoped_context('bar', 'baz');
        $log->info('Hello');  # [foo:bar:baz] Hello
        # $ctx goes out of scope, automatically popping baz and bar
    }
    $log->info('Hello');  # [foo] Hello

DESCRIPTION

It can be useful to include some bits of context with your log messages. This plugin allows you to push and pop context on a stack, and have it automatically prepended to each log message.

CONFIGURATION

Configuration values are passed as key-value pairs when adding the plugin: Log::Any::Plugin->add('ContextStack', stringify => \&my_stringifier);

stringify => sub { ... }

Stringify function to turn the context stack into a string. Receives a single arrayref argument, and should return a single string. If there are no items on the context stack, this function won't be called. You don't need to handle the empty array case.

Default stringifier renders ['foo', 'bar'] as "[foo:bar]".

METHODS

There are no methods in this package which should be directly called by the user. Use Log::Any::Plugin->add() instead.

install

Private method called by Log::Any::Plugin->add()

ADAPTER METHODS

The following methods are injected into the adapter class.

$log->push_context(ARRAY)

Push one or more items onto the context stack.

$log->pop_context()

Pop a single item off the context stack.

my $ctx = $log->push_scoped_context(ARRAY)

Push one or more items onto the context stack, and return a Scope::Guard object that pops the same amount when it goes out of scope.

AUTHOR

Stephen Thirlwall <sdt@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2022, 2019, 2017, 2015, 2014 by Stephen Thirlwall.

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