Jon Schutz > Log-Dispatch-Scribe > Log::Dispatch::Scribe

Download:
Log-Dispatch-Scribe-0.05.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.05   Source  

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:

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:

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>, 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:

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.

syntax highlighting: