package Foo; use Log::Any qw($log); # log a string $log->error("an error occurred"); # log a string and some data $log->info("program started", {progname => $0, pid => $$, perl_version => $]}); # log a string and data using a format string $log->debugf("arguments are: %s", \@_); # log an error and throw an exception die $log->fatal("a fatal error occurred");
In a Moo/Moose-based module:
package Foo; use Log::Any (); use Moo; has log => ( is => 'ro', default => sub { Log::Any->get_logger }, );
In your application:
use Foo; use Log::Any::Adapter; # Send all logs to Log::Log4perl Log::Any::Adapter->set('Log4perl'); # Send all logs to Log::Dispatch my $log = Log::Dispatch->new(outputs => [[ ... ]]); Log::Any::Adapter->set( 'Dispatch', dispatcher => $log ); # See Log::Any::Adapter documentation for more options
Many modules have something interesting to say. Unfortunately there is no standard way for them to say it - some output to STDERR, others to "warn", others to custom file logs. And there is no standard way to get a module to start talking - sometimes you must call a uniquely named method, other times set a package variable.
This being Perl, there are many logging mechanisms available on CPAN. Each has their pros and cons. Unfortunately, the existence of so many mechanisms makes it difficult for a CPAN author to commit his/her users to one of them. This may be why many CPAN modules invent their own logging or choose not to log at all.
To untangle this situation, we must separate the two parts of a logging API. The first, log production, includes methods to output logs (like "$log->debug") and methods to inspect whether a log level is activated (like "$log->is_debug"). This is generally all that CPAN modules care about. The second, log consumption, includes a way to configure where logging goes (a file, the screen, etc.) and the code to send it there. This choice generally belongs to the application.
A CPAN module uses "Log::Any" to get a log producer object. An application, in turn, may choose one or more logging mechanisms via Log::Any::Adapter, or none at all.
"Log::Any" has a very tiny footprint and no dependencies beyond Perl 5.8.1, which makes it appropriate for even small CPAN modules to use. It defaults to 'null' logging activity, so a module can safely log without worrying about whether the application has chosen (or will ever choose) a logging mechanism.
See <http://www.openswartz.com/2007/09/06/standard-logging-api/> for the original post proposing this module.
trace debug info (inform) notice warning (warn) error (err) critical (crit, fatal) alert emergency
Levels are translated as appropriate to the underlying logging mechanism. For example, log4perl only has six levels, so we translate 'notice' to 'info' and the top three levels to 'fatal'. See the documentation of an adapter class for specifics.
use Log::Any qw($log);
This creates a package variable $log and assigns it to the logger for the current package. It is equivalent to
our $log = Log::Any->get_logger;
In general, to get a logger for a specified category:
my $log = Log::Any->get_logger(category => $category)
If no category is specified, the calling package is used.
A logger object is an instance of Log::Any::Proxy, which passes on messages to the Log::Any::Adapter handling its category.
If the "proxy_class" argument is passed, an alternative to Log::Any::Proxy (such as a subclass) will be instantiated and returned instead. The argument is automatically prepended with ``Log::Any::Proxy::''. If instead you want to pass the full name of a proxy class, prefix it with a ``+''. E.g.
# Log::Any::Proxy::Foo my $log = Log::Any->get_logger(proxy_class => 'Foo'); # MyLog::Proxy my $log = Log::Any->get_logger(proxy_class => '+MyLog::Proxy');
$log->error("this is an error"); $log->warn("this is a warning"); $log->warning("this is also a warning");
The log string will be returned so that it can be used further (e.g. for a "die" or "warn" call).
You should not include a newline in your message; that is the responsibility of the logging mechanism, which may or may not want the newline.
If you want to log additional structured data alongside with your string, you can add a single hashref after your log string. e.g.
$log->info("program started", {progname => $0, pid => $$, perl_version => $]});
If the configured Log::Any::Adapter does not support logging structured data, the hash will be converted to a string using Data::Dumper.
There are also versions of each of the logging methods with an additional ``f'' suffix ("infof", "errorf", "debugf", etc.) that format a list of arguments. The specific formatting mechanism and meaning of the arguments is controlled by the Log::Any::Proxy object.
$log->errorf("an error occurred: %s", $@); $log->debugf("called with %d params: %s", $param_count, \@params);
By default it renders like "sprintf", with the following additional features:
if ($log->is_info()) { ... } $log->debug("arguments are: " . Dumper(\@_)) if $log->is_debug();
This is important for efficiency, as you can avoid the work of putting together the logging message (in the above case, stringifying @_) if the log level is not active.
The formatting methods ("infof", "errorf", etc.) check the log level for you.
Some logging mechanisms don't support detection of log levels. In these cases the detection methods will always return 1.
In contrast, the default logging mechanism - Null - will return 0 for all detection methods.
$log->context->{directory} = $dir; for my $file (glob "$dir/*") { local $log->context->{file} = basename($file); $log->warn("Can't read file!") unless -r $file; }
This will produce the following line:
Can't read file! {directory => '/foo',file => 'bar'}
If the configured Log::Any::Adapter does not support structured data, the context hash will be converted to a string using Data::Dumper, and will be appended to the log message.
use Log::Any '$log', default_adapter => 'Stderr';
The name of the default class follows the same rules as used by Log::Any::Adapter.
To pass arguments to the default adapter's constructor, use an arrayref:
use Log::Any '$log', default_adapter => [ 'File' => '/var/log/mylog.log' ];
When a consumer configures their own adapter, the default adapter will be overridden. If they later remove their adapter, the default adapter will be used again.
use Log::Any '$log', filter => \&myfilter;
For example, to send output to a file via Log::Any::Adapter::File, your application could do this:
use Log::Any::Adapter ('File', '/path/to/file.log');
See the Log::Any::Adapter documentation for more details.
To detect if a consumer exists, use "Log::Any->has_consumer".
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.