File Coverage

=head1 NAME

Log::Abstraction - Logging Abstraction Layer

=head1 VERSION

0.41

=cut

=head1 SYNOPSIS

  use Log::Abstraction;

  # The default level is 'warning'; 'trace' lets every example through
  my $logger = Log::Abstraction->new(logger => 'logfile.log', level => 'trace');

  $logger->debug('This is a debug message');
  $logger->info('This is an info message');
  $logger->notice('This is a notice message');
  $logger->trace('This is a trace message');
  $logger->warn({ warning => 'This is a warning message' });

  # Structured fields
  $logger->info('User logged in', { user_id => 42 });

=head1 DESCRIPTION

The C<Log::Abstraction> class provides a flexible logging layer on top of
different types of loggers, including code references, arrays, file paths,
and objects.  It also supports logging to syslog if configured.

=head2 Unicode

Messages may be character strings containing any Unicode text.  The file,
fd and scalar-path backends write character strings as UTF-8 (unless an
C<fd> handle already has a C<:utf8> or C<:encoding> layer, in which case the
handle does the encoding), and C<format =E<gt> 'json'> output is UTF-8 too.
journald fields are sent as UTF-8.  Byte strings are written unchanged.

=head2 Structured fields

Every logging method accepts a hash reference of structured fields after
the message:

  $logger->info('User logged in', { user_id => 42, ip => $ip });
  $logger->warn('Slow query', { ms => 1250 });

A hash reference is taken as fields only when it is the last of two or more
arguments, so C<warn({ warning =E<gt> ... })> keeps its meaning, and a lone
hash reference is still a message.  An empty hash reference is ignored.  The
fields are copied, so changing the hash afterwards doesn't change what was
logged.  They are kept out of the message and go to each backend as follows:

=over 4

=item * L</messages>, C<array> and an ARRAY C<logger> -- a C<fields> key in
the entry, alongside C<level> and C<message>.

=item * a CODE C<logger> -- a C<fields> key in the hashref it is called with.

=item * C<format =E<gt> 'json'> -- a nested C<fields> object.  Objects are
stringified; other references are kept as JSON data.

=item * C<journald> -- journal fields.  Each name is upper-cased, characters
other than C<A-Z>, C<0-9> and C<_> become C<_>, leading underscores are
removed and it is cut to 64 characters; a field left with no name is
dropped.  Fields override the extra keys in the C<journald> hash, but never
C<MESSAGE>, C<PRIORITY> or C<SYSLOG_IDENTIFIER>.

=item * text formats (C<file>, C<fd>, a scalar C<logger>), C<syslog>,
C<sendmail> and object loggers -- appended to the message as logfmt-style
C<key=value> pairs in key order, e.g. C<User logged in ip=10.0.0.1 user_id=42>.
Characters other than C<[\w.-]> in a key become C<_>.  A value that is empty
or contains white space, C<">, C<=> or C<\> is double-quoted, with C<"> and
C<\> escaped and control characters written as C<\n>, C<\r>, C<\t> or
C<\xNN>.  Objects are stringified and other references written as JSON.  An
object logger is passed the pairs as an extra argument after the message.

=back

When logging through L<Log::Any>, a hash reference at the end of the call,
together with the proxy's C<context>, arrives here as fields; see
L<Log::Any::Adapter::Abstraction/structured>.

=head2 Redaction

The C<redact> option removes secrets before a message reaches the history
or any backend.  Each match of any of its patterns is replaced with
C<[REDACTED]>:

  my $log = Log::Abstraction->new(
      logger => '/var/log/myapp.log',
      redact => [qr/password=\S+/, qr/\b\d{4}(?:[ -]?\d{4}){3}\b/],
  );
  $log->warn('Login failed: user=fred password=hunter2');
  # Login failed: user=fred [REDACTED]

To keep the start of a match, end it with C<\K>: C<qr/password=\K\S+/> logs
C<password=[REDACTED]>.  The patterns run over the whole message, after its
arguments are joined, so a match may span them, as in
C<$log-E<gt>info('password=', $password)>; a CODE or object logger then gets
the joined message as one argument.  The text given to C<carp> or C<croak>
(see L</warn> and L</error>) is redacted too.

