.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mail::SpamAssassin::Logger 3pm"
.TH Mail::SpamAssassin::Logger 3pm "2021-03-26" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::SpamAssassin::Logger \- SpamAssassin logging module
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Mail::SpamAssassin::Logger;
\&
\&  $SIG{_\|_WARN_\|_} = sub {
\&    log_message("warn", $_[0]);
\&  };
\&
\&  $SIG{_\|_DIE_\|_} = sub {
\&    log_message("error", $_[0])  if !$^S;
\&  };
.Ve
.SH "METHODS"
.IX Header "METHODS"
.IP "add_facilities(facilities)" 4
.IX Item "add_facilities(facilities)"
Enable debug logging for specific facilities.  Each facility is the area
of code to debug.  Facilities can be specified as a hash reference (the
key names are used), an array reference, an array, or a comma-separated
scalar string. Facility names are case-sensitive.
.Sp
If \*(L"all\*(R" is listed, then all debug facilities are implicitly enabled,
except for those explicitly disabled.  A facility name may be preceded
by a \*(L"no\*(R" (case-insensitive), which explicitly disables it, overriding
the \*(L"all\*(R".  For example: all,norules,noconfig,nodcc.  When facility names
are given as an ordered list (array or scalar, not a hash), the last entry
applies, e.g. 'nodcc,dcc,dcc,noddc' is equivalent to 'nodcc'.  Note that
currently no facility name starts with a \*(L"no\*(R", it is advised to keep this
practice with newly added facility names to make life easier.
.Sp
Higher priority informational messages that are suitable for logging in
normal circumstances are available with an area of \*(L"info\*(R".  Some very
verbose messages require the facility to be specifically enabled (see
\&\f(CW\*(C`would_log\*(C'\fR below).
.ie n .IP "log_message($level, @message)" 4
.el .IP "log_message($level, \f(CW@message\fR)" 4
.IX Item "log_message($level, @message)"
Log a message at a specific level.  Levels are specified as strings:
\&\*(L"warn\*(R", \*(L"error\*(R", \*(L"info\*(R", and \*(L"dbg\*(R".  The first element of the message
must be prefixed with a facility name followed directly by a colon.
.ie n .IP "dbg(""facility: message"")" 4
.el .IP "dbg(``facility: message'')" 4
.IX Item "dbg(facility: message)"
This is used for all low priority debugging messages.
.ie n .IP "info(""facility: message"")" 4
.el .IP "info(``facility: message'')" 4
.IX Item "info(facility: message)"
This is used for informational messages indicating a normal, but
significant, condition.  This should be infrequently called.  These
messages are typically logged when SpamAssassin is run as a daemon.
.ie n .IP "add(method => 'syslog', socket => $socket, facility => $facility)" 4
.el .IP "add(method => 'syslog', socket => \f(CW$socket\fR, facility => \f(CW$facility\fR)" 4
.IX Item "add(method => 'syslog', socket => $socket, facility => $facility)"
\&\f(CW\*(C`socket\*(C'\fR is the type the syslog (\*(L"unix\*(R" or \*(L"inet\*(R").  \f(CW\*(C`facility\*(C'\fR is the
syslog facility (typically \*(L"mail\*(R").
.ie n .IP "add(method => 'file', filename => $file)" 4
.el .IP "add(method => 'file', filename => \f(CW$file\fR)" 4
.IX Item "add(method => 'file', filename => $file)"
\&\f(CW\*(C`filename\*(C'\fR is the name of the log file.
.IP "add(method => 'stderr')" 4
.IX Item "add(method => 'stderr')"
No options are needed for stderr logging, just don't close stderr first.
.IP "remove(method)" 4
.IX Item "remove(method)"
Remove a logging method.  Only the method name needs to be passed as a
scalar.
.ie n .IP "would_log($level, $facility)" 4
.el .IP "would_log($level, \f(CW$facility\fR)" 4
.IX Item "would_log($level, $facility)"
Returns false if a message at the given level and with the given facility
would not be logged.  Returns 1 if a message at a given level and facility
would be logged normally.  Returns 2 if the facility was specifically
enabled.
.Sp
The facility argument is optional.
.IP "\fBclose_log()\fR" 4
.IX Item "close_log()"
Close all logs.