Portage log

When using emerge for building a package, it is not uncommon to notice messages coming from Portage itself. Since they may contain important information from Gentoo developers it is a good idea to read them, but often this is not immediately possible because they rapidly scroll out of the screen. This can be easily solved by enabling a Portage feature called elog, whose purpose is to save messages to disk for later review. But other logging capabilities exist as well...

Portage elog subsystem

The Portage elog subsystem keeps track of specific, ebuild-provided log messages that developers have put in the ebuilds to attract attention of the administrator or user. Often, these messages contain important or interesting information related to the build of said package.

Setup

Select which kind of information should be logged through the PORTAGE_ELOG_CLASSES variable. Possible values are info, warn, error, log and qa:

FILE /etc/portage/make.conf

PORTAGE_ELOG_CLASSES="log warn error"

Configuring for file-based storage

Portage can handle the elog events in a number of ways.

In order to save the elog events to disk, enable the save module in the PORTAGE_ELOG_SYSTEM variable:

FILE /etc/portage/make.conf

PORTAGE_ELOG_SYSTEM="save"

The messages will be saved in /var/log/portage/elog or in ${PORTAGE_LOGDIR}/elog if said variable is set.

In order to create per-category elog files, enable the split-elog Portage feature. It will force Portage to create category-based subdirectories of the /var/log/portage/elog location.

Configuring for e-mail

To mail logs to a recipient, enable the mail module. The mail option requires some additional variables to be set. Read /usr/share/portage/config/make.conf.example for more information.

Below, an example setup is shown which is hopefully self-explanatory:

FILE /etc/portage/make.conf

PORTAGE_ELOG_SYSTEM="mail"
# First the mail-to address, then the SMTP server
PORTAGE_ELOG_MAILURI="log-intake@example.com mail.example.com"
PORTAGE_ELOG_MAILFROM="portage@$(hostname).example.com"
PORTAGE_ELOG_MAILSUBJECT="${PACKAGE} is ${ACTION} on ${HOST}"

Another example with nullmailer or sendmail:

FILE /etc/portage/make.conf

PORTAGE_ELOG_SYSTEM="mail"
# First the mail-to address, then the SMTP server
PORTAGE_ELOG_MAILURI="users@host /usr/sbin/sendmail"
PORTAGE_ELOG_MAILFROM="portage@$(hostname).example.com"
PORTAGE_ELOG_MAILSUBJECT="${PACKAGE} is ${ACTION} on ${HOST}"

Related software

The following is a list of elog-related software packages:

• app-portage/elogv - Curses based utility to parse the contents of elogs
• app-portage/elogviewer - Python based elog viewer

Build logs

Package build logs can be saved to disk or mailed to a remote recipient. This allows administrators to review builds later.

Setup

To enable saving build logs, edit /etc/portage/make.conf and set PORTAGE_LOGDIR to a location where the log files should be stored. By default, when emerge is running, Portage saves the build log of a package to ${PORTAGE_TMPDIR}/portage/${CATEGORY}/${PF}/temp/build.log (possibly followed by an extension if compress-build-logs is in FEATURES), where PORTAGE_TMPDIR is /var/tmp unless set to something different in make.conf, and ${CATEGORY} and ${PF} represent the package's category and name (with version and revision), respectively. Directory ${PORTAGE_TMPDIR}/portage/${CATEGORY}/${PF} will be deleted after emerge finishes successfully, and the contained build log lost, but kept if it doesn't, so the log will still be available for attaching to support tickets:

FILE /etc/portage/make.conf

PORTAGE_LOGDIR="/var/log/portage"

It is customary to choose /var/log/portage as the location for log files, because it is where the elog subsystem's elog directory would be if PORTAGE_LOGDIR has been previously empty or unset.

Next, you may want to edit and/or set a number of FEATURES= settings in /etc/portage/make.conf which influence how Portage handles build logs.

• With binpkg-logs set, even binary package deployments will have their logs saved
• When clean-logs is set, regular log file clean operations are executed. The command that is executed is defined by PORTAGE_LOGDIR_CLEAN and defaults to a retention of the files of 7 days.
• With split-log set, build logs are stored in category-named subdirectories of ${PORTAGE_LOGDIR}/build

Note
Until Portage version 2.3.53, PORTAGE_LOGDIR used to be named PORT_LOGDIR. This old name is now deprecated.

Cleaning up

When clean-logs is set, Portage will execute the command defined by PORTAGE_LOGDIR_CLEAN after every build or unmerge operation. By default, the following command is used:

FILE /usr/share/portage/config/make.globals

PORTAGE_LOGDIR_CLEAN="find \"\${PORTAGE_LOGDIR}\" -type f ! -name \"summary.log*\" -mtime +7 -delete"

When defining a custom command, do not forget to escape the PORTAGE_LOGDIR variable (or immediately hardcode the right location).

Note
Until Portage version 2.3.53, PORTAGE_LOGDIR_CLEAN used to be named PORT_LOGDIR_CLEAN. This old name is now deprecated.

External resources

• Sven Vermeulen. "Underestimated or underused: Portage (e)logging ", September 25th, 2013. Retrieved on May 30th, 2019.