L</Structured fields> are redacted as well: string values, including those
inside plain hashes and arrays, and objects whose stringification matches
(they become the redacted string).  Field names aren't redacted, nor are
the format string, C<%env_*%> values or C<ctx>.

Redaction is applied only to messages that pass the logger's C<level>, so
it costs nothing for messages that are dropped.  A pattern that can match
the empty string, such as C<qr/x*/>, is rejected by L</new>.

=head2 Email digests

C<min_interval> limits the C<sendmail> backend to one email per interval,
dropping the messages in between.  With C<digest>, they are held instead,
and sent ahead of the next message in the first email after the interval:

  my $log = Log::Abstraction->new(
      logger => {
          file     => '/var/log/myapp.log',
          sendmail => {
              to           => 'ops@example.com',
              level        => 'error',
              min_interval => 300,
              digest       => 1,
              format       => '%level%> [%timestamp%] %message%',
          },
      },
  );

Each message is one line of the email, oldest first, as its own email body
would be: formatted with the C<sendmail> C<format> if there is one (as
above, so that each line has its time), else the message.  At most
C<digest_max> messages (default 100) are held; later ones are only
counted, and the email says C<... and N more messages> after the held ones.
Messages held when an email fails to send stay held, and the new one is
held with them.

Nothing is sent on a timer: held messages go out with the next email,
when L</flush> is called, or when the logger is destroyed (which calls
L</flush>).  A clone made with L</new> starts with none held.

=head2 Per-backend level and format

Every backend can have its own C<level> and C<format>, as well as the
logger's.  C<syslog>, C<journald> and C<sendmail> are hashes already, so
they take them as keys.  C<file>, C<fd> and C<array>, inside a C<logger> hash
or at the top level, and C<log_any> and C<log_dispatch>, may be given as a
hash holding the destination under the backend's own name:

  my $log = Log::Abstraction->new(
      level  => 'debug',
      logger => {
          file   => { file => '/var/log/myapp.log', format => 'json' },
          fd     => { fd => \*STDERR, level => 'warning' },
          array  => { array => \@recent, level => 'info' },
          syslog => { level => 'error', format => '%level%: %message%' },
      },
  );

=over 4

=item * C<level> -- the backend only gets messages at this level or more
severe.  A level name or a syslog number (0-7).  The logger's C<level> is
applied first, so a backend's level can only narrow it: set the logger's
C<level> to the most verbose any backend wants.

=item * C<format> -- a format string, or C<json>, as for the logger's
L</format>, which it overrides.  For C<file> and C<fd> it is the line
written.  For the others, which by default get the message as it is, it
replaces the message: the C<array> entry's C<message>, the text sent to
syslog, Log::Any or Log::Dispatch, the journal's C<MESSAGE> field and the
email body.

=back

The plain forms (C<file =E<gt> $path>, C<fd =E<gt> $handle>,
C<array =E<gt> \@array>, C<log_any =E<gt> $category>,
C<log_dispatch =E<gt> $dispatcher>) still work and have no level or format of their
own.  A blessed handle object is a destination, not the hash form.

=head2 Forwarding to Log::Any and Log::Dispatch

L<Log::Any::Adapter::Abstraction> brings messages from L<Log::Any> into
C<Log::Abstraction>.  The C<log_any> and C<log_dispatch> backends go the
other way, sending messages on to an application's existing L<Log::Any> or
L<Log::Dispatch> set-up, alongside any other backends:

  my $log = Log::Abstraction->new(
      level  => 'debug',
      logger => {
          log_any      => 'MyApp',          # a category, or a Log::Any logger
          log_dispatch => $dispatcher,      # a Log::Dispatch object
          file         => '/var/log/myapp.log',
      },
  );

Levels keep their names, except that C<warn> becomes C<warning>, and
Log::Dispatch, which has nothing below C<debug>, gets C<trace> messages as
C<debug>.  Log::Any gets L</Structured fields> as its trailing hashref, so a
structured adapter receives them as data; Log::Dispatch has no fields, so
they are appended to the message as text.  With its own C<format> (see
L</Per-backend level and format>) a backend gets the formatted line instead.

