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       SeekBack
108
109       "SeekBack" behaves like the inverse of "Seek".  A positive value acts
110       like a negative "Seek".  A negative value acts like a positive "Seek".
111       A zero "SeekBack" instructs POE::Wheel::FollowTail to begin at the very
112       end of the file.
113
114       "Seek" and "SeekBack" are mutually exclusive.
115
116       See "Seek" for caveats, techniques, and an explanation of the magic
117       that happens when neither "Seek" nor "SeekBack" is specified.
118
119       Handle
120
121       POE::Wheel::FollowTail may follow a previously opened file "Handle".
122       Unfortunately it cannot follow log resets this way, as it won't be able
123       to reopen the file once it has been reset.  Applications that must
124       follow resets should use "Filename" instead.
125
126       "Handle" is still useful for files that will never be reset, or for
127       devices that require setup outside of POE::Wheel::FollowTail's purview.
128
129       "Handle" and "Filename" are mutually exclusive.  One of them is
130       required, however.
131
132       Filename
133
134       Specify the "Filename" to watch.  POE::Wheel::FollowTail will wait for
135       the file to appear if it doesn't exist.  The wheel will also reopen the
136       file if it disappears, such as when it has been reset or rolled over.
137       In the case of a reset, POE::Wheel::FollowTail will also emit a
138       "ResetEvent", if one has been requested.
139
140       "Handle" and "Filename" are mutually exclusive.  One of them is
141       required, however.
142
143       See the "SYNOPSIS" for an example.
144
145       IdleEvent
146
147       "IdleEvent" is an optional event.  If specified, it will fire whenever
148       POE::Wheel::FollowTail checks for activity but sees nothing.  It was
149       added in POE 1.362 as a way to advance certain test programs without
150       needing to wait conservatively large amounts of time.
151
152       "IdleEvent" is described in "PUBLIC EVENTS".
153
154       InputEvent
155
156       The "InputEvent" parameter is required, and it specifies the event to
157       emit when new data arrives in the watched file.  "InputEvent" is
158       described in detail in "PUBLIC EVENTS".
159
160       ResetEvent
161
162       "ResetEvent" is an optional.  It specifies the name of the event that
163       indicates file rollover or reset.  Please see "PUBLIC EVENTS" for more
164       details.
165
166       ErrorEvent
167
168       POE::Wheel::FollowTail may emit optional "ErrorEvent"s whenever it runs
169       into trouble.  The data that comes with this event is explained in
170       "PUBLIC EVENTS".
171
172   event
173       event() allows a session to change the events emitted by a wheel
174       without destroying and re-creating the object.  It accepts one or more
175       of the events listed in "PUBLIC EVENTS".  Undefined event names disable
176       those events.
177
178       Stop handling log resets:
179
180         sub some_event_handler {
181           $_[HEAP]{tailor}->event( ResetEvent => undef );
182         }
183
184       The events are described in more detail in "PUBLIC EVENTS".
185
186   ID
187       The ID() method returns the wheel's unique ID.  It's useful for storing
188       the wheel in a hash.  All POE::Wheel events should be accompanied by a
189       wheel ID, which allows the wheel to be referenced in their event
190       handlers.
191
192         sub setup_tailor {
193           my $wheel = POE::Wheel::FollowTail->new(... incomplete ...);
194           $_[HEAP]{tailors}{$wheel->ID} = $wheel;
195         }
196
197       See the example in "ErrorEvent" for a handler that will find this wheel
198       again.
199
200   tell
201       tell() returns the current position for the file being watched by
202       POE::Wheel::FollowTail.  It may be useful for saving the position
203       program termination.  new()'s "Seek" parameter may be used to resume
204       watching the file where tell() left off.
205
206         sub handle_shutdown {
207           # Not robust.  Do better in production.
208           open my $save, ">", "position.save" or die $!;
209           print $save $_[HEAP]{tailor}->tell(), "\n";
210           close $save;
211         }
212
213         sub handle_startup {
214           open my $save, "<", "position.save" or die $!;
215           chomp(my $seek = <$save>);
216           $_[HEAP]{tailor} = POE::Wheel::FollowTail->new(
217             ...,
218             Seek => $seek,
219           );
220         }
221

PUBLIC EVENTS

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

BUGS

291       This wheel can't tail pipes and consoles on some operating systems.
292
293       POE::Wheel::FollowTail generally reads ahead of the data it returns, so
294       the tell() position may be later in the file than the data an
295       application has already received.
296

AUTHORS & COPYRIGHTS

298       Please see POE for more information about authors and contributors.
299
300
301
302perl v5.36.0                      2023-01-20         POE::Wheel::FollowTail(3)