Access Keys:
Skip to content (Access Key - 0)

How-to Configure File Appenders

Print this page


This article describes how to setup and configure file appenders in Rhino, and how to use appenders to filter logging output.

Types of Appenders

Rhino's logging system sends log messages to one or more appenders, depending on configuration. The standard Rhino logging configuration includes three appenders - a console appender which writes all log messages to the console, a file appender which writes all log messages to a logfile, rhino.log, and a second file appender which writes configuration related logging messages to config.log.
This article discusses user configuration of additional file appenders.

Rolling File Appenders

File appenders may be configured to rollover automatically after the file reaches a certain size. When a log file is rolled over the current file is renamed to an archive filename of the format <filename>.<N> where <N> is the next archive sequence number in log file's directory. Additionally Rhino may be configured to automatically remove the oldest archive file whenever a new log file is created. The number of backup files to keep at any one time can be configured.

Creating a File Appender

To create a file appender use the createfileappender command in rhino-console, passing a symbolic name for the appender, and a filename to be used for files created by that appender:

[Rhino@localhost (#1)] help fileappender
Matching commands:
  createfileappender <appender-name> <filename>
     Create a file appender
[Rhino@localhost (#2)] createfileappender FILEAPP myfile.log

The listappenders command will show currently configured appenders:

[Rhino@localhost (#3)] listappenders

Sending output to a File Appender

To have output sent to a file appender it must be attached to a logger. Rhino loggers are hierarchical in nature, with every logger passing log messages to its parent. This means that appenders receive log messages for all loggers it is attached to and all children of loggers it is attached to. The default loggers STDERR and RhinoLog are attached to the root logger (which has the special name root) and thus receive all log messages output by Rhino, while the logger ConfigLog is attached to the logger rhino.config.

To attach an appender to a logger use the addappenderref command, passing the name of the logger and the name of the appender:

[Rhino@localhost (#5)] addappenderref root FILEAPP 

The listappenderrefs command will list all appenders attached to a log key:

[Rhino@localhost (#6)] listappenderrefs root

Using a File Appender to log Trace Messages

Trace messages emitted by SBB's are logged by Rhino under the log key trace. By attaching a file appender to the trace logger all trace messages can be captured in a log file:

[Rhino@localhost (#7)] createfileappender Trace trace.log
[Rhino@localhost (#8)] addappenderref trace Trace 

Advanced Settings

Advanced configuration options such as maximum log file size before rolling over and the number of backup log files to keep are available. These can be set for a file appender either via the web console or by editing the logging configuration XML. The following example shows how to export Rhino's current logging configuration to a file, edit it to create a new appender or modify the properties of an existing one, and re-import it. Note, Rhino's logging configuration is stored in the file config/logging.xml in Rhino's work directory. The export / import procedure below is the recommended method for editing the logging configuration. It is not recommended to edit the file on disk directly, even if Rhino is not running. This will produce especially unpredictable results in clustered environments.

To export the current logging configuration to a file use the exportconfig command in rhino-console:

[Rhino@localhost (#12)] exportconfig logging logging-conf.xml
Export logging: (all keys) to logging-conf.xml
Wrote logging-conf.xml

The above command produced the following configuration file in the working directory:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rhino-logging-config PUBLIC "-//Open Cloud Ltd.//DTD Rhino Logging Config 1.0//EN" "">
<rhino-logging-config config-version="1.0" rhino-version="Rhino-SDK (version='1.4.5', release='02', build='200709051254', revision='7671')" timestamp="1201439529105">
    <!-- Generated Rhino configuration file: 2008-01-27 21:12:09.104 -->
    <logging base-directory="work/log" show-thread="true">
        <logger additivity="false" name="">
        <logger name="rhino.config">
        <logger level="INFO" name="root">
        <logger name="trace">
        <console-appender name="STDERR" target="System.err"/>
        <file-appender filename="rhino.log" maximum-backup-files="4" maximum-file-size="104857600" name="RhinoLog"/>
        <file-appender filename="config.log" maximum-backup-files="4" maximum-file-size="104857600" name="ConfigLog"/>
        <file-appender filename="myfile.log" name="FILEAPP"/>
        <file-appender filename="trace.log" name="Trace"/>

The two new appenders created in this how-to appear at the end of the file. Because neither appender has the maximum-backup-files or maximum-file-size properties set they will both use the system defaults which is to limit files to 64M in size and keep an unlimited number of backups. To change the file size and specify a maximum number of backups for the trace.log file appender edit the configuration file and add maximum-backup-files and maximum-file-size properties:

<file-appender filename="trace.log" name="Trace" maximum-backup-files="20" maximum-file-size="120000000"/>

The above configuration keeps 20 backup files and uses a maximum file size of 120 megabytes. Re-import the configuration file using rhino-console's importconfig command:

[Rhino@localhost (#0)] importconfig logging logging-conf.xml -replace
Configuration successfully imported.

Manual log file rollover

Log files can be rolled over manually using JMX management API's. The web console provides operations to rollover the log files of individual appenders, or all appenders. Alternately the rolloverlogfiles command in rhino-console can be used to quickly rollover all appenders.

Adaptavist Theme Builder Powered by Atlassian Confluence