A C<Log::Any> category name is looked up with
C<Log::Any-E<gt>get_logger(category =E<gt> $name)> (which needs L<Log::Any>
installed) when the first message is sent, and follows later
C<Log::Any::Adapter-E<gt>set()> calls.  If Log::Any or Log::Dispatch dies,
C<Carp::carp> is called and the other backends still get the message.

A C<Log::Any::Proxy> or C<Log::Dispatch> object given as the C<logger>
itself is used in the same way, rather than as an object whose method is
called for each level: neither has a method for every level, and both
would join the arguments with spaces.

A message that reaches a C<Log::Abstraction> while it is being forwarded
(e.g. through L<Log::Any::Adapter::Abstraction>) is logged by that logger's
other backends but not forwarded again, so a set-up that points back at
itself doesn't loop.

=head2 File rotation

Log files written by path (a scalar C<logger>, a C<file> key in a C<logger>
hash, and the top-level C<file>) can be rotated by size, by time, or both:

  my $log = Log::Abstraction->new(
      file            => '/var/log/myapp.log',
      rotate_size     => '10M',
      rotate_interval => 'daily',
      rotate_keep     => 7,
  );

Before each write the file is checked, and if it is due it is renamed to
F<myapp.log.1>, the old F<.1> to F<.2> and so on, the oldest beyond
C<rotate_keep> being deleted; the line then goes to a new F<myapp.log>.  A
rotation that fails (e.g. for lack of permission) is ignored, and the line is
still written.  File handles passed as C<fd> aren't rotated.

Rotation isn't coordinated between processes: if several processes log to the
same file, use B<logrotate> instead.

=head3 logrotate

The file is kept open between messages, but before each write the logger
checks that the path still names the same file (device and inode), so
B<logrotate>'s default (rename the file and let the application create a new
one) works without C<copytruncate>, and without sending the process a
C<SIGHUP>: the next message is written to a new file.

A C<postrotate> script that sends the process a C<SIGHUP> works too: except
on Windows, the first time a logger opens a file, C<Log::Abstraction> sets
C<$SIG{HUP}> to a handler that makes every logger open its files again on
the next write.  A handler that was already set (a code reference or a sub
name) is called after it.  This means a C<SIGHUP> no longer ends the
program, as it does by default, while a logger that has opened a file
exists.  When the last of them is destroyed, the handler that was there
before is put back.  A handler that the program sets later replaces
C<Log::Abstraction>'s (and isn't changed when the loggers are destroyed);
it can call L</reopen> itself.

In case a C<SIGHUP> isn't sent, every file is also closed and opened again
every 5 minutes, by default.  C<reopen_interval> changes how often, makes
C<SIGHUP> the only way (C<-1>), or closes the file after every message
(C<0>), as before version 0.40.

On Windows an open file can't be renamed or deleted, so a file the logger is
writing can only be rotated by the logger itself (which closes it first), or
after calling L</reopen>, and then only until the next message.

=head1 METHODS

=head2 new

  my $logger = Log::Abstraction->new(%args);
  my $logger = Log::Abstraction->new(\%args);
  my $logger = Log::Abstraction->new($file_path);

  # Clone with optional overrides
  my $clone = $logger->new(level => 'debug');

Creates a new C<Log::Abstraction> instance, or clones an existing one when
called on an object.  It may also be called as a plain function,
C<Log::Abstraction::new(%args)>, which behaves like
C<Log::Abstraction-E<gt>new(%args)>.

=head3 Arguments

=over 4

=item * C<carp_on_warn>

If set to 1, and no C<logger> is given, call C<Carp::carp> on C<warn()>.
Also causes C<error()> to C<carp> if C<croak_on_error> is not set.

=item * C<croak_on_error>

If set to 1, and no C<logger> is given, call C<Carp::croak> on C<error()>.

=item * C<config_file>

Path to a configuration file (YAML, XML, INI, etc.) whose contents are
merged with the constructor arguments.  On non-Windows systems the class
can also be configured via environment variables prefixed with
C<"Log::Abstraction::">.  For example:

  export Log::Abstraction::script_name=foo

