NAME¶
POE::Wheel::FollowTail - follow the tail of an ever-growing file
SYNOPSIS¶
#!perl
use POE qw(Wheel::FollowTail);
POE::Session->create(
inline_states => {
_start => sub {
$_[HEAP]{tailor} = POE::Wheel::FollowTail->new(
Filename => "/var/log/system.log",
InputEvent => "got_log_line",
ResetEvent => "got_log_rollover",
);
},
got_log_line => sub {
print "Log: $_[ARG0]\n";
},
got_log_rollover => sub {
print "Log rolled over.\n";
},
}
);
POE::Kernel->run();
exit;
DESCRIPTION¶
POE::Wheel::FollowTail objects watch for new data at the end of a file and
generate new events when things happen to the file. Its "Filter"
parameter defines how to parse data from the file. Each new item is sent to
the creator's session as an "InputEvent" event. Log rotation will
trigger a "ResetEvent".
POE::Wheel::FollowTail only reads from a file, so it doesn't implement a
put() method.
PUBLIC METHODS¶
new¶
new() returns a new POE::Wheel::FollowTail object. As long as this object
exists, it will generate events when the corresponding file's status changes.
new() accepts a small set of named parameters:
Driver
The optional "Driver" parameter specifies which driver to use when
reading from the tailed file. If omitted, POE::Wheel::FollowTail will use
POE::Driver::SysRW. This is almost always the right thing to do.
Filter
"Filter" is an optional constructor parameter that specifies how to
parse data from the followed file. By default, POE::Wheel::FollowTail will use
POE::Filter::Line to parse files as plain, newline-separated text.
$_[HEAP]{tailor} = POE::Wheel::FollowTail->new(
Filename => "/var/log/snort/alert",
Filter => POE::Filter::Snort->new(),
InputEvent => "got_snort_alert",
);
PollInterval
POE::Wheel::FollowTail needs to periodically check for new data on the followed
file. "PollInterval" specifies the number of seconds to wait between
checks. Applications that need to poll once per second may omit
"PollInterval", as it defaults to 1.
Longer poll intervals may be used to reduce the polling overhead for
infrequently updated files.
$_[HEAP]{tailor} = POE::Wheel::FollowTail->new(
...,
PollInterval => 10,
);
Seek
If specified, "Seek" instructs POE::Wheel::FollowTail to seek to a
specific spot in the tailed file before beginning to read from it. A positive
"Seek" value is interpreted as the number of octets to seek from the
start of the file. Negative "Seek" will, like negative array
indices, seek backwards from the end of the file. Zero "Seek" starts
reading from the beginning of the file.
Be careful when using "Seek", as it's quite easy to seek into the
middle of a record. When in doubt, and when beginning at the end of the file,
omit "Seek" entirely. POE::Wheel::FollowTail will seek 4 kilobytes
back from the end of the file, then parse and discard all records unto EOF. As
long as the file's records are smaller than 4 kilobytes, this will guarantee
that the first record returned will be complete.
"Seek" may also be used with the wheel's
tell() method to
restore the file position after a program restart. Save the
tell()
value prior to exiting, and load and "Seek" back to it on subsequent
start-up.
SeekBack
"SeekBack" behaves like the inverse of "Seek". A positive
value acts like a negative "Seek". A negative value acts like a
positive "Seek". A zero "SeekBack" instructs
POE::Wheel::FollowTail to begin at the very end of the file.
"Seek" and "SeekBack" are mutually exclusive.
See "Seek" for caveats, techniques, and an explanation of the magic
that happens when neither "Seek" nor "SeekBack" is
specified.
Handle
POE::Wheel::FollowTail may follow a previously opened file "Handle".
Unfortunately it cannot follow log resets this way, as it won't be able to
reopen the file once it has been reset. Applications that must follow resets
should use "Filename" instead.
"Handle" is still useful for files that will never be reset, or for
devices that require setup outside of POE::Wheel::FollowTail's purview.
"Handle" and "Filename" are mutually exclusive. One of them
is required, however.
Filename
Specify the "Filename" to watch. POE::Wheel::FollowTail will wait for
the file to appear if it doesn't exist. The wheel will also reopen the file if
it disappears, such as when it has been reset or rolled over. In the case of a
reset, POE::Wheel::FollowTail will also emit a "ResetEvent", if one
has been requested.
"Handle" and "Filename" are mutually exclusive. One of them
is required, however.
See the "SYNOPSIS" for an example.
IdleEvent
"IdleEvent" is an optional event. If specified, it will fire whenever
POE::Wheel::FollowTail checks for activity but sees nothing. It was added in
POE 1.362 as a way to advance certain test programs without needing to wait
conservatively large amounts of time.
"IdleEvent" is described in "PUBLIC EVENTS".
InputEvent
The "InputEvent" parameter is required, and it specifies the event to
emit when new data arrives in the watched file. "InputEvent" is
described in detail in "PUBLIC EVENTS".
ResetEvent
"ResetEvent" is an optional. It specifies the name of the event that
indicates file rollover or reset. Please see "PUBLIC EVENTS" for
more details.
ErrorEvent
POE::Wheel::FollowTail may emit optional "ErrorEvent"s whenever it
runs into trouble. The data that comes with this event is explained in
"PUBLIC EVENTS".
event¶
event() allows a session to change the events emitted by a wheel without
destroying and re-creating the object. It accepts one or more of the events
listed in "PUBLIC EVENTS". Undefined event names disable those
events.
Stop handling log resets:
sub some_event_handler {
$_[HEAP]{tailor}->event( ResetEvent => undef );
}
The events are described in more detail in "PUBLIC EVENTS".
The
ID() method returns the wheel's unique ID. It's useful for storing
the wheel in a hash. All POE::Wheel events should be accompanied by a wheel
ID, which allows the wheel to be referenced in their event handlers.
sub setup_tailor {
my $wheel = POE::Wheel::FollowTail->new(... incomplete ...);
$_[HEAP]{tailors}{$wheel->ID} = $wheel;
}
See the example in "ErrorEvent" for a handler that will find this
wheel again.
tell¶
tell() returns the current position for the file being watched by
POE::Wheel::FollowTail. It may be useful for saving the position program
termination.
new()'s "Seek" parameter may be used to resume
watching the file where
tell() left off.
sub handle_shutdown {
# Not robust. Do better in production.
open my $save, ">", "position.save" or die $!;
print $save $_[HEAP]{tailor}->tell(), "\n";
close $save;
}
sub handle_startup {
open my $save, "<", "position.save" or die $!;
chomp(my $seek = <$save>);
$_[HEAP]{tailor} = POE::Wheel::FollowTail->new(
...,
Seek => $seek,
);
}
PUBLIC EVENTS¶
POE::Wheel::FollowTail emits a small number of events.
IdleEvent¶
"IdleEvent" specifies the name of an event to be fired when
POE::Wheel::FollowTail doesn't detect activity on the watched file.
$_[ARG0] contains the ID of the POE::Wheel::FollowTail object that fired the
event.
"InputEvent" sets the name of the event to emit when new data arrives
into the tailed file. The event will be accompanied by two parameters:
$_[ARG0] contains the data that was read from the file, after being parsed by
the current "Filter".
$_[ARG1] contains the wheel's ID, which may be used as a key into a data
structure tracking multiple wheels. No assumption should be made about the
nature or format of this ID, as it may change at any time. Therefore, track
your wheels in a hash.
See the "SYNOPSIS" for an example.
ResetEvent¶
"ResetEvent" names the event to be emitted whenever the wheel detects
that the followed file has been reset. It's only available when watching files
by name, as POE::Wheel::FollowTail must reopen the file after it has been
reset.
"ResetEvent" comes with only one parameter, $_[ARG0], which contains
the wheel's ID. See "InputEvent" for some notes about what may be
done with wheel IDs.
See the "SYNOPSIS" for an example.
ErrorEvent¶
"ErrorEvent" names the event emitted when POE::Wheel::FollowTail
encounters a problem. Every "ErrorEvent" comes with four parameters
that describe the error and its situation:
$_[ARG0] describes the operation that failed. This is usually "read",
since POE::Wheel::FollowTail spends most of its time reading from a file.
$_[ARG1] and $_[ARG2] contain the numeric and stringified values of $!,
respectively. They will never contain EAGAIN (or its local equivalent) since
POE::Wheel::FollowTail handles that error itself.
$_[ARG3] contains the wheel's ID, which has been discussed in
"InputEvent".
This error handler logs a message to STDERR and then shuts down the wheel. It
assumes that the session is watching multiple files.
sub handle_tail_error {
my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3];
warn "Wheel $wheel_id: $operation error $errnum: $errstr\n";
delete $_[HEAP]{tailors}{$wheel_id};
}
SEE ALSO¶
POE::Wheel describes the basic operations of all wheels in more depth. You need
to know this.
The SEE ALSO section in POE contains a table of contents covering the entire POE
distribution.
BUGS¶
This wheel can't tail pipes and consoles on some operating systems.
POE::Wheel::FollowTail generally reads ahead of the data it returns, so the
tell() position may be later in the file than the data an application
has already received.
AUTHORS & COPYRIGHTS¶
Please see POE for more information about authors and contributors.