POE::W...owTail(3pm)

💖 POE::Wheel::FollowTail 💖

okay bestie, so this is the manual page for POE::Wheel::FollowTail, straight out of the User Contributed Perl Documentation section, and it's literally about following the tail of an ever-growing file. like tail -f but make it ✨event-driven✨. let's go 🦋

---

🌸 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;

no cap, that's the whole vibe right there 💅

---

🫶 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 gets sent to the creator's session as an InputEvent event. log rotation will trigger a ResetEvent. it's giving very attentive bestie energy honestly 👑

one thing to know: POE::Wheel::FollowTail only reads from a file, so it doesn't implement a put() method. it's a read-only queen, periodt. 📖

---

🌈 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. iconic behavior fr fr.

new() accepts a small set of named parameters:

• Driver — this optional parameter says which driver to use when reading from the tailed file. if you omit it, POE::Wheel::FollowTail will use POE::Driver::SysRW. and ngl, that's almost always the right thing to do. don't overthink it bestie 🎀
• Filter — 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. and if you wanna swap it up:

$_[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, and PollInterval specifies the number of seconds to wait between checks. applications that need to poll once per second may omit PollInterval, because it defaults to 1. longer poll intervals may be used to reduce the polling overhead for infrequently updated files. lowkey a whole optimization moment 🌿

$_[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, because 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. that's the magic trick, iykyk 🪄

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. chef's kiss 🧑🍳💋

• 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. it's right up there bestie ⬆️

• IdleEvent — 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 — this 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 — 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 ErrorEvents 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, just like that:

sub some_event_handler {
  $_[HEAP]{tailor}->event( ResetEvent => undef );
}

the events are described in more detail in PUBLIC EVENTS. 💜

👑 ID 👑

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. main character identification moment ✨

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,
  );
}

🙈 that comment in there saying # Not robust. Do better in production. is literally in the original, so yeah, do better in production bestie.

---

💅 PUBLIC EVENTS 💅

POE::Wheel::FollowTail emits a small number of events. small but mighty 🫶

🌙 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 💖

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. fr fr, put them 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. like, actually. go read it. 📚

the SEE ALSO section in POE contains a table of contents covering the entire POE distribution. whole menu of options, slay 🍽️

---

🐛 BUGS 🐛

this wheel can't tail pipes and consoles on some operating systems. sad but true 😭

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. just so you know, so you're not surprised 👀

---

📜 AUTHORS & COPYRIGHTS 📜

please see POE for more information about authors and contributors. 💜

---

and that's the whole page bestie, no notes, you ate 💅✨

perl v5.34.0 · 2022-03-25 · mwah, go tail some logs 🦋💖