=item * C<ctx>

Arbitrary context value passed through to CODE-ref logger callbacks as
C<$args-E<gt>{ctx}>.

=item * C<format>

Format string for the file, fd and scalar-path backends; a backend's own
C<format> (see L</Per-backend level and format>) overrides it for that
backend.  Unset or an empty string means the default,
C<%level%E<gt> [%timestamp%] %class% %callstack% %message%>.  Tokens expanded
at log time:

  %callstack%   caller file and line number
  %class%       blessed class of the logger object
  %level%       upper-cased level name
  %message%     the joined log message
  %timestamp%   the time of the call; YYYY-MM-DD HH:MM:SS local time by
                default (see timestamp_format, timestamp_precision and utc)
  %env_FOO%     value of $ENV{FOO}, or empty string if unset

Tokens are only expanded in the format string itself, never in the text
of the message.  Each line break in a message is followed by a tab, so a
continuation line can't be mistaken for a new log entry.

The special value C<"json"> (not a format string but a magic keyword) switches
all file and fd backends to emit one compact JSON object per log line:

  {"timestamp":"...","level":"info","message":"...","file":"...","line":42}

This format is compatible with log aggregators such as journald, Loki,
Elasticsearch, and Splunk.  C<class> is included when the logger is a subclass
of C<Log::Abstraction>, and C<fields> when the call has L</Structured fields>.
Keys are emitted in sorted order.

B<Security note:> because a format may contain C<%env_*%> tokens, which
expand to environment variables, avoid granting untrusted sources write
access to config files that set C<format> or any backend's C<format> (see
L</Per-backend level and format>).

=item * C<level>

Minimum level at which to emit log entries.  Defaults to C<"warning">.
Valid values (case-insensitive): C<trace>, C<debug>, C<info>/C<informational>,
C<notice>, C<warn>/C<warning>, C<error>/C<err>, C<crit>/C<critical>/C<fatal>,
C<alert>, C<emerg>/C<emergency>/C<panic>.  C<trace> and C<debug> are the same
threshold (see L</LIMITATIONS>).  It may also be an array reference, whose
first element is used, as some configuration-file formats produce.

=item * C<max_messages>

The most entries to keep in the in-memory history returned by
L</messages>; when it is full, the oldest entry is discarded.  Must be a
non-negative integer; C<0> keeps no history at all.  Unlimited by default, which in a long-running process
means the history grows without bound.

=item * C<logger>

One of:

=over 4

=item * A code reference -- called with a hashref C<{ class, file, line, level, message, ctx, fields }>
(C<ctx> and C<fields> only when there are any)

=item * An object -- method matching the level name is called on it; a
L<Log::Any> logger or a L<Log::Dispatch> object is used as the C<log_any> or
C<log_dispatch> backend (see L</Forwarding to Log::Any and Log::Dispatch>)

=item * A hash reference -- may contain C<file>, C<array>, C<fd>, C<syslog>, C<journald>, C<sendmail>,
C<log_any> and/or C<log_dispatch> keys,
each of which may have its own C<level> and C<format> (see L</Per-backend level and format>)

=item * An array reference -- C<{ level, message }> hashrefs are pushed onto it, with a
C<fields> key when the call has L</Structured fields>

=item * A scalar string -- treated as a file path to append to

=back

When not supplied, L<Log::Log4perl> is initialised as the default backend.

The C<sendmail> sub-hash supports:
C<host>, C<port>, C<to>, C<from>, C<subject>, C<level>, C<format>,
C<min_interval>, C<digest>, C<digest_max>, C<async>.  C<to> is required.  With C<format>, the email body is the
formatted line rather than the message.  C<level> may be a level name or a syslog number (0-7);
without it, every message is emailed.
At most one email is sent per C<min_interval> seconds per instance; the
messages in between are dropped, unless C<digest> is set, which sends them
with the next email (see L</Email digests>).  If delivery fails,
C<Carp::carp> is called and the other backends still receive the message.

