Logging

The following information is valid for IzPack versions >= 5.1.0, where the logging behavior has been consolidated.

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.1.0). 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 by default for its purposes (unless the java.util.logging.config.file or java.util.logging.config.class JVM properties are set, see below).

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 passed as JVM command line option (standard approach of the LogManager API) or at compile time in the installer descriptor.

Here is what an example installer logs by default 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  
====================
Installation started
Framework: 5.0.11-SNAPSHOT-4f718 (IzPack)
Platform: suse_linux,version=4.9.9-1-default,arch=x64,symbolicName=null,javaVersion=1.8.0_121
Installation finished

If you wish to add debug information to the log of the IzPack installer implementation you can add the -debug command line 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  
====================
Installation started
Framework: 5.0.11-SNAPSHOT-4f718 (IzPack)
Platform: suse_linux,version=4.9.9-1-default,arch=x64,symbolicName=null,javaVersion=1.8.0_121
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'
...
Installation finished

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

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

The <logging> element accepts the following attributes:

Attribute nameDescriptionAllowed valuesDefault
level

Specifies the global logging level for console logging.
In general there are logged just messages with the same or higher priority than the level specified.
The level SEVERE has the highest priority, FINEST the lowest one.

The value OFF mutes the output to the console.

OFF | SEVERE | WARNING | INFO | CONFIG | FINE | FINER | FINEST | ALL

INFO


The above definition of a <log-file> supports all configuration options of java.util.logging.FileHandler as attributes, in particular:

Attribute nameDescriptionAllowed valuesDefault

pattern

Pattern for generating the output file name.
See the FileHandler API for details on how a pattern can be designed.
IzPack variables are resolved.
The parent directory of the log file must exist, otherwise the installer will fail.
The log file will be created automatically if it doesn't exist at the time the first log entry should be written.

According to the FileHandler API the percent '%' sign is used as an escape character for different special components that will be replaced at runtime. If you want to user a percent sign as static part of the path name use a double percent sign ("%%") to get it to that place in the name.

Valid path to log file name.
The file name is normalized as much as possible. 
%h/java%u.log
level

Specifies the logging level.
In general there are logged just messages with the same or higher priority than the level specified.
The level SEVERE has the highest priority, FINEST the lowest one. 

This level overrides the global level defined above.

Example: If the global logging level is set to OFF and the file logging level to INFO, the installer logs just to the file.

OFF | SEVERE | WARNING | INFO | CONFIG | FINE | FINER | FINEST | ALL

INFO
filterSpecifies the name of a Filter class to use (defaults to no Filter).Fully qualified Java class name.(no filter)
encodingThe name of the character set encoding to use.Valid Java character set name.
Example: like UTF-8
(platform encoding)
limitSpecifies an approximate maximum amount to write (in bytes) to any one file.
If this is zero, then there is no limit.
Integer value >= 0(no limit)
countSpecifies how many output files to cycle through.
This allows you to maintain a limited number of log file archives with a maximum size specified by the limit attribute (rolling log files). 
Integer value >= 11
appendSpecifies whether the FileHandler should append onto any existing files.true | falsefalse
mkdirs

Specifies whether the installer should recursively create the parent directory of the log file speciified by the pattern attribute.

This attribute is not part of the FileHandler API and is hidden to the FileHandler configuration. IzPack handles it before the according FileHandler-based Java Logger gets activated.

true | falsefalse

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.

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

The installer can easily log immediately to a file without any compile-time configuration by simply adding the installer command line option -logfile <log_file_path>.

This will redirect the complete logging output to the specified file.

This approach logs immediately when the installer starts and overrides all the above approach of compile time configuration.

The parent directory of the log file must exist, otherwise the installer will fail.
The log file will be created automatically if it doesn't exist at the time the first log entry should be written.

Example log file contents
2017.02.16 15:07:22 INFO: Command line arguments: -logfile x.log  
2017.02.16 15:07:27 INFO: ====================
2017.02.16 15:07:27 INFO: Installation started
2017.02.16 15:07:27 INFO: Framework: 5.0.11-SNAPSHOT-4f718 (IzPack)
2017.02.16 15:07:27 INFO: Platform: suse_linux,version=4.9.9-1-default,arch=x64,symbolicName=null,javaVersion=1.8.0_121
2017.02.16 15:07:27 INFO: Installation finished

Passing full Java Logging parameters at runtime

The next alternative, is passing a logging configuration file as system property to the JVM calling the installer.

This approach logs immediately when the installer starts and overrides all the above approaches.

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, for example by using the following command line parameter:

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

The following example simulates IzPack's default logging behavior:

Example: Simulating IzPack built-in logging
# Global logging properties.
# ------------------------------------------

# The set of handlers to be loaded upon startup.
# Comma-separated list of class names.
handlers = java.util.logging.ConsoleHandler

# The IzPack ConsoleFormatter implementation overrides the log level automatically depending on whether we are in debug mode (command line option -debug)
java.util.logging.ConsoleHandler.formatter = com.izforge.izpack.logging.ConsoleFormatter

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.

Alternatively to java.util.logging.config.file there can be also passed the system property java.util.logging.config.class, for example by using the following command line parameter:

-Djava.util.logging.config.class=com.my.company.LogConfiguration

For general information about how to use these two JVM system properties see the LogManager API specification.