Client Logging
From Multiverse
| Using the Multiverse Client |
|
Install & Run • Supported Graphics Cards • Release Notes • Client FAQ • Troubleshooting • Connecting to a World • Client Metering • Using the Client Log File • Debugging Client Errors |
| Reference |
|
Command Line Syntax • World Settings File • Patcher Page Reference • Client Logging |
The Multiverse Client uses log4net framework for logging. Log4net is very similar to the server's log4j framework. See the Log4net Manual for complete documentation.
Contents |
Client log files
By default, the Multiverse Client creates log files in the client_home/log directory. Generally, client_home is C:\Documents and Settings\username\My Documents\Multiverse World Browser on Windows XP and C:\Users\username\Documents\Multiverse World Browser on Windows Vista.
By default, the client creates the following log files:
-
MultiverseClient.log- The main Client log file. -
Exception.log- A subset of the main log file, containing just errors and stack traces, and hardware profile information. -
ScriptDeprecated.log- A subset of the main log file, containing just warnings about calls to deprecated Client scripting API methods. Use this file to eliminate calls to deprecated methods from your code.
You can change the log directory and the names of the log files (as well as their formats and what information they contain) by changing the logging configuration file, described below.
Media patcher log
When it downloads assets from an asset repository, the client creates the file media_patcher.log containing a log of all media assets it has downloaded.
This file is outside the standard client logging framework and is not affected by the logging configuration.
The client will not create this file when using a local asset repository (for example, with the --development command line option).
Configuration file
The Multiverse Client reads a logging configuration file in the client_home\Config\ directory. By default, it uses DefaultLogConfig.xml. To customize logging, copy the default configuration file to LogConfig.xml, and modify as desired.
Important: Do not modify DefaultLogConfig.xml. The Client will recreate this file each time it starts, and you will lose any edits. Instead, copy it to LogConfig.xml, and edit that file.
The configuration file specifies:
- One or more appenders, each of which specifies an destination for log output and other associated details.
- A layout associated with each appender
- The root logger, and optionally, additional loggers. Each logger has a level and uses one of the previously defined appenders.
Log levels
Each loggers specifies a level that determines what events it records in the log file. The following are possible log levels, in order of increasing priority:
- ALL
- DEBUG
- INFO
- WARN
- ERROR
- FATAL
- OFF
Default configuration
The following table describes the default Multiverse Client logging configuration. By default, the client saves all log output to the user's "My Documents" folder, generally C:\Documents and Settings\username\My Documents\Multiverse World Browser on Windows XP and C:\Users\username\Documents\Multiverse World Browser on Windows Vista.
By default, the client uses the log4net.Layout.PatternLayout layout.
| Appender Name | Log file | Log4Net Appender Class | Description |
|---|---|---|---|
| RollingFile | MultiverseClient.log
| log4net.Appender.RollingFileAppender | Contains all log output . |
| DeprecatedFile | ScriptDeprecated.log
| log4net.Appender.RollingFileAppender | Contains calls to deprecated scritping APIs |
| ExceptionFile | Exception.log
| log4net.Appender.RollingFileAppender | Contains only exception stack traces. |
RollingFileAppender properties
Specify properties for an appender with tags within the <appender> tag as follows:
<propertyName value="value" />
For example,
<rollingStyle value="once" />
RollingStyle specifies the criteria that RollingFileAppender uses to "roll over" log files: size, date, or both. When the Client rolls over a log file, by default it renames the current log file to foo.log.1, renames any existing foo.log.1 to foo.log.2, and so on, and then writes further log messages to foo.log. The most recent log files always have extension .log.
If RollingStyle is:
- Size, the Client rolls over the log file when its size exceeds the MaximumFileSize.
- Date, the Client rolls over the log file when the date boundary specified in the DatePattern property is crossed.
- Composite, the Client rolls over the log file when the date boundary specified in the DatePattern property is crossed, but within a date boundary the file will also be rolled once its size exceeds the MaximumFileSize.
- Once, the Client rolls over the log file when the appender is configured. This effectively means that the log file is rolled once per program execution.
file property specifies the name of the log file.
appendToFile is a Boolean value that indicates whether the file should be appended to or overwritten.
maximumFileSize specifies the maximum size that the output file is allowed to reach before being rolled over to backup files. You can use suffixes "KB", "MB" or "GB" to denote kilobytes, megabytes or gigabytes. The default maximum file size is 10MB.
maxSizeRollBackups specifies the maximum number of backup files that are kept before the oldest is erased. The maximum applies to each time-based group of files and not the total. If set to zero, then there will be no backup files and the log file will be truncated when it reaches MaxFileSize. If set to a negative number, then the Client will not delete any files, which could result in very slow performance as a large number of files are rolled over unless CountDirection is used.
CountDirection indicates if the current file is the lowest numbered file or the highest numbered file. By default, newer files have lower numbers (CountDirection less than zero), that is, log.1 is most recent, log.5 is the 5th backup, and so on. CountDirection of zero or greater does the opposite: log.1 is the first backup made, log.5 is the 5th backup made, and so on. For infinite backups use CountDirection greater than or equal to zero to reduce rollover costs. The default value is -1.
Default configuration file
The default logging configuration file is DefaultLogConfig.xml in your "My Documents" folder, generally C:\Documents and Settings\username\My Documents\Multiverse World Browser on Windows XP and C:\Users\username\Documents\Multiverse World Browser on Windows Vista.
The configuration file is reproduced here for reference. Do not modify this file. The client will recreate it each time it starts, and you will lose any edits.
<?xml version="1.0" encoding="utf-8" ?>
<log4net>
<appender name="RollingFile" type="log4net.Appender.RollingFileAppender">
<file value="../Logs/MultiverseClient.log" />
<appendToFile value="false" />
<maximumFileSize value="100MB" />
<maxSizeRollBackups value="2" />
<rollingStyle value="once" />
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%-5p [%d{ISO8601}] %-20.20c{1} %m%n" />
</layout>
</appender>
<appender name="DeprecatedFile" type="log4net.Appender.RollingFileAppender">
<file value="../Logs/ScriptDeprecated.log" />
<appendToFile value="false" />
<maximumFileSize value="100MB" />
<maxSizeRollBackups value="2" />
<rollingStyle value="once" />
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%-5p [%d{ISO8601}] %-20.20c{1} %m%n" />
</layout>
</appender>
<appender name="ExceptionFile" type="log4net.Appender.RollingFileAppender">
<file value="../Logs/Exception.log" />
<appendToFile value="false" />
<maximumFileSize value="1MB" />
<maxSizeRollBackups value="2" />
<rollingStyle value="once" />
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%-5p [%d{ISO8601}] %-20.20c{1} %m%n" />
</layout>
</appender>
<appender name="TraceAppender" type="log4net.Appender.TraceAppender">
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%-5p %m%n" />
</layout>
</appender>
<root>
<level value="INFO" />
<appender-ref ref="RollingFile" />
<appender-ref ref="TraceAppender" />
</root>
<logger name="ScriptDeprecated">
<level value="WARN" />
<appender-ref ref="DeprecatedFile" />
</logger>
<logger name="Exception">
<level value="DEBUG" />
<appender-ref ref="ExceptionFile" />
</logger>
<logger name="HardwareCaps">
<level value="DEBUG" />
<appender-ref ref="ExceptionFile" />
</logger>
</log4net>
