POE::Wheel::FollowTail(3pm)

1POE::Wheel::FollowTail(U3s)er Contributed Perl DocumentatPiOoEn::Wheel::FollowTail(3)
2
3
4

NAME

6       POE::Wheel::FollowTail - follow the tail of an ever-growing file
7

SYNOPSIS

9         #!perl
10
11         use POE qw(Wheel::FollowTail);
12
13         POE::Session->create(
14           inline_states => {
15             _start => sub {
16               $_[HEAP]{tailor} = POE::Wheel::FollowTail->new(
17                 Filename => "/var/log/system.log",
18                 InputEvent => "got_log_line",
19                 ResetEvent => "got_log_rollover",
20               );
21             },
22             got_log_line => sub {
23               print "Log: $_[ARG0]\n";
24             },
25             got_log_rollover => sub {
26               print "Log rolled over.\n";
27             },
28           }
29         );
30
31         POE::Kernel->run();
32         exit;
33

DESCRIPTION

35       POE::Wheel::FollowTail objects watch for new data at the end of a file
36       and generate new events when things happen to the file. Its "Filter"
37       parameter defines how to parse data from the file. Each new item is
38       sent to the creator's session as an "InputEvent" event. Log rotation
39       will trigger a "ResetEvent".
40
41       POE::Wheel::FollowTail only reads from a file, so it doesn't implement
42       a put() method.
43

PUBLIC METHODS

45   new
46       new() returns a new POE::Wheel::FollowTail object.  As long as this
47       object exists, it will generate events when the corresponding file's
48       status changes.
49
50       new() accepts a small set of named parameters:
51
52       Driver
53
54       The optional "Driver" parameter specifies which driver to use when
55       reading from the tailed file.  If omitted, POE::Wheel::FollowTail will
56       use POE::Driver::SysRW.  This is almost always the right thing to do.
57
58       Filter
59
60       "Filter" is an optional constructor parameter that specifies how to
61       parse data from the followed file.  By default, POE::Wheel::FollowTail
62       will use POE::Filter::Line to parse files as plain, newline-separated
63       text.
64
65         $_[HEAP]{tailor} = POE::Wheel::FollowTail->new(
66           Filename => "/var/log/snort/alert",
67           Filter => POE::Filter::Snort->new(),
68           InputEvent => "got_snort_alert",
69         );
70
71       PollInterval
72
73       POE::Wheel::FollowTail needs to periodically check for new data on the
74       followed file.  "PollInterval" specifies the number of seconds to wait
75       between checks.  Applications that need to poll once per second may
76       omit "PollInterval", as it defaults to 1.
77
78       Longer poll intervals may be used to reduce the polling overhead for
79       infrequently updated files.
80
81         $_[HEAP]{tailor} = POE::Wheel::FollowTail->new(
82           ...,
83           PollInterval => 10,
84         );
85
86       Seek
87
88       If specified, "Seek" instructs POE::Wheel::FollowTail to seek to a
89       specific spot in the tailed file before beginning to read from it.  A
90       positive "Seek" value is interpreted as the number of octets to seek
91       from the start of the file.  Negative "Seek" will, like negative array
92       indices, seek backwards from the end of the file.  Zero "Seek" starts
93       reading from the beginning of the file.
94
95       Be careful when using "Seek", as it's quite easy to seek into the
96       middle of a record.  When in doubt, and when beginning at the end of
97       the file, omit "Seek" entirely.  POE::Wheel::FollowTail will seek 4
98       kilobytes back from the end of the file, then parse and discard all
99       records unto EOF.  As long as the file's records are smaller than 4
100       kilobytes, this will guarantee that the first record returned will be
101       complete.
102
103       "Seek" may also be used with the wheel's tell() method to restore the
104       file position after a program restart.  Save the tell() value prior to
105       exiting, and load and "Seek" back to it on subsequent start-up.
106
107       TODO - Example.
108
109       SeekBack
110
111       "SeekBack" behaves like the inverse of "Seek".  A positive value acts
112       like a negative "Seek".  A negative value acts like a positive "Seek".
113       A zero "SeekBack" instructs POE::Wheel::FollowTail to begin at the very
114       end of the file.
115
116       "Seek" and "SeekBack" are mutually exclusive.
117
118       See "Seek" for caveats, techniques, and an explanation of the magic
119       that happens when neither "Seek" nor "SeekBack" is specified.
120
121       TODO - Example.
122
123       Handle
124
125       POE::Wheel::FollowTail may follow a previously opened file "Handle".
126       Unfortunately it cannot follow log resets this way, as it won't be able
127       to reopen the file once it has been reset.  Applications that must
128       follow resets should use "Filename" instead.
129
130       "Handle" is still useful for files that will never be reset, or for
131       devices that require setup outside of POE::Wheel::FollowTail's purview.
132
133       "Handle" and "Filename" are mutually exclusive.  One of them is
134       required, however.
135
136       TODO - Example.
137
138       Filename
139
140       Specify the "Filename" to watch.  POE::Wheel::FollowTail will wait for
141       the file to appear if it doesn't exist.  The wheel will also reopen the
142       file if it disappears, such as when it has been reset or rolled over.
143       In the case of a reset, POE::Wheel::FollowTail will also emit a
144       "ResetEvent", if one has been requested.
145
146       "Handle" and "Filename" are mutually exclusive.  One of them is
147       required, however.
148
149       See the "SYNOPSIS" for an example.
150
151       InputEvent
152
153       The "InputEvent" parameter is required, and it specifies the event to
154       emit when new data arrives in the watched file.  "InputEvent" is
155       described in detail in "PUBLIC EVENTS".
156
157       ResetEvent
158
159       "ResetEvent" is an optional.  It specifies the name of the event that
160       indicates file rollover or reset.  Please see "PUBLIC EVENTS" for more
161       details.
162
163       ErrorEvent
164
165       POE::Wheel::FollowTail may emit optional "ErrorEvent"s whenever it runs
166       into trouble.  The data that comes with this event is explained in
167       "PUBLIC EVENTS".
168
169   event
170       event() allows a session to change the events emitted by a wheel
171       without destroying and re-creating the object.  It accepts one or more
172       of the events listed in "PUBLIC EVENTS".  Undefined event names disable
173       those events.
174
175       Stop handling log resets:
176
177         sub some_event_handler {
178           $_[HEAP]{tailor}->event( ResetEvent => undef );
179         }
180
181       The events are described in more detail in "PUBLIC EVENTS".
182
183   ID
184       The ID() method returns the wheel's unique ID.  It's useful for storing
185       the wheel in a hash.  All POE::Wheel events should be accompanied by a
186       wheel ID, which allows the wheel to be referenced in their event
187       handlers.
188
189         sub setup_tailor {
190           my $wheel = POE::Wheel::FollowTail->new(... incomplete ...);
191           $_[HEAP]{tailors}{$wheel->ID} = $wheel;
192         }
193
194       See the example in "ErrorEvent" for a handler that will find this wheel
195       again.
196
197   tell
198       tell() returns the current position for the file being watched by
199       POE::Wheel::FollowTail.  It may be useful for saving the position
200       program termination.  new()'s "Seek" parameter may be used to resume
201       watching the file where tell() left off.
202
203         sub handle_shutdown {
204           # Not robust.  Do better in production.
205           open my $save, ">", "position.save" or die $!;
206           print $save $_[HEAP]{tailor}->tell(), "\n";
207           close $save;
208         }
209
210         sub handle_startup {
211           open my $save, "<", "position.save" or die $!;
212           chomp(my $seek = <$save>);
213           $_[HEAP]{tailor} = POE::Wheel::FollowTail->new(
214             ...,
215             Seek => $seek,
216           );
217         }
218

