Index of /manual/software/flog/current

	Name	Last modified	Size	Description
	Parent Directory		-
	sample.conf/	08-Jan-2012 13:02	-
	stingy.pl	19-Jan-2006 20:23	1.0K
	flog.catman	19-Jan-2006 20:23	5.3K
	TODO	19-Jan-2006 20:23	385
	NOTE	19-Jan-2006 20:23	255
	INSTALL	19-Jan-2006 20:23	262
	4k-block	19-Jan-2006 20:23	4.0K
	flog	19-Jan-2006 20:23	2.5K
	CHANGELOG	19-Jan-2006 20:23	405

flog(n)							  flog(n)

NAME
	flog - real time log splitter and viewer

SYNOPSIS
	flog  -c=file [ -d[=file] ] [ -g=GID|group ]  [ -u=UID|
	user ] [ -o ]

DESCRIPTION
	flog grew out of the desire to have Apache httpd(8) dir-
	ect log output to  multiple files dependent  upon various
	parameters. While

	CustomLog file-pipe format-or-nickname env=[!]environment-variable

	is pretty nifty it's basically an if-then-else construct,
	and I desired more of a switch-case one.  Hence flog was
	born.

	Yes,  there are other means of acheiving similar results.
	Apache::Request with mod_perl comes to mind.

OPTIONS
	-c=file
		Use configuration file

	-d
	-d=file
		Open file in  clobber mode for  debug output.  If
		file is not specified /dev/tty8 is used instead.

	-g=GID|group
		flog will run as the group specified

	-o
		flog will  NOT  pre-open  all of %FILES  for you.
		You'll need to use printFlog instead of print.

		printFlog(FH, [close])

		printFlog's first argument is the filehandle to
		open (if necessary). If its second argument is
		true, it will close the file after writing. See
		CAVEATS

	-u=UID|user
		flog will run as the user specified

CONFIGURATION
	Configuration of flog is meant to be fairly straight for-
	ward.  The configuration  file should contain  at least a
	global hash named FILES, and a sub named flog.

	%FILES
		The keys for  %FILES  are  file descriptor  names
		which flog will automatically open for you.

		The values for  %FILES are  anonymous arrays. The
		first index  is the  file name  to be  associated
		with the  key/file handle. If the second index is
		present  and  true,  the file handle  will be un-
		buffered. See CAVEATS

	Flog::init();
		A call to this function after declaring %FILES.

	sub flog
		The subroutine  called for each  log entry  which
		contains the logic  to determine where  the entry
		should be output to. It takes no arguments.

SIGNALS
	flog will respond  to various signals.  Listed below are
	those that have special meaning.
	
	HUP
		Flush buffers, reread the configuration file, and
		reopen all of %FILEs unless -o is was used.

	INT, PIPE, TERM
		Flush buffers and exit.

	USR1
		Flush buffers.
		NOT YET IMPLEMENTED

	USR2
		Flush  buffers.  Toggle  the  pausing  of  output
		(queueing input) useful for log rotation etc.
		NOT YET IMPLEMENTED 


CAVEATS
	The -g and -u options  only work if the current user is
	allowed to setuid. This is typically root.

	From perlfaq5
	In most stdio implementations, the type of output buffer-
	ing and the  size of the  buffer varies  according to the
	type of device. Disk files are block buffered, often with
	a buffer size of more than 2k.

	4k seems pretty typical, to get an idea what 4k of log is
	examine the 4k-block file in the root directory of the
	flog package.

	Pros
		Buffering helps your system reduce I/O.  Big deal
		you say?  Well,  more often  than not  I/O is the
		main bottleneck in modern systems.  Especially on
		web servers.  So you typically want to do as lit-
		tle writing to the disk as possible.

		Closing and reopening a file as printFlog does is
		moderately expensive, since close forces a write.

	Cons
		flog's  buffered logs are  slightly more prone to
		data loss or  corruption than an  unbuffered log.
		If the  system  undergoes a  disorderly shutdown,
		i.e.;  flog does not receive a  recognized signal
		it won't have a chance to flush its buffers.  And
		since the buffer is block/byte-wise and not line-
		wise,  if this were to occur  your log may become
		corrupt. The last write may not have ended with a
		newline. However this  could easily be fixed with
		a text editor.

		Each open buffered log will consume 0-4k  for the
		actual data buffer, and a filehandle.

	In conclusion;  if resource usage is critical  use -o, if
	resources are  not an issue,  but the  low potential  for
	data loss is unexceptable, use an unbuffered log.  Other-
	wise use a buffered log.

TODO
	Build in  log rotation,  or support  external rotation by
	flushing then pausing output during rotation.

SEE ALSO
	httpd(8), PERL(1).

	Documentation on  Apache  log file-pipe  configuration is
	available from
	http://www.apache.org/docs/mod/mod_log_config.html#transferlog

LICENSE
        LGPL or Perl artistic license.
AUTHORS
	Bug reports to: webmaster@pthbb.org