Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Log::Dispatch::Scribe(User Contributed Perl DocumentatLog::Dispatch::Scribe(3)

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:

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

       o   'category' passed to	log_message() will be used otherwise, if
	   defined.

       o   'log4p_category' passed to log_message() will be used otherwise, if
	   defined.  Log4perl sets this	parameter from the logger category.

       o   '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:

       o   die

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

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

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

       o   discard

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

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

	   o   name, min_level,	max_level, callbacks

	       Same as various Log::Dispatch::*	classes.

	   o   host, port

	       The host	and port number	of the Scribe server.

	   o   category, default_category

	       See above under "Scribe Categories".

	   o   retry_plan_a, retry_plan_b

	       See above under "Scribe Server and Error	Handling".

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

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

	   o   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
       o   <http://notes.jschutz.net/109/perl/perl-client-for-facebooks-scribe-logging-software>

       o   <http://github.com/facebook/scribe/>

       o   Log::LogDispatch

       o   Log::Log4perl

       o   File::Tail::Scribe, tail_to_scribe.pl

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:

       o   RT: CPAN's request tracker

	   <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Log-Dispatch-Scribe>

       o   AnnoCPAN: Annotated CPAN documentation

	   <http://annocpan.org/dist/Log-Dispatch-Scribe>

       o   CPAN	Ratings

	   <http://cpanratings.perl.org/d/Log-Dispatch-Scribe>

       o   Search CPAN

	   <http://search.cpan.org/dist/Log-Dispatch-Scribe/>

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.

perl v5.32.0			  2018-01-02	      Log::Dispatch::Scribe(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | SEE ALSO | AUTHOR | BUGS | SUPPORT | COPYRIGHT & LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Log::Dispatch::Scribe&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help