Logging API

From PhexWiki

Phex uses the LOGBack library for logging. (Since Phex 3.2.8 build 107)

Logging Configuration

To change the default configuration and adjust Phex logging to your needs, you need to create a file called logback-test.xml which must be placed in the Phex classpath. This can for example be the directory ext/ inside your Phex home directory or the Phex source directory.

The configuration file can contain LOGBack configuration according to the LOGBack documentation.

Phex provides a default configuration set of appenders which can be integrated into a custom configuration for easier setup. It will provide three logging appenders:

• ConsoleAppender: Outputs all message on the command line console, if Phex is started from console.
• DefaultFileAppender: Writes all log messages into the file 'phex.log' in the Phex configuration directory.
• ErrorFileAppender: Writes all error messages into the file 'phex.error.log' in the Phex configuration directory.

To use the provided default configuration add this directive:

<configuration>
  ...
  <!-- include Phex default appenders -->
  <include resource="logback.inc.xml"/>
  ...
</configuration>

All that is left to do is to configure the root logger and the custom logger configuration. Since the Phex logs a very high volume it is highly recommended to only log on the ERROR or maybe WARN level on the root logger.

This is a recommended example configuration for the root logger:

<configuration>
  ...
  <!-- root logger configuration -->
  <root>
    <!-- only log ERROR level -->
    <level value="ERROR" />

    <!-- write all output to phex.log -->
    <appender-ref ref="DefaultFileAppender" />

    <!-- write all ERROR output to phex.log -->
    <appender-ref ref="ErrorFileAppender" />

    <!-- write all output to shell console -->
    <appender-ref ref="ConsoleAppender" />
  </root>
  ...
</configuration>

Now add your custom logger at package or class level. Here is a possible example configuration:

<configuration>
  ...
  <!-- configure logger for the class HttpFileDownload -->
  <logger name="phex.download.handler.HttpFileDownload" additivity="false">
    <level value="DEBUG" />
  </logger>

  <!-- configure logger for the whole package phex.gwebcache -->
  <logger name="phex.gwebcache" additivity="false">
    <level value="DEBUG" />
  </logger>
  ...
</configuration>

A complete custom log configuration file could look like this:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>

  <!-- include Phex default appenders -->
  <include resource="logback.inc.xml"/>

  <!-- root logger configuration -->
  <root>
    <!-- only log ERROR level -->
    <level value="ERROR" />

    <!-- write all output to phex.log -->
    <appender-ref ref="DefaultFileAppender" />

    <!-- write all ERROR output to phex.log -->
    <appender-ref ref="ErrorFileAppender" />

    <!-- write all output to shell console -->
    <appender-ref ref="ConsoleAppender" />
  </root>
   
  <!-- configure logger for the class HttpFileDownload -->
  <logger name="phex.download.handler.HttpFileDownload" additivity="false">
    <!-- log DEBUG, INFO, WARN and ERROR -->
    <level value="DEBUG" />

    <!-- use root logger appenders -->

  </logger>

  <!-- configure logger for the whole package phex.gwebcache -->
  <logger name="phex.gwebcache" additivity="false">
    <!-- log DEBUG, INFO, WARN and ERROR -->
    <level value="DEBUG" />

    <!-- use root logger appenders -->

  </logger>

</configuration>