view release on metacpan or  search on metacpan

lib/Fugu/Log.pod  view on Meta::CPAN

=head1 NAME

Fugu::Log - logging to syslog, standard error, or nowhere

=head1 SYNOPSIS

    use Fugu::Log;

    my $log = Fugu::Log->new(
        mode     => 'syslog',
        ident    => 'mydaemon',
        level    => 'info',
        facility => 'daemon',
    );

    $log->info('listening on port %d', $port);
    $log->error('cannot open %s: %s', $path, $!);

    Fugu::Log->set_default($log);

=head1 DESCRIPTION

B<Fugu::Log> gives a program one logging interface. The interface is
the same when the program runs as a daemon and when it runs in the
foreground. The caller selects the destination one time, when it
creates the logger. Every call site then has the same form for all
destinations.

The logger discards messages below the configured level. The levels,
from lowest to highest, are C<debug>, C<info>, C<notice>, C<warning>
and C<error>. Each level is a method of the same name, and there is
one spelling for each level.

The module also holds one process default logger. Library code that
gets no logger asks for it with C<default>, so no library has to die
for the lack of one.

=head2 new

C<new(%args)> creates a logger. These are the arguments:

=over 4

=item C<mode>

The destination for messages. The value is one of:

=over 4

=item C<syslog>

Messages go through syslog(3). The logger pins the transport to the
C<native> mechanism with C<setlogsock> from L<Sys::Syslog>, and then
calls openlog(3) immediately with the C<ndelay> and C<pid> options.

The pin keeps a pledged daemon alive. On OpenBSD the C<native>
mechanism delivers with sendsyslog(2), which sits inside the C<stdio>
promise. Every other mechanism opens a socket, and a daemon that
pledges C<stdio> dies at that call.

=item C<stderr>

Messages go to standard error, with one line for each message. Each
line starts with a local-time stamp and the level in upper case.

=item C<quiet>

Messages go nowhere. The logger discards them before it does a check
of the level.

=back

The default is C<stderr>.

=item C<level>

The lowest level to emit. The default is C<info>.

=item C<ident>

The program name that the logger passes to openlog(3). The default is
C<fugu>. The logger uses this argument only when C<mode> is
C<syslog>.

=item C<facility>

The syslog facility. The value is a L<Sys::Syslog> constant, or one
of the names C<daemon>, C<user> or C<local0> through C<local7>. The
default is C<LOG_DAEMON>.

=back

=head2 debug, info, notice, warning, error

    $log->info($fmt, @args);

Each method logs one message at the level that its name gives. When
C<@args> is not empty, the method formats C<$fmt> through sprintf(3).
When C<@args> is empty, the method uses C<$fmt> as a literal string.

There is one method for each level, and no other spelling parses.

=head2 set_level

C<set_level($level)> changes the lowest level to emit on a logger
after its creation. If the value is not a known level name, the
logger uses C<info>.

=head2 level

C<level> returns the lowest level to emit, by name. The name is one
of the six canonical levels, whatever spelling the caller used.

=head2 mode

C<mode> returns the destination, one of the C<MODE_SYSLOG>,