---
name: "Perlbal::Manual::Logging"
section: "3pm"
platform: "linux"
package: "libperlbal-perl"
version: "1.80-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Perlbal::Manual::Logging"
---

# Perlbal::Manual::Logging(3pm)

How Perlbal's logging system works

## NAME

Perlbal::Manual::Logging - How Perlbal's logging system works

### VERSION

Perlbal 1.78.

### DESCRIPTION

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

This document describes how to achieve that.

### 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"`.

If Perlbal is running on the background, it logs through Sys::Syslog. If Sys::Syslog is not available, there will be no logging, and THAT'S THE MOST IMPORTANT THING TO KNOW ABOUT PERLBAL'S LOGGING SYSTEM.

### How to log a message

You can log a message by calling `"Perlbal::log"` as 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?

- •

  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 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.

### SEE ALSO

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