The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Log-Unrotate-1.25
River stage one • 1 direct dependent • 1 total dependent
1 ++
/ Log::Unrotate

NAME

Log::Unrotate - Reader of rotated logs.

VERSION

version 1.25

SYNOPSIS

  use Log::Unrotate;

  my $reader = Log::Unrotate->new({
      log => 'xxx.log',
      pos => 'xxx.pos',
  });

  $reader->read();
  $reader->read();
  $reader->read();
  $reader->commit();
  my $position = $reader->position();
  $reader->read();
  $reader->read();
  $reader->commit($position); # rollback the last 2 reads
  my $lag = $reader->lag();

DESCRIPTION

The Log::Unrotate is a class that implements incremental and transparent reading of a log file which correctly handles logrotates.

It tries really hard to never skip any data from logs. If it's not sure about what to do, it fails, and you should either fix your position file manually, or remove it completely.

METHODS

new($params)

Creates new unrotate object.

pos

Name of file to store log reading position. Will be created automatically if missing.

Value '-' means not use position file. I.e., pretend it doesn't exist at start and ignore commit calls.

cursor

Instead of pos file, you can specify any custom cursor. See Log::Unrotate::Cursor for cursor API details.

autofix_cursor

Recreate cursor if it's broken.

Warning will be printed. This option is dangerous and shouldn't be enabled light-heartedly.

log

Name of log file. Value '-' means standard input stream.

start

Describes behavior when position file doesn't exist. Allowed values: begin (default), end, first.

  • When start is begin, we'll read current log from beginning.

  • When start is end, we'll put current position in log at the end (useful for big files when some new script don't need to read everything).

  • When start is first, Log::Unrotate will find oldest log file and read everything.

end

Describes behavior when the log is asynchronously appended while read. Allowed values: fixed (default), future.

  • When end is fixed, the log is read up to the position it had when the reader object was created.

  • When end is future, it allows reading the part of the log that was appended after the reader creation (useful for reading from stdin).

lock

Describes locking behaviour. Allowed values: none (default), blocking, nonblocking.

  • When lock is blocking, lock named pos.lock will be acquired in blocking mode.

  • When lock is nonblocking, lock named pos.lock will be acquired in nonblocking mode; if lock file is already locked, exception will be thrown.

check_inode

This flag is disabled by default.

It enables inode checks when detecting log rotations. This option should not be enabled when retrieving logs via rsync or some other way which modifies inodes.

check_lastline

This flag is set by default. It enables content checks when detecting log rotations. There is actually no reason to disable this option.

read()

Read a string from the file log.

position()

Get your current position in log as an object passible to commit.

commit(;$)

Save current position in the file pos. You can also save some other position, previosly taken with position.

Position file gets commited using temporary file, so it'll not be lost if disk space is depleted.

lag()

Get the lag between current position and the end of the log in bytes.

log_number()

Get current log number.

log_name()

Get current log name. Don't contain .N postfix even if cursor points to old log file.

BUGS & CAVEATS

To find and open correct log is a race-condition-prone task.

This module was used in production environment for 3 years, and many bugs were found and fixed. The only known case when position file can become broken is when logrotate is invoked twice in *very* short amount of time, which should never be a case.

Don't set check_inode option on virtual hosts, especially on openvz-based ones. When host migrates, inodes of files will change and your position file will become broken.

The logrotate config should not use the "compress" option to make that module function properly. If you need to compress logs, set "delaycompress" option too.

AUTHORS

Andrei Mishchenko druxa@yandex-team.ru, Vyacheslav Matjukhin mmcleric@yandex-team.ru.

SEE ALSO

File::LogReader - another implementation of the same idea.

unrotate(1) - console script to unrotate logs.

COPYRIGHT

Copyright (c) 2006-2010 Yandex LTD. All rights reserved.

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

See <http://www.perl.com/perl/misc/Artistic.html>