/ 
Log-Abstraction-0.39
/ Log::Any::Adapter::Abstraction

NAME

Log::Any::Adapter::Abstraction - Log::Any adapter backed by Log::Abstraction

VERSION

0.39

SYNOPSIS

use Log::Any::Adapter;
use Log::Abstraction;

my @messages;

# Option A: pass a pre-built Log::Abstraction instance
my $logger = Log::Abstraction->new(logger => \@messages, level => 'debug');
Log::Any::Adapter->set('Abstraction', instance => $logger);

# Option B: let the adapter create a Log::Abstraction for you
Log::Any::Adapter->set('Abstraction', level => 'debug', logger => \@messages);

# Any module that uses Log::Any will now route through Log::Abstraction
use Log::Any '$log';
$log->info('Hello world');

DESCRIPTION

Log::Any::Adapter::Abstraction is a Log::Any adapter that routes messages from any module using Log::Any through a Log::Abstraction backend. Configure a single Log::Abstraction instance (with file, syslog, email, array, or code-ref backends) and all Log::Any-using CPAN modules automatically send their output there.

Level mapping

Each of Log::Any's nine severity levels has a Log::Abstraction method of the same name, except warning:

Log::Any level   Log::Abstraction method
---------------  -----------------------
trace            trace
debug            debug
info             info
notice           notice
warning          warn
error            error
critical         critical
alert            alert
emergency        emergency

Before version 0.36, critical, alert and emergency were all sent to error().

METHODS

init

Called automatically by Log::Any::Adapter::Base::new(). Initialises the internal Log::Abstraction backend.

Arguments (passed as key=>value pairs to Log::Any::Adapter->set)

  • instance

    An existing Log::Abstraction object. When supplied, the adapter wraps it directly without creating a new instance. Anything other than a Log::Abstraction object (or subclass) is a fatal error.

  • Any Log::Abstraction->new() argument

    logger, level, file, fd, array, format, ctx, script_name, verbose, carp_on_warn, croak_on_error, config_file, max_messages, redact, timestamp_format, timestamp_precision, utc, rotate_size, rotate_interval, rotate_keep. Used to build a fresh Log::Abstraction instance when instance is not supplied.

Example

Log::Any::Adapter->set('Abstraction',
    level  => 'debug',
    format => 'json',
    file   => '/var/log/myapp.log',
);

API SPECIFICATION

Input

{
    instance    => { type => OBJECT, isa => 'Log::Abstraction', optional => 1 },
    logger      => { optional => 1 },
    level       => { type => SCALAR, optional => 1 },
    file        => { type => SCALAR, optional => 1 },
    fd          => { optional => 1 },
    array       => { type => ARRAYREF, optional => 1 },
    format      => { type => SCALAR, optional => 1 },
    ctx         => { optional => 1 },
    script_name => { type => SCALAR, optional => 1 },
    verbose     => { type => BOOLEAN, optional => 1 },
    carp_on_warn   => { type => BOOLEAN, optional => 1 },
    croak_on_error => { type => BOOLEAN, optional => 1 },
    config_file    => { type => SCALAR, optional => 1 },
    max_messages   => { type => INTEGER, min => 0, optional => 1 },
    redact         => { optional => 1 },
    timestamp_format    => { type => SCALAR, optional => 1 },
    timestamp_precision => { type => INTEGER, min => 0, max => 9, optional => 1 },
    utc            => { type => BOOLEAN, optional => 1 },
    rotate_size    => { type => SCALAR, optional => 1 },
    rotate_interval => { type => SCALAR, optional => 1 },
    rotate_keep    => { type => INTEGER, min => 0, optional => 1 },
}

Output

{ type => 'object', class => 'Log::Any::Adapter::Abstraction' }

MESSAGES

Error                                     Meaning / Action
----------------------------------------  -----------------------------------------
"...: instance must be a Log::Abstraction  'instance' was given something other
  object"                                 than a Log::Abstraction object.
(any Log::Abstraction croak)              The supplied constructor args are invalid.
                                          See Log::Abstraction for detail.

Logging methods

trace
debug
info
notice
warning
error
critical
alert
emergency
$adapter->info($message);

Called by Log::Any with the formatted message; each sends it to the matching Log::Abstraction method (see "Level mapping"). These methods are generated when the module loads. A croak from Log::Abstraction (e.g. croak_on_error) is turned into a Carp::carp, so logging never dies.

API SPECIFICATION

Input

{ message => { type => 'string' } }

Output

{ type => 'undef' }

structured

$adapter->structured($level, $category, @parts, \%fields);

Called by Log::Any in place of the logging methods, with the message parts and, when there are any, a final hashref of structured fields: the proxy's context merged with a hashref passed as the last argument of the log call. The parts are joined with a space and sent, with the fields, to the matching Log::Abstraction method, so

$log->info('login', { user_id => 42 });

reaches Log::Abstraction as info('login', { user_id => 42 }). See "Structured fields" in Log::Abstraction for where the fields go. As with the logging methods, a croak is turned into a Carp::carp.

API SPECIFICATION

Input

{
    level    => { type => 'string' },
    category => { type => 'string' },
    parts    => { type => 'array' },
    fields   => { type => 'hashref', optional => 1 },
}

Output

{ type => 'undef' }

Detection methods

is_trace
is_debug
is_info
is_notice
is_warning
is_error
is_critical
is_alert
is_emergency
if($adapter->is_debug()) { ... }

Return 1 if a message at that level would be logged by the wrapped Log::Abstraction instance's level threshold, otherwise 0. Each calls the Log::Abstraction method of the same name (is_warning calls is_warn). As in Log::Abstraction, is_trace equals is_debug.

API SPECIFICATION

Input

{} (no arguments)

Output

{ type => 'boolean' }

LIMITATIONS

Message parts are joined with a space

In structured mode Log::Any passes the message parts, including any prefix, separately; "structured" joins them with a single space, so a prefix is followed by a space.

Filters disable structured fields

Log::Any doesn't use "structured" when the proxy has a filter; the fields then arrive as text appended to the message, as Log::Any formats them.

Logging never dies

A croak from the wrapped Log::Abstraction instance, such as from croak_on_error, is turned into a Carp::carp so that a module logging through Log::Any is never killed by its log call.

Log::Any as optional, not required

This adapter requires Log::Any at runtime, but Log::Any is listed as a recommends dependency rather than requires. CPAN clients that do not install recommended modules will allow this adapter to be installed but not loaded. Install Log::Any explicitly if you intend to use this adapter.

AUTHOR

Nigel Horne njh@nigelhorne.com

SEE ALSO

Log::Abstraction, Log::Any, Log::Any::Adapter

FORMAL SPECIFICATION

init ┌─ AdapterState ────────────────────────────────────────────── │ _logger : Log::Abstraction └─────────────────────────────────────────────────────────────

┌─ Init ──────────────────────────────────────────────────────
│ args? : { instance? : Log::Abstraction | logger_args }
│ result! : AdapterState
├─────────────────────────────────────────────────────────────
│ args?.instance ≠ ∅ ∧ isa(args?.instance, Log::Abstraction)
│   ⟹ result!._logger = args?.instance
│ args?.instance = ∅
│   ⟹ result!._logger = Log::Abstraction::new(logger_args)
└─────────────────────────────────────────────────────────────

COPYRIGHT AND LICENSE

Copyright (C) 2026 Nigel Horne

Usage is subject to the GPL2 licence terms. If you use it, please let me know.