/ 
Log-Abstraction-0.35
/ Log::Any::Adapter::Abstraction

NAME

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

VERSION

0.35

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

Log::Any has nine severity levels; Log::Abstraction has six. The mapping is:

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

critical, alert, and emergency all route to error() because Log::Abstraction follows the syslog six-level model.

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. 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 },
}

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' }

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. As in Log::Abstraction, is_trace equals is_debug, and is_critical, is_alert and is_emergency equal is_error.

API Specification

Input

{} (no arguments)

Output

{ type => 'boolean' }

LIMITATIONS

Nine-to-six level collapse

Log::Any has nine severity levels; Log::Abstraction has six. critical, alert, and emergency all map to error(). Applications that rely on distinguishing these three levels in downstream Log::Abstraction backends will lose that distinction.

No structured field support

Log::Any's log_fields() mechanism for structured fields is not forwarded to Log::Abstraction. Only the final formatted string is dispatched; callers that need structured output should use the Log::Abstraction CODE-ref backend and access the formatted string via the message key.

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.