File Coverage

=head1 NAME

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

=head1 VERSION

0.40

=head1 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');

=head1 DESCRIPTION

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

=head2 Level mapping

Each of Log::Any's nine severity levels has a Log::Abstraction method of
the same name, except C<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, C<critical>, C<alert> and C<emergency> were all sent
to C<error()>.

=head1 METHODS

=head2 init

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

=head3 Arguments (passed as key=E<gt>value pairs to C<Log::Any::Adapter-E<gt>set>)

=over 4

=item * C<instance>

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

=item * Any C<Log::Abstraction-E<gt>new()> argument

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

=back

=head3 Example

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

=head3 API SPECIFICATION

=head4 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 },
      reopen_interval => { type => INTEGER, min => -1, optional => 1 },
  }

=head4 Output

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

=head3 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.

=cut

=head2 Logging methods

=over 4

=item trace

=item debug

=item info

=item notice

=item warning

=item error

=item critical

=item alert

=item emergency

=back

  $adapter->info($message);

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

=head3 API SPECIFICATION

=head4 Input

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

=head4 Output

  { type => 'undef' }

=head2 structured

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

Called by L<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 C<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 L<Log::Abstraction> method, so

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

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

=head3 API SPECIFICATION

=head4 Input

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

=head4 Output

  { type => 'undef' }

=head2 Detection methods

=over 4

=item is_trace

=item is_debug

=item is_info

=item is_notice

=item is_warning

=item is_error

=item is_critical

=item is_alert

=item is_emergency

=back

  if($adapter->is_debug()) { ... }

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

=head3 API SPECIFICATION

=head4 Input

  {} (no arguments)

=head4 Output

  { type => 'boolean' }

=cut

=head1 LIMITATIONS

=over 4

=item B<Message parts are joined with a space>

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

=item B<Filters disable structured fields>

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

=item B<Logging never dies>

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

=item B<Log::Any as optional, not required>

This adapter requires L<Log::Any> at runtime, but Log::Any is listed as a
C<recommends> dependency rather than C<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.

=back

=head1 AUTHOR

Nigel Horne C<njh@nigelhorne.com>

=head1 SEE ALSO

L<Log::Abstraction>, L<Log::Any>, L<Log::Any::Adapter>

=encoding utf-8

=head1 FORMAL SPECIFICATION

=head2 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)
  â””─────────────────────────────────────────────────────────────

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2026 Nigel Horne

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

=cut