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
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 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
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" "http://www.opencloud.com/dtd/rhino-logging-config.dtd">
<rhino-logging-config config-version="1.0" rhino-version="Rhino-SDK (version='1.4.5', release='02', build='200709051254', revision='7671')" timestamp="1201439529105">
<logging base-directory="work/log" show-thread="true">
<logger additivity="false" name="rhino.management.profile.import">
<logger level="INFO" name="root">
<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.