=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 => 'stderr';

=head1 DESCRIPTION

This dispatchers produces output to syslog, based on the Sys::Syslog
module (which will NOT be automatically installed for you).

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

=head1 METHODS

=head2 Constructors

$obj-E<gt>B<close>

=over 4

See L<Log::Report::Dispatcher/"Constructors">

=back

Log::Report::Dispatcher::Syslog-E<gt>B<new>(TYPE, NAME, OPTIONS)

=over 4

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.  Use L<new(format_reason)|Log::Report::Dispatcher/"Constructors"> with C<IGNORE> to achieve
that.

 Option       --Defined in     --Default
 accept         Log::Report::Dispatcher  depend on mode
 facility                        'user'
 flags                           'pid,nowait'
 format_reason  Log::Report::Dispatcher  'LOWERCASE'
 identity                        <basename $0>
 locale         Log::Report::Dispatcher  <system locale>
 mode           Log::Report::Dispatcher  'NORMAL'
 to_prio                         []

. accept => REASONS

. facility => STRING

=over 4

The possible values for this depend (a little) on the system.  POSIX
only defines 'user' and 'local0' upto 'local7'.

=back

. flags => STRING

=over 4

Any combination of C<pid>, C<ndelay>, and C<nowait>, used with
C<openlog(3)> if needed

=back

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

. identity => STRING

. locale => LOCALE

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

. to_prio => ARRAY-of-PAIRS

=over 4

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

=back

=back

=head2 Accessors

$obj-E<gt>B<isDisabled>

=over 4

See L<Log::Report::Dispatcher/"Accessors">

=back

$obj-E<gt>B<mode>

=over 4

See L<Log::Report::Dispatcher/"Accessors">

=back

$obj-E<gt>B<name>

=over 4

See L<Log::Report::Dispatcher/"Accessors">

=back

$obj-E<gt>B<needs>

=over 4

See L<Log::Report::Dispatcher/"Accessors">

=back

$obj-E<gt>B<type>

=over 4

See L<Log::Report::Dispatcher/"Accessors">

=back

=head2 Logging

$obj-E<gt>B<collectLocation>

=over 4

See L<Log::Report::Dispatcher/"Logging">

=back

$obj-E<gt>B<collectStack>([MAXDEPTH])

=over 4

See L<Log::Report::Dispatcher/"Logging">

=back

$obj-E<gt>B<log>(HASH-of-OPTIONS, REASON, MESSAGE)

=over 4

See L<Log::Report::Dispatcher/"Logging">

=back

$obj-E<gt>B<reasonToPrio>(REASON)

=over 4

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">.

=back

$obj-E<gt>B<stackTraceLine>(OPTIONS)

Log::Report::Dispatcher::Syslog-E<gt>B<stackTraceLine>(OPTIONS)

=over 4

See L<Log::Report::Dispatcher/"Logging">

=back

$obj-E<gt>B<translate>(HASH-of-OPTIONS, REASON, MESSAGE)

=over 4

See L<Log::Report::Dispatcher/"Logging">

=back

=head1 DETAILS

=head1 SEE ALSO

This module is part of Log-Report distribution version 0.07,
built on June 20, 2007. Website: F<http://perl.overmeer.net/log-report/>

=head1 LICENSE

Copyrights 2007 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>

