/ 
Log-Dispatch-Scribe-0.04
River stage one • 1 direct dependent • 1 total dependent
/ Log::Dispatch::Scribe

NAME

Log::Dispatch::Scribe - Logging via Facebook's Scribe server software

SYNOPSIS

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

DESCRIPTION

This module provides a Log::Dispatch style interface to Scribe, and is also fully compatible with Log::Log4perl.

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.

Installing Scribe and Thrift Perl Modules

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.

Scribe Categories

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'.

Scribe Server and Error Handling

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

    Die immediately. Plan B becomes irrelevant if this is the setting for Plan A.

  • wait_forever

    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.

  • wait_count

    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

    Discard the current message and return immediately, allowing the Perl application to continue.

  • buffer

    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.

METHODS

new
$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.

  • host, port

    The host and port number of the Scribe server.

  • category, default_category

    See above under "Scribe Categories".

  • retry_plan_a, retry_plan_b

    See above under "Scribe Server and Error Handling".

  • retry_buffer_size

    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.

  • retry_delay

    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.

  • retry_count

    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->log( level => $level, message => $message, category => $category  )

As for "log" in Log::Dispatch, but also supports passing in a 'category' parameter to specify the Scribe category, and 'log4p_category'. See above under "Scribe Categories".

SEE ALSO

AUTHOR

Jon Schutz, <jon at jschutz.net>

BUGS

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.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Log::Dispatch::Scribe

You can also look for information at:

COPYRIGHT & LICENSE

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.