Sending an email waits for the SMTP server, which can take seconds.  With
C<async =E<gt> 1>, the email is sent by a child process (made with
C<fork>), and the log call returns at once.  The C<host> and C<port> are
still checked first.  The logger can't know whether the child succeeded:
the child carps a failure itself, and the message (and any digest sent
with it) is lost rather than held.  Emails sent close together are sent at
the same time, so they may arrive in any order.  The finished children are
reaped the next time an email is sent and when a logger is destroyed; a program that
reaps every child itself (e.g. C<waitpid(-1, ...)> in a C<$SIG{CHLD}>
handler) may see them.  On Windows, whose C<fork> is emulated with threads,
when C<fork> fails, and for the email sent when perl exits, the email is
sent in the log call as without C<async>.

The C<syslog> sub-hash supports the keys below.  The message is passed to
C<syslog()> through a C<%s> format, so C<%> sequences in it, such as C<%m>,
are logged literally.

=over 4

=item * C<facility> -- the syslog facility (default: C<local0>)

=item * C<level> -- only messages at this level or more severe are sent; a level name or a syslog number (0-7)

=item * C<format> -- format the message with this (see L</format>) before sending it; by default the message is sent as it is

=item * C<host> (or its alias C<server>), and any other L<Sys::Syslog/setlogsock> option -- passed to C<setlogsock()>

=back

The C<journald> sub-hash sends each message as a single datagram to the
systemd journal using the journald native protocol.  Supported keys:

=over 4

=item * C<socket> -- path to the journald socket (default: F</run/systemd/journal/socket>)

=item * C<identifier> -- value for the C<SYSLOG_IDENTIFIER> field (default: basename of C<$0>)

=item * C<level> -- only messages at this level or more severe are sent; a level name or a syslog number (0-7)

=item * C<format> -- the C<MESSAGE> field is the message formatted with this (see L</format>); by default it is the message as it is

=item * any other key -- included verbatim as an uppercase journald field name.
The upper-cased name must contain only C<A-Z>, C<0-9> and C<_>, and must not
start with C<_>; C<new()> croaks otherwise.

=back

The C<PRIORITY> field is set automatically from the log level (0=emerg...7=debug).
A message too large for one datagram (about 200KB) is truncated and
C<[truncated]> appended.
Delivery failures are silent apart from a single C<Carp::carp> (repeated only
after a later send has succeeded); the application is never crashed by a
journald error.  The socket is opened for the first message and reused for
the next ones; after a failed send it is closed, and the next message opens a
new one.  Each datagram is addressed to the socket path, so delivery
continues after journald restarts.

=item * C<redact>