PUBLIC EVENTS

220       POE::Wheel::FollowTail emits a small number of events.
221
222   InputEvent
223       "InputEvent" sets the name of the event to emit when new data arrives
224       into the tailed file.  The event will be accompanied by two parameters:
225
226       $_[ARG0] contains the data that was read from the file, after being
227       parsed by the current "Filter".
228
229       $_[ARG1] contains the wheel's ID, which may be used as a key into a
230       data structure tracking multiple wheels.  No assumption should be made
231       about the nature or format of this ID, as it may change at any time.
232       Therefore, track your wheels in a hash.
233
234       See the "SYNOPSIS" for an example.
235
236   ResetEvent
237       "ResetEvent" names the event to be emitted whenever the wheel detects
238       that the followed file has been reset.  It's only available when
239       watching files by name, as POE::Wheel::FollowTail must reopen the file
240       after it has been reset.
241
242       "ResetEvent" comes with only one parameter, $_[ARG0], which contains
243       the wheel's ID.  See "InputEvent" for some notes about what may be done
244       with wheel IDs.
245
246       See the "SYNOPSIS" for an example.
247
248   ErrorEvent
249       "ErrorEvent" names the event emitted when POE::Wheel::FollowTail
250       encounters a problem.  Every "ErrorEvent" comes with four parameters
251       that describe the error and its situation:
252
253       $_[ARG0] describes the operation that failed.  This is usually "read",
254       since POE::Wheel::FollowTail spends most of its time reading from a
255       file.
256
257       $_[ARG1] and $_[ARG2] contain the numeric and stringified values of $!,
258       respectively.  They will never contain EAGAIN (or its local equivalent)
259       since POE::Wheel::FollowTail handles that error itself.
260
261       $_[ARG3] contains the wheel's ID, which has been discussed in
262       "InputEvent".
263
264       This error handler logs a message to STDERR and then shuts down the
265       wheel.  It assumes that the session is watching multiple files.
266
267         sub handle_tail_error {
268           my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3];
269           warn "Wheel $wheel_id: $operation error $errnum: $errstr\n";
270           delete $_[HEAP]{tailors}{$wheel_id};
271         }
272

BUGS

281       This wheel can't tail pipes and consoles on some operating systems.
282
283       POE::Wheel::FollowTail generally reads ahead of the data it returns, so
284       the tell() position may be later in the file than the data an
285       application has already received.
286

AUTHORS & COPYRIGHTS

288       Please see POE for more information about authors and contributors.
289
290
291
292perl v5.12.1                      2010-04-03         POE::Wheel::FollowTail(3)