Logging
- René Krell
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
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:
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.
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:
<logging>
<log-file pattern="${logging.file}" append="true" ... />
</logging>
The <logging> element accepts the following attributes:
| Attribute name | Description | Allowed values | Default |
|---|---|---|---|
level | Specifies the global logging level for console logging. The value |
| INFO |
The above definition of a <log-file> supports all configuration options of java.util.logging.FileHandler as attributes, in particular:
| Attribute name | Description | Allowed values | Default |
|---|---|---|---|
| Pattern for generating the output file name. 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. This level overrides the global level defined above. Example: If the global logging level is set to |
| INFO |
filter | Specifies the name of a Filter class to use (defaults to no Filter). | Fully qualified Java class name. | (no filter) |
encoding | The name of the character set encoding to use. | Valid Java character set name. Example: like UTF-8 | (platform encoding) |
limit | Specifies 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) |
count | Specifies 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 >= 1 | 1 |
append | Specifies whether the FileHandler should append onto any existing files. | true | false | false |
mkdirs | Specifies whether the installer should recursively create the parent directory of the log file speciified by the 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 | false | false |
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
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.
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:
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.