Patterns to remove from every message before it is logged: a C<qr//>, a
string (compiled as a regular expression; a config file can't hold a
C<qr//>), or an array reference of them.  See L</Redaction>.

=item * C<reopen_interval>

Log files written by path are kept open between messages.  Every this many
seconds (default 300, i.e. 5 minutes) each one is closed and opened again on
its next write, in case a rotation tool changed the file without renaming it
and without sending a C<SIGHUP> (see L</logrotate>).

C<0> closes the file after every message, so it is never held open, and no
C<SIGHUP> handler is installed for it.  C<-1> never reopens the file because
of time: only a C<SIGHUP>, L</reopen>, or the file being renamed or deleted
does.  (Windows has no C<SIGHUP>.)

=item * C<rotate_interval>

Rotate log files by time: C<hourly>, C<daily>, C<weekly> (weeks start on
Monday) or C<monthly>, case-insensitive.  Before each write, a file whose
last-modified time is in an earlier period than now (in local time, or UTC
with C<utc>) is rotated, so a file not written to for a while rotates on the
next write.  See L</File rotation>.

=item * C<rotate_keep>

How many rotated files to keep, F<FILE.1> to F<FILE.I<n>> (default 5).  With
C<0>, a file due for rotation is deleted instead.

=item * C<rotate_size>

Rotate log files that have reached this size: a number of bytes, optionally
followed by C<K>, C<M> or C<G> (powers of 1024), e.g. C<10M>.  See
L</File rotation>.

=item * C<script_name>

Script name reported to syslog.  Auto-detected from C<$0> if not supplied.

=item * C<timestamp_format>

How C<%timestamp%>, and the C<timestamp> key of C<format =E<gt> 'json'>,
are written.  Either a L<POSIX/strftime> pattern (default
C<%Y-%m-%d %H:%M:%S>) or one of these names (case-insensitive):

  iso8601, rfc3339   2026-10-03T20:14:23-04:00, or 2026-10-04T00:14:23Z with utc

The pattern may also use:

  %N        fractional seconds, 9 digits (nanoseconds)
  %3N       fractional seconds, 3 digits (milliseconds); any width 1-9
  %z        UTC offset as +hhmm (on every platform, unlike some strftimes)
  %:z       UTC offset as +hh:mm, as RFC 3339 needs
  %Z        the time-zone name; "UTC" when utc is set
  %%        a literal %

Fractional seconds come from L<Time::HiRes> and are truncated, not rounded;
digits beyond the system clock's resolution (usually microseconds) are
noise.  The timestamp is taken once per message, so every backend shows the
same time.

=item * C<timestamp_precision>

The number of fractional-second digits, 0-9 (default 0), added after the
seconds (each C<%S>) of whichever C<timestamp_format> is in use:

  Log::Abstraction->new(timestamp_format => 'rfc3339', timestamp_precision => 3, utc => 1);
  # 2026-10-04T00:14:24.094Z

=item * C<utc>

If true, timestamps are in UTC rather than local time.

=item * C<verbose>

When using the default Log::Log4perl backend, raises the logging level to
DEBUG when set to a true value.

=back

=head3 Returns

A blessed C<Log::Abstraction> object.

=head3 Side Effects

Loads C<File::Basename> if C<syslog> is configured (either at the top level
or in a C<logger> hash) and C<script_name> is not supplied.  Loads
C<Log::Log4perl> if no backend (C<logger>, C<file>, C<fd> or C<array>) is
specified.

Builds one L<Log::Abstraction::Backend> object for each place messages go
to.  The arguments are not changed: in particular, the C<syslog> hash keeps
its C<facility>, C<level> and C<format> keys, and a C<server> key is not
renamed C<host> (before 0.40, the first message did both).

=head3 Example

  my $logger = Log::Abstraction->new(
      level  => 'debug',
      logger => \@messages,
  );

  my $clone = $logger->new(level => 'info');

=head3 API SPECIFICATION

=head4 Input

  {
      carp_on_warn   => { type => 'boolean', optional => 1 },
      config_file    => { type => 'string',  optional => 1 },
      croak_on_error => { type => 'boolean', optional => 1 },
      ctx            => { optional => 1 },
      format         => { type => 'string',  optional => 1 },
      level          => { type => 'string',  regex => qr/^(trace|debug|info(?:rmational)?|notice|warn(?:ing)?|err(?:or)?|crit(?:ical)?|fatal|alert|emerg(?:ency)?|panic)$/i, optional => 1 },
      logger         => { optional => 1 },
      max_messages   => { type => 'integer', min => 0, optional => 1 },
      redact         => { optional => 1 },    # regex, string, or arrayref of them
      reopen_interval => { type => 'integer', min => -1, optional => 1 },
      rotate_interval => { type => 'string', regex => qr/^(hourly|daily|weekly|monthly)$/i, optional => 1 },
      rotate_keep    => { type => 'integer', min => 0, optional => 1 },
      rotate_size    => { type => 'string',  regex => qr/^\s*[1-9]\d*\s*[kmg]?b?\s*$/i, optional => 1 },
      script_name    => { type => 'string',  optional => 1 },
      timestamp_format    => { type => 'string', min => 1, optional => 1 },
      timestamp_precision => { type => 'integer', min => 0, max => 9, optional => 1 },
      utc            => { type => 'boolean', optional => 1 },
      verbose        => { type => 'boolean', optional => 1 },
  }

=head4 Output

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

=head3 MESSAGES

  Error                                     Meaning / Action
  ----------------------------------------  -----------------------------------------
  "<class>: <path>: File not readable"      config_file path exists but is unreadable.
                                            Check file permissions.
  "<class>: Can't load configuration       Config::Abstraction could not parse the
    from <path>"                            file.  Check syntax and format.
  "<class>: syslog needs to know the        syslog backend requested but script_name
    script name"                            could not be determined.  Pass it explicitly.
  "<class>: attempt to encapsulate          logger => Log::Abstraction would create
    Log::Abstraction as a logging class,    a needless forwarding loop.  Use a
    that would add a needless indirection"  different backend.
  "<class>: invalid syslog level '<l>'"     level value is not a recognised syslog
                                            level name.  Use trace/debug/info/notice/
                                            warn/warning/error.
  "<class>: max_messages must be a          max_messages is negative or not a number.
    non-negative integer, not '<v>'"
  "<class>: rotate_size must be a           rotate_size is not, e.g., 1048576, 512K,
    positive number of bytes, optionally    10M or 1G.
    with K, M or G, not '<v>'"
  "<class>: rotate_interval must be         rotate_interval is not one of those names.
    hourly, daily, weekly or monthly,
    not '<v>'"
  "<class>: rotate_keep must be a           rotate_keep is negative or not a number.
    non-negative integer, not '<v>'"
  "<class>: reopen_interval must be a       reopen_interval is not a whole number
    number of seconds, 0 or -1, not '<v>'"  of seconds, 0 (close after every
                                            message) or -1 (only on SIGHUP).
  "<class>: timestamp_format must be a      timestamp_format is undef, empty or a
    non-empty string"                       reference.
  "<class>: timestamp_precision must be     timestamp_precision is not a whole
    an integer from 0 to 9, not '<v>'"      number of digits from 0 to 9.
  "<class>: redact patterns must be         A redact entry is a reference other than
    regular expressions or non-empty        a qr//, or an empty string.
    strings"
  "<class>: invalid redact pattern '<p>':   A redact string is not a valid regular
    <error>"                                expression.
  "<class>: redact pattern <p> matches the  The pattern can match nothing at all
    empty string"                           (e.g. qr/x*/), which would put a marker
                                            between every character.
  "<class>: invalid <backend> level '<l>'"  A backend's 'level' (file, fd, array,
                                            sendmail, journald) is neither a level
                                            name nor 0-7.  (A bad syslog 'level'
                                            gives "invalid syslog level", as above.)
  "<class>: the <backend> format must be   A backend's 'format' is undef, empty or
    a non-empty string"                     a reference.
  "<class>: the <backend> hash needs a      The hash form of file, fd, array, log_any
    '<backend>' key"                        or log_dispatch has no destination (e.g.
                                            file => { level => 'info' } without a
                                            'file' key).
  "<class>: the sendmail backend needs      The sendmail sub-hash has no 'to' key.
    a 'to' address"
  "<class>: sendmail digest_max must be a   digest_max is zero, negative or not a
    positive integer, not '<v>'"            number.
  "<class>: invalid journald field name     An extra journald key, upper-cased, is not
    '<k>'"                                  [A-Z0-9_] or starts with '_'.
  "<class>: the logger hash has none of     The logger hash has nowhere to send
    the keys array, fd, file, journald,     messages.  (Before 0.40, the first
    log_any, log_dispatch, sendmail,        message croaked "Don't know how to deal
    syslog"                                 with the <level> message".)
  "<class>: the logger can't be a <TYPE>    logger is a reference of an unsupported
    reference"                              type, e.g. a SCALAR or GLOB reference.
  "<class>: log_any must be a Log::Any      log_any is neither a Log::Any logger
    logger or a category name"              (Log::Any::Proxy) nor a non-empty string.
  "<class>: log_any needs Log::Any to be    log_any is a category name but Log::Any
    installed"                              can't be loaded.
  "<class>: log_dispatch must be a          log_dispatch is not an object with a
    Log::Dispatch object"                   log() method.

