The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
MARKOV / Log-Report-1.16 / lib / Log / Report / Dispatcher / Syslog.pod 
=encoding utf8

=head1 NAME

Log::Report::Dispatcher::Syslog - send messages to syslog

=head1 INHERITANCE

 Log::Report::Dispatcher::Syslog
   is a Log::Report::Dispatcher

=head1 SYNOPSIS

 # add syslog dispatcher
 dispatcher SYSLOG => 'syslog', accept => 'NOTICE-'
   , format_reason => 'IGNORE'
   , to_prio => [ 'ALERT-' => 'err' ];

 # disable default dispatcher, when daemon
 dispatcher close => 'default';

=head1 DESCRIPTION

This dispatchers produces output to syslog, based on the Sys::Syslog
module (which will NOT be automatically installed for you, because some
systems have a problem with this dependency).

The REASON for a message often uses names which are quite similar to
the log-levels used by syslog.  However: they have a different purpose.
The REASON is used by the programmer to indicate the cause of the message:
whether it was able to handle a certain situation.  The syslog levels
are there for the user's of the program (with syslog usually the
system administrators).  It is not unusual to see a "normal" error
or mistake as a very serious situation in a production environment. So,
you may wish to translate any message above reason MISTAKE into a LOG_CRIT.

The default translation table is list below.  You can change the mapping
using L<new(to_prio)|Log::Report::Dispatcher::Syslog/"Constructors">.  See example in SYNOPSIS.

  TRACE   => LOG_DEBUG    ERROR   => LOG_ERR
  ASSERT  => LOG_DEBUG    FAULT   => LOG_ERR
  INFO    => LOG_INFO     ALERT   => LOG_ALERT
  NOTICE  => LOG_NOTICE   FAILURE => LOG_EMERG
  WARNING => LOG_WARNING  PANIC   => LOG_CRIT
  MISTAKE => LOG_WARNING

Extends L<"DESCRIPTION" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DESCRIPTION">.
 
=head1 METHODS

Extends L<"METHODS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"METHODS">.
 
=head2 Constructors

Extends L<"Constructors" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Constructors">.
 
=over 4

=item $obj-E<gt>B<close>()

Inherited, see L<Log::Report::Dispatcher/"Constructors">

=item Log::Report::Dispatcher::Syslog-E<gt>B<new>($type, $name, %options)

With syslog, people tend not to include the REASON of the message
in the logs, because that is already used to determine the destination
of the message.

 -Option        --Defined in             --Default
  accept          Log::Report::Dispatcher  depend on mode
  charset                                  'utf8'
  facility                                 'user'
  flags                                    'pid,nowait'
  format                                   <unchanged>
  format_reason   Log::Report::Dispatcher  'IGNORE'
  identity                                 <basename $0>
  include_domain                           <false>
  locale          Log::Report::Dispatcher  <system locale>
  logsocket                                undef
  mode            Log::Report::Dispatcher  'NORMAL'
  to_prio                                  []

=over 2

=item accept => REASONS

=item charset => CHARSET

Translate the text-strings into the specified charset, otherwise the
sysadmin may get unreadable text.

=item facility => STRING

The possible values for this depend (a little) on the system.  POSIX
only defines C<user>, and C<local0> up to C<local7>.

=item flags => STRING

Any combination of flags as defined by Sys::Syslog, for instance
C<pid>, C<ndelay>, and C<nowait>.

=item format => CODE

[1.10] With a CODE reference you get your hands on the text before
it gets sent to syslog.  The three parameters are: the (translated) text,
the related text domain object, and the message object.  You may want to
use context information from the latter.

=item format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE

=item identity => STRING

=item include_domain => BOOLEAN

[1.00] Include the text-domain of the message in each logged message.

=item locale => LOCALE

=item logsocket => 'unix'|'inet'|'stream'|HASH

If specified, the log socket type will be initialized to this before
C<openlog()> is called.  If not specified, the system default is used.

=item mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3

=item to_prio => ARRAY-of-PAIRS

See L<reasonToPrio()|Log::Report::Dispatcher::Syslog/"Logging">.

=back

=back

=head2 Accessors

Extends L<"Accessors" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Accessors">.
 
=over 4

=item $obj-E<gt>B<format>( [CODE] )

Returns the CODE ref which formats the syslog line.

=item $obj-E<gt>B<isDisabled>()

Inherited, see L<Log::Report::Dispatcher/"Accessors">

=item $obj-E<gt>B<mode>()

Inherited, see L<Log::Report::Dispatcher/"Accessors">

=item $obj-E<gt>B<name>()

Inherited, see L<Log::Report::Dispatcher/"Accessors">

=item $obj-E<gt>B<needs>( [$reason] )

Inherited, see L<Log::Report::Dispatcher/"Accessors">

=item $obj-E<gt>B<type>()

Inherited, see L<Log::Report::Dispatcher/"Accessors">

=back

=head2 Logging

Extends L<"Logging" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Logging">.
 
=over 4

=item $obj-E<gt>B<addSkipStack>(@CODE)

=item Log::Report::Dispatcher::Syslog-E<gt>B<addSkipStack>(@CODE)

Inherited, see L<Log::Report::Dispatcher/"Logging">

=item $obj-E<gt>B<collectLocation>()

=item Log::Report::Dispatcher::Syslog-E<gt>B<collectLocation>()

Inherited, see L<Log::Report::Dispatcher/"Logging">

=item $obj-E<gt>B<collectStack>( [$maxdepth] )

=item Log::Report::Dispatcher::Syslog-E<gt>B<collectStack>( [$maxdepth] )

Inherited, see L<Log::Report::Dispatcher/"Logging">

=item $obj-E<gt>B<log>(HASH-$of-%options, $reason, $message, $domain)

Inherited, see L<Log::Report::Dispatcher/"Logging">

=item $obj-E<gt>B<reasonToPrio>($reason)

Returns a level which is understood by syslog(3), based on a translation
table.  This can be changed with L<new(to_prio)|Log::Report::Dispatcher::Syslog/"Constructors">.

=item $obj-E<gt>B<skipStack>()

Inherited, see L<Log::Report::Dispatcher/"Logging">

=item $obj-E<gt>B<stackTraceLine>(%options)

=item Log::Report::Dispatcher::Syslog-E<gt>B<stackTraceLine>(%options)

Inherited, see L<Log::Report::Dispatcher/"Logging">

=item $obj-E<gt>B<translate>(HASH-$of-%options, $reason, $message)

Inherited, see L<Log::Report::Dispatcher/"Logging">

=back

=head1 DETAILS

Extends L<"DETAILS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DETAILS">.
 
=head1 SEE ALSO

This module is part of Log-Report distribution version 1.16,
built on May 27, 2016. Website: F<http://perl.overmeer.net/log-report/>

=head1 LICENSE

Copyrights 2007-2016 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>