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

AUTHOR

Jon Schutz, "<jon at jschutz.net>", <http://notes.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:

RT: CPAN's request tracker
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Log-Dispatch-Scribe>
AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/Log-Dispatch-Scribe>
CPAN Ratings
<http://cpanratings.perl.org/d/Log-Dispatch-Scribe>
Search CPAN
<http://search.cpan.org/dist/Log-Dispatch-Scribe/>

COPYRIGHT & LICENSE

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