Introduction

IzPack installers use Java Logging for logging any information. If you want to customize it you should be familar with it, otherwise there is a good description of its principles in Oracle's Java Logging Overview.

Without any explicit specification on the command line or in the install.xml itself, an installer logs to the console at the given log level. For this purpose it associates a default Java ConsoleHandler combined with a built-in formatter not being that messy like the JRE's SimpleFormatter. The log level to limit the output to depends on whether you set IzPack to debug mode by adding the command line option -debug (or the -DDEBUG=true JVM option for IzPack versions < 5.0.11). If the installer runs in debug mode the Java Logging level for the root logger is set to FINE by default globally, by default it is INFO otherwise.

The IzPack logging settings affect also custom implementations and built-in listeners, since IzPack reconfigures the Java root logger. The output of Ant builds in AntActionInstallerListener is also caught to the log If overridden in an <antaction> to log to a file dedicated to the specific action, this override happens now additionally to the default IzPack logging approach. So there may appear the same output of Ant builds in two files, just with differences in formatting.

On the console, there are just shown the plain log messages, without any prefixes per line (like timestamp or message level). An exception are the message levels WARNING and SEVERE, which are always prepended to better inform the user in the terminal in case of irregularities.

IzPack has been enhanced by the possibility of logging to files natively, either triggered from the command line or by a special section in install.xml.

Beyond the built-in logging mechanisms for console and file output there can be override the Java Logging configuration, handlers, formatters and their configuration at each desired Java package hierarchy you may add to an external configuration file, which can be given by the JVM command line option -Djava.util.logging.config.file=<path>. Furthermore, there might be used am own custom implementation given as parameter -Djava.util.logging.config.class=<classname>, which initializes the installer logging in its default constructor (be sure to see it in the classpath). If one of those standard system properties is set all other built-in approaches of IzPack are skipped to match the official API. See the LogManager API Specification for more information.

Here is what an example installer logs to the console when without custom logging:

> /usr/java/jdk1.8.0_112/jre/bin/java -jar installer.jar -trace -stacktrace
Command line arguments: -trace -stacktrace  
Detected platform: suse_linux,version=4.9.8-1-default,arch=x64,symbolicName=null,javaVersion=1.8.0_121
...

If you wish to add debug information to the log of the IzPack installer implementation you can add the -DDEBUG=true JVM option, which will result in a very messy output with information for installer developers to analyze issues.

> /usr/java/jdk1.8.0_112/jre/bin/java -DDEBUG=true -jar installer.jar
Command line arguments: -trace -stacktrace  
Detected platform: suse_linux,version=4.9.8-1-default,arch=x64,symbolicName=null,javaVersion=1.8.0_121
Dynamic variable 'APP_NAME' set to 'My Great Application'
...

Setting up logging

Logging of an IzPack installers can be done at three different levels, the latter approach overrides the previous one each time:

• defining a <logging> section in install.xml,
• defining a log file by adding -logfile <path> to the command line (optionally enhanced by -debug, -trace or -stacktrace),
• configuring own handlers and/or formatters by making usage of the full Java Logging API.

Compile-time log configuration in the installer

IzPack 5.0.11 introduces several options to configure file logging in the installation descriptor (install.xml).

These settings are activated right before the InstallPanel triggers the first pre-installation action in queue. Therefore there can be used unresolved IzPack variables, in the log file paths as well as in all configuration options for handlers and formatters. A path to a log file is normalized at file name level before applying, which means there can be used .. file name parts, for example: ${INSTALL_PATH}/../install_logs, which can be immediately used to create a log file in an existing directory beside of  the target installation directory of the application ${INSTALL_PATH} even if ${INSTALL_PATH} still hasn't been created, which is the case in all beforePack installer listener actions (before unpacking).

The configuration below does not apply for log entries triggered by input panels activated before InstallPanel appears.

One of them is to redirect all the output of the Java root logger including the Ant builds triggered by AntActionInstallerListener to one single log file:

<logging>
  <log-file pattern="${logging.file}" append="true" ... />
</logging>

The above definition supports all configuration options of java.util.logging.FileHandler as attributes. This means you may maintain a limited number of log files with a maximum size each (rolling log files).

Alternatively, to savor the full flavour of Java Logging there can be passed a configuration properties file. This allows the user to define his/her own set of handlers and formatters on different Java package levels. For example there might be used different log files for IZPack and for a business implementation plugging in to IzPack.

<logging>
  <configuration-file>${logging.config.file}</configuration-file>
</logging>

There can be used just one of the above options in one installer definition, either <log-file> or <configuration-file>. The compiler will not allow to mix them.

Explicitly logging to a file at runtime

Passing full Java Logging parameters at runtime

The example here is very simple, just for the purpose to show how the installer handles logging customization.

To activate the contents of a configuration file add its path to the command line as value of the system property java.util.logging.config.file JVM parameter, for example like this:

-Djava.util.logging.config.file=/home/rkrell/logging.properties

IzPack uses the following built-in configuration;

# Global logging properties.
# ------------------------------------------
# The set of handlers to be loaded upon startup.
# Comma-separated list of class names.
com.izforge.izpack.util.handlers = com.izforge.izpack.util.LogHandler

com.izforge.izpack.util.LogHandler.formatter = com.izforge.izpack.util.LogFormatter

# The IzPack LogHandler implementation overrides the log level automatically depending on whether we are in debug mode (JVM option -DDEBUG=true)

If you want to use the default JVM console log handler and formatter instead of the IzPack built-in facilities you might use this configuration file:

# Global logging properties.
# ------------------------------------------
# The set of handlers to be loaded upon startup.
# Comma-separated list of class names.
# (? LogManager docs say no comma here, but JDK example has comma.)
handlers = java.util.logging.ConsoleHandler

# Default global logging level.
# Loggers and Handlers may override this level
.level = FINE

# The Java ConsoleHandler implementation has its own logging level setting
java.util.logging.ConsoleHandler.level = FINE

You might for example mix both configuration above:

# Global logging properties.
# ------------------------------------------
# The set of handlers to be loaded upon startup.
# Comma-separated list of class names.
# (? LogManager docs say no comma here, but JDK example has comma.)
handlers = java.util.logging.ConsoleHandler

java.util.logging.ConsoleHandler.formatter = com.izforge.izpack.util.LogFormatter

# Default global logging level.
.level=FINE

You can also log to files, sockets and other resources, see the appropriate handler implementation and their dedicated configuration for more details.

There might be used own custom handlers for writing the log to a database or to a log collector web service, no limits here.