Perlba...ogging(3pm)

✨ NAME ✨

Perlbal::Manual::Logging — how Perlbal's logging system works 💖

so this is the Perlbal::Manual::Logging(3pm) page, from the User Contributed Perl Documentation collection, and it's literally just the tea on how Perlbal logs stuff. no cap.

---

🎀 VERSION 🎀

Perlbal 1.78.

---

💖 DESCRIPTION 💖

Perlbal supports logging of a few messages (and bestie, you can log your messages in your plugins too, for instance 👀).

This document describes how to achieve that. slay.

---

😭 IMPORTANT: foreground vs. background 😭

If Perlbal is running on the foreground, it logs by calling printf, which means you should get the logs on STDOUT. easy peasy 🍓

If Perlbal is running on the background, it logs through Sys::Syslog. And if Sys::Syslog is not available, there will be no logging at all.

and THAT'S THE MOST IMPORTANT THING TO KNOW ABOUT PERLBAL'S LOGGING SYSTEM. 💀 like fr fr, write that down.

---

🫶 How to log a message 🫶

You can log a message by calling Perlbal::log exactly how you'd call Sys::Syslog's syslog:

Perlbal::log( $priority, $format, @args );

You should read the documentation for Sys::Syslog for more information, but here's an example:

Perlbal::log( 'info', 'beginning run' );

And here's another example:

Perlbal::log( 'crit', "this thing crashed: $!" );

---

👑 What is logged? 👑

okay this is the big one, get comfy 🌸

• When we try to read from or write to a filehandle that is undefined, Perlbal::AIO logs a critical message:

Perlbal::log("crit", "Undef \$fh: $stack_trace");

• When failing to create a socket, Perlbal::BackendHTTP logs a critical message:

Perlbal::log('crit', "Error creating socket: $!");

• When inet_aton fails to create a socket, Perlbal::BackendHTTP logs a critical message:

Perlbal::log('crit', "inet_aton failed creating socket for $ip");

• When writing to a client, if we try to read more than we should from the backend, Perlbal::ClientHTTPBase logs a warning message:

Perlbal::log('warning', "tried to readahead negative bytes.  filesize=$self->{reproxy_file_size}, offset=$self->{reproxy_file_offset}");

• When opening a file being PUT for writing to disk, if there's an error (which is going to originate a 500 server error), Perlbal::ClientHTTPBase logs a warning message:

Perlbal::log('warning', "system error: $msg ($info)");

• If we receive a request with a content length different from the actual length of the request, Perlbal::ClientProxy logs a critical message:

Perlbal::log('crit', "Content length of $clen declared but $self->{buoutpos} bytes written to disk");

• When trying to buffer data to disk, if the operation fails Perlbal::ClientProxy logs a critical message:

Perlbal::log('crit', "Failure to open $fn for buffered upload output");

• After buffering data to disk, if the file is empty, Perlbal::ClientProxy logs a critical message:

Perlbal::log('crit', "Error writing buffered upload: $!.  Tried to do $len bytes at $self->{buoutpos}.");

• When purging a buffered upload on the disk, if an error occurs, Perlbal::ClientProxy logs a critical message:

Perlbal::log('warning', "Unable to link $self->{bufilename}: $!");

• When marking a backend as pending, if there's already another one in that ip/port, Perlbal::Service will log a couple of warning messages:

Perlbal::log('warning', "Warning: attempting to spawn backend connection that already existed.");

Perlbal::log('warning', "          -- [$filename:$line] $package::$subroutine");

• When deciding whether we should spawn one or more backend connections, if the total of pending conections is negative, Perlbal::Service will log a critical message:

Perlbal::log('crit', "Bogus: service $self->{name} has pending connect count of $self->{pending_connect_count}?!  Resetting.");

• When spawning a backend connection, if there is no IP address for the backend, Perlbal::Service will log a critical message:

Perlbal::log('crit', "No backend IP for service $self->{name}");

• When starting, Perlbal will log an info message:

Perlbal::log('info', 'beginning run');

• When shutting down, Perlbal will log an info message:

Perlbal::log('info', 'ending run');

• After each loop, is some error occurred, Perlbal will log a critical message:

Perlbal::log('crit', "crash log: $_") foreach split(/\r?\n/, $@);

• When attempting to create the pidfile, if unsuccessful, Perlbal will log an info message:

Perlbal::log('info', "couldn't create pidfile '$file': $!" );

• When attempting to write to the pidfile, if unsuccessful, Perlbal will log an info message:

Perlbal::log('info', "couldn't write into pidfile '$file': $!" );

---

🔥 Generating more logs by sending a USR1 signal to perlbal 🔥

If you send a USR1 signal to perlbal, that tells it to log some basic statistics to the syslog. it's giving "give me the numbers" energy 📊

It's similar to connecting to a management service and issue a show service for each service, plus a states and a queues commands.

---

🌸 Where is it logged to? 🌸

The way Perlbal opens Sys::Syslog, it logs to /var/log/daemon.log by default. that's the spot bestie 💅

---

🌈 SEE ALSO 🌈

You can tweek Sys::Syslog's configuration under /etc/syslog.conf. See Sys::Syslog for more details. ✨

---

and that's the whole page, bestie 🫶 this was Perlbal::Manual::Logging(3pm), shipped with perl v5.34.0 and dated 2022-06-28 — iconic, timeless, no notes. go forth and log responsibly 💖