Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MooseX::Role::LoggableUser Contributed Perl DocumentaMooseX::Role::Loggable(3)

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

VERSION
       version 0.114

SYNOPSIS
	   package My::Object;

	   use Moose; #	or Moo
	   with	'MooseX::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 Moose # Moo works too
	   with	'MooseX::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	Moo so it takes	as little resources as it can by
       default,	and can	seamlessly work	with both Moo or Moose.

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 Moose;
	   with	'MooseX::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.

   has_log_file
       Determines if "log_file"	was specified.

   has_log_path
       Determines if "log_path"	was specified.

   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 MooseX::Role::Loggable, but from a
       builder calling a logging method	before the logger is built. Since Moo
       and Moose do 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 Moose;
	   with	'MooseX::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".

AUTHOR
       Sawyer X	<xsawyerx@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2017 by Sawyer X.

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

perl v5.32.1			  2017-02-12	     MooseX::Role::Loggable(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | Propagating logging definitions | ATTRIBUTES | METHODS | DEBUGGING | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MooseX::Role::Loggable&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help