- SEE ALSO
- COPYRIGHT & LICENSE
Log::Dispatch::Scribe - Logging via Facebook's Scribe server software
use Log::Dispatch::Scribe; my $log = Log::Dispatch::Scribe->new( name => 'scribe', min_level => 'info', host => 'localhost', port => 1463, default_category => 'test', retry_plan_a => 'buffer', retry_plan_b => 'die', ); $log->log(level => 'emergency', message => 'something BAD happened'); $log->log(category => 'system', level => 'emergency', message => 'something BAD happened'); # Or, via Log::Log4perl (using YAML style configuration in this example): log4perl.rootLogger: INFO, Scribe log4perl.appender.Scribe: Log::Dispatch::Scribe log4perl.appender.Scribe.host: localhost log4perl.appender.Scribe.port: 1465 log4perl.appender.Scribe.category: system log4perl.appender.Scribe.layout: Log::Log4perl::Layout::PatternLayout log4perl.appender.Scribe.layout.ConversionPattern: "[%d] [%p] %m%n" use Log::Log4perl; Log::Log4perl->init('log4perlconfig.yml'); # initialise using config file $log = Log::Log4perl->get_logger('example.usage'); $log->info("..."); # Log an info message via Log::Log4perl $log->log($INFO, "..."); # alternative syntax
Scribe is a server for aggregating log data streamed in real time from a large number of servers. It is designed to be scalable, extensible without client-side modification, and robust to failure of the network or any specific machine. Scribe was developed at Facebook and released as open source.
Scribe, and the related Thrift Perl modules, are available from the respective source distributions (as of this writing, the modules are not available on CPAN). When compiling Scribe, ensure that the namespace is set to 'namespace perl Scribe.Thrift' in the scribe.thrift file. Further information is available here: http://notes.jschutz.net/109/perl/perl-client-for-facebooks-scribe-logging-software.
A Scribe category is an identifier that determines how Scribe handles the message. Scribe configuration files define logging behaviour per-category (or by category prefix, or by a default behaviour if no matching category is found).
Log::Log4perl also uses logger 'categories' which can be used to filter messages. Log4perl categories will typically be more fine-grained that Scribe categories, but could also conceivably have a 1:1 mapping depending on system design.
Log::LogDispatch::Scribe has several ways of specifying categories to handle these situations. 'category' and 'default_category' values may be passed to the constructor, and 'category' and 'log4p_category' values may be passed to the log_message method. These are handled as follows:
'category' passed to the constructor overrides all other values and will always be used if defined. This essentially fixes the Scribe category for this logger instance.
'category' passed to log_message() will be used otherwise, if defined.
'log4p_category' passed to log_message() will be used otherwise, if defined. Log4perl sets this parameter from the logger category.
'default_category' passed to the constructor is used where no other category parameters have been set. If no 'default_category' is given, it defaults to 'none'.
A Scribe server is expected to be listening for log messages on a given host and port number.
The standard behaviour of most Log::Dispatch::* loggers is to die on error, such as when a file cannot be written. It is feasible that the Scribe server might be restarted from time to time resulting in temporary connection failures, and it would not be very satisfactory if one's Perl application should die just because of a temporary outage of the Scribe server. Log::Dispatch::Scribe offers several options for retrying delivery of log messages.
The retry behaviour is set through 'retry_plan_a' and 'retry_plan_b' parameters. Plan A is tried first, and if that fails, then Plan B. There is no Plan C. The 'retry_plan_*' parameters may have any of the following values:
Die immediately. Plan B becomes irrelevant if this is the setting for Plan A.
The Perl application blocks, waiting forever in a loop to reconnect to the Scribe server, retrying after a specified 'retry_delay'. Plan B becomes irrelevant if this is the setting for Plan A.
The Perl application blocks, waiting for 'retry_delay' seconds, up to 'retry_count' times, then move on to the next plan if possible, otherwise die. (Note that the count is not doubled if both Plan A and B are 'wait_count').
Discard the current message and return immediately, allowing the Perl application to continue.
Buffer messages up to the given 'retry_buffer_size' (a count of number of messages, not bytes), then move on to the next plan if the buffer fills. This allows the Perl application to continue at least until the buffer fills.
The default settings are:
retry_plan_a => 'buffer', retry_buffer_size => 1000, retry_plan_b => 'discard',
in which case the first 1000 messages will be kept, then subsequent messages discarded until the Scribe service recovers. The first 1000 messages will then be flushed to Scribe as soon as it recovers.
$log = Log::Dispatch::Scribe->new(%params);
This method takes a hash of parameters. The following options are valid:
name, min_level, max_level, callbacks
Same as various Log::Dispatch::* classes.
The host and port number of the Scribe server.
See above under "Scribe Categories".
See above under "Scribe Server and Error Handling".
Maximum number of messages to hold in a memory buffer if Scribe becomes unavailable and a retry plan is set to 'buffer'. See above under "Scribe Server and Error Handling". Defaults to 1000.
For the 'wait_forever' and 'wait_count' retry plans, the time interval (in seconds) between attempts to reconnect. See above under "Scribe Server and Error Handling". Defaults to 10 seconds.
For the 'wait_count' retry plans, the number of times to retry before giving up. See above under "Scribe Server and Error Handling". Defaults to 100.
$log->log( level => $level, message => $message, category => $category )
<jon at jschutz.net>, http://notes.jschutz.net
Please report any bugs or feature requests to
bug-log-dispatch-scribe at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Log-Dispatch-Scribe. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
You can find documentation for this module with the perldoc command.
You can also look for information at:
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
Copyright 2009 Jon Schutz, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.