The following are not raised by C<new()> but later, by the logging methods
(C<trace>, C<debug>, C<info>, C<notice>, C<warn>, C<error>, C<fatal>,
C<critical>, C<alert>, C<emergency>), when
a message that passes the level threshold reaches the backend concerned.
Croaks are configuration errors; delivery failures only carp, because a
logging failure must never crash the application.

  Croak                                     Meaning / Action
  ----------------------------------------  -----------------------------------------
  "<class>: Invalid file name: <path>"      A file path (logger string, 'file' key or
                                            logger hash 'file') contains one of
                                            < > | * ? ; ! ` $ " or a control
                                            character, or contains '..'.
  "<class>: Invalid SMTP host: <host>"      The sendmail 'host' contains characters
                                            other than A-Z a-z 0-9 . -
  "<class>: Invalid SMTP port: <port>"      The sendmail 'port' is not an integer in
                                            1-65535.
  "<class>: <object class> doesn't know     An object logger has no method for this
    how to deal with the <level> message"   level.  (notice falls back to info.)

  Carp                                      Meaning / Action
  ----------------------------------------  -----------------------------------------
  "Failed to send email: <error>"           SMTP delivery failed.  The other backends
                                            still receive the message.
  "<class>: syslog failed: <error>"         Sys::Syslog::syslog() died.
  "<class>: journald send failed: <error>"  The journald socket could not be reached.
                                            Given once, then not again until a send
                                            succeeds.
  "<class>: Log::Any failed: <error>"       Log::Any (or its adapter) died.  The other
  "<class>: Log::Dispatch failed: <error>"  backends still receive the message.

=head3 PSEUDOCODE

  FUNCTION new(class_or_obj, args...)

    Parse args:
      IF single non-hash scalar
      THEN store as logger shorthand
      ELSE extract named params via Params::Get

    IF config_file present:
      CROAK if file is not readable
      Load via Config::Abstraction, merge into args (constructor args win)
      Restore caller-supplied array ref that config merge would have dropped

    IF called on a blessed instance (clone form):
      CROAK on an invalid timestamp_format or timestamp_precision
      CROAK on an invalid rotate_size, rotate_interval, rotate_keep or
        reopen_interval, and normalise rotate_size to bytes
      CROAK on an invalid redact pattern; compile redact to one regex
      shallow-clone self merged with override args
      validate and store new level integer if level given in args
      copy message history list
      start the clone with no held email digest, no open files, and not
        counted as a user of the SIGHUP handler
      count the clone as a user of an open syslog connection
      build the clone's own backends
      RETURN clone

    IF syslog requested (top level or in a logger hash) and script_name
    not supplied:
      auto-detect script name via File::Basename
      CROAK if still undefined

    IF logger arg is a Log::Abstraction object:
      CROAK (would create a needless forwarding loop)

    IF no logger AND no file AND no fd AND no array:
      load Log::Log4perl, easy_init at DEBUG or ERROR per verbose flag
      store Log4perl logger as the backend

    Normalise and validate level:
      IF level is an arrayref, take first element
      lc() the level string
      CROAK if not in syslog_values lookup
      default to $DEFAULT_LEVEL if not supplied

    CROAK if max_messages is given and is not a non-negative integer
    CROAK if timestamp_format is empty or not a string, or
      timestamp_precision is not an integer 0-9
    CROAK if rotate_size is not a positive size, rotate_interval is not
      hourly/daily/weekly/monthly, or rotate_keep or reopen_interval is not
      a non-negative integer; normalise rotate_size to bytes
    CROAK if a redact pattern is not a regex or non-empty string, doesn't
      compile, or matches the empty string; compile redact to one regex

    FOR each backend (top-level file/fd/array, and the logger hash's
    file/fd/array/syslog/sendmail/journald/log_any/log_dispatch):
      IF log_any: CROAK unless a Log::Any::Proxy, or a category name with
        Log::Any installed
      IF log_dispatch: CROAK unless an object with a log() method
      SKIP the rest unless given as a hash
      CROAK if a file/fd/array/log_any/log_dispatch hash lacks its
        destination key (its own name)
      CROAK if its 'level' is not a level name or 0-7
      CROAK if its 'format' is undef, empty or not a string

    IF logger is a hash:
      CROAK if a sendmail sub-hash has no 'to' address, or a digest_max
        that isn't a positive integer
      CROAK if an extra journald key is not a valid journald field name
      CROAK if it has none of the backend keys

    self = bless { messages => [], merged args, level => numeric } as class
    self->{_backends} = _build_backends()  (CROAK on an unsupported logger)
    RETURN self

  END FUNCTION

=cut