NAME

MouseX::Role::Loggable - Extensive, yet simple, logging role using Log::Dispatchouli

VERSION

version 0.113

SYNOPSIS

package My::Object;

use Mouse;
with 'MouseX::Role::Loggable';

sub do_this {
    my $self = shift;
    $self->set_prefix('[do_this] ');
    $self->log_debug('starting...');
    ...
    $self->log_debug('more stuff');
    $self->clear_prefix;
}

DESCRIPTION

This is a role to provide logging ability to whoever consumes it using Log::Dispatchouli. Once you consume this role, you have attributes and methods for logging defined automatically.

package MyObject;
use Mouse;
with 'MouseX::Role::Loggable';

sub run {
    my $self = shift;

    $self->log('Trying to do something');

    # this only gets written if debug flag is on
    $self->log_debug('Some debugging output');

    $self->log(
        { level => 'critical' },
        'Critical log message',
    );

    $self->log_fatal('Log and die');
}

This module uses Mouse so it takes as little resources as it can by default.

Propagating logging definitions

Sometimes your objects create additional object which might want to log using the same settings. You can simply give them the same logger object.

package Parent;
use Mouse;
with 'MouseX::Role::Loggable';

has child => (
    is      => 'ro',
    isa     => 'Child',
    lazy    => 1,
    builder => '_build_child',
);

sub _build_child {
    my $self = shift;
    return Child->new( logger => $self->logger );
}

ATTRIBUTES

debug

A boolean for whether you're in debugging mode or not.

Default: no.

Read-only.

logger_facility

The facility the logger would use. This is useful for syslog.

Default: local6.

logger_ident

The ident the logger would use. This is useful for syslog.

Default: calling object's class name.

Read-only.

log_to_file

A boolean that determines if the logger would log to a file.

Default location of the file is in /tmp.

Default: no.

Read-only.

log_to_stdout

A boolean that determines if the logger would log to STDOUT.

Default: no.

log_to_stderr

A boolean that determines if the logger would log to STDERR.

Default: no.

log_file

The leaf name for the log file.

Default: undef

log_path

The path for the log file.

Default: undef

log_pid

Whether to append the PID to the log filename.

Default: yes

log_fail_fatal

Whether failure to log is fatal.

Default: yes

log_muted

Whether only fatals are logged.

Default: no

log_quiet_fatal

From Log::Dispatchouli: 'stderr' or 'stdout' or an arrayref of zero, one, or both fatal log messages will not be logged to these.

Default: stderr

logger

A Log::Dispatchouli object.

METHODS

All methods here are imported from Log::Dispatchouli. You can read its documentation to understand them better.

log

Log a message.

log_debug

Log a message only if in debug mode.

log_fatal

Log a message and die.

set_debug

Set the debug flag.

clear_debug

Clear the debug flag.

set_prefix

Set a prefix for all next messages.

clear_prefix

Clears the prefix for all next messages.

set_muted

Sets the mute property, which makes only fatal messages logged.

clear_muted

Clears the mute property.

BUILDARGS

You shouldn't care about this. It takes care of propagating attributes from a given logger (if you provided one) to the attributes this role provides.

log_fields

DEPRECATED.

Please pass the logger attribute instead:

SomeObject->new( logger => $parent->logger );

DEBUGGING

Occassionally you might encounter the following error:

no ident specified when using Log::Dispatchouli at Loggable.pm line 117.

The problem does not stem from MouseX::Role::Loggable, but from a builder calling a logging method before the logger is built. Since Mouse does not assure order of building attributes, some attributes might not yet exist by the time you need them.

This specific error happens when the ident attribute isn't built by the time a builder runs. In order to avoid it, the attribute which uses the builder should be made lazy, and then called in the BUILD method. Here is an example:

package Stuff;

use Mouse;
with 'MouseX::Role::Logger';

has db => (
    is      => 'ro',
    lazy    => 1,
    builder => '_build_db',
}

sub _build_db {
    my $self = shift;
    $self->log_debug('Building DB');
    ...
}

sub BUILD {
    my $self = shift;
    $self->db;
}

This makes the db attribute non-lazy, but during run-time. This will assure that all the logging attributes are created before you build the db attribute and call log_debug.

AUTHORS

  • Sawyer X <xsawyerx@cpan.org>

  • Michael G Schwern <schwern@pobox.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Michael G Schwern.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.