Logging

From OpenSimulator

(Difference between revisions)
Jump to: navigation, search
(Setting log levels during runtime)
(Specifying log file location per instance)
 
(19 intermediate revisions by 10 users not shown)
Line 1: Line 1:
 +
__NOTOC__
 +
{{Quicklinks}}
 +
<br />
 +
 
== Changing logging levels before startup ==
 
== Changing logging levels before startup ==
  
OpenSim uses the [http://logging.apache.org/log4net/ log4net] package for logging. This means that every executable you run for OpenSim has an accompanying .config file which contains the logging configuration
+
OpenSimulator uses the [http://logging.apache.org/log4net/ log4net] package for logging. This means that every executable you run for OpenSimulator has an accompanying .config file which contains the logging configuration
 +
 
 +
For instance
 +
 
 +
* OpenSim.exe -> config is OpenSim.exe.config
 +
* OpenSim.32BitLaunch.exe -> config is OpenSim.32BitLaunch.exe.config
 +
* Robust.exe -> config is Robust.exe.config
  
For instance, the OpenSim.exe.config file looks like this.
+
The OpenSim.exe.config file looks like this.
  
 
  <?xml version="1.0" encoding="utf-8" ?>
 
  <?xml version="1.0" encoding="utf-8" ?>
Line 18: Line 28:
 
       </layout>
 
       </layout>
 
     </appender>
 
     </appender>
 
+
 
     <appender name="LogFileAppender" type="log4net.Appender.FileAppender">
 
     <appender name="LogFileAppender" type="log4net.Appender.FileAppender">
 
       <file value="OpenSim.log" />
 
       <file value="OpenSim.log" />
Line 26: Line 36:
 
       </layout>
 
       </layout>
 
     </appender>
 
     </appender>
 
+
 
     <!-- if you'd like to know what NHibernate is doing more set value="DEBUG" -->
 
     <!-- if you'd like to know what NHibernate is doing more set value="DEBUG" -->
 
     <logger name="NHibernate" additivity="false">
 
     <logger name="NHibernate" additivity="false">
Line 32: Line 42:
 
       <appender-ref ref="NHibernateFileLog"/>
 
       <appender-ref ref="NHibernateFileLog"/>
 
     </logger>
 
     </logger>
 
+
 
     <root>
 
     <root>
 
       <level value="DEBUG" />
 
       <level value="DEBUG" />
Line 41: Line 51:
 
  </configuration>
 
  </configuration>
  
This looks rather complicated, but if you want to change the level of messages logged, then you could change the value in
+
This looks rather complicated, but if you want to change the level of messages logged, then you could change the value in the <root> section (right at the end) which is
  
 
  <level value="DEBUG" />
 
  <level value="DEBUG" />
  
to something different, e.g.
+
in the example above to something different, e.g.
  
 
  <level value="WARN" />
 
  <level value="WARN" />
  
which will only display warning and error level log messages. Permissible values are ALL, DEBUG, INFO, WARN, ERROR, FATAL, OFF
+
which will only display warning and error level log messages. Permissible values are ALL, DEBUG, INFO, WARN, ERROR, FATAL, OFF
  
 
You can also see from the OpenSim.exe.config file that log files are written to OpenSim.log (as well as the console).
 
You can also see from the OpenSim.exe.config file that log files are written to OpenSim.log (as well as the console).
 +
 +
=== Rolling file appender and maximum log-file size ===
 +
 +
Log4net provides several log-file appenders. One of them is the ''RollingFileAppender'', which limits log-file size and rotates log-files automatically. To use this appender, add the following section to the log4net-configuration:
 +
 +
<appender name="RollingFileAppender" type="log4net.Appender.RollingFileAppender">
 +
  <file value="OpenSim.log" />
 +
  <appendToFile value="true" />
 +
  <maximumFileSize value="1000KB" />
 +
  <maxSizeRollBackups value="2" />
 +
  <layout type="log4net.Layout.PatternLayout">
 +
    <conversionPattern value="%date %-5level - %logger %message%newline" />
 +
  </layout>
 +
</appender>
 +
 +
The maximum size can be set in the ''maximumFileSize'' element, the ''maxSizeRollBackups'' element determines the maximum number of rolling log-files. So, the setting above will create a log-file named ''OpenSim.log'' with a maximum size of 1000KB. When the limit is reached, ''OpenSim.log'' will be renamed to ''OpenSim.log.1'', and a fresh ''OpenSim.log'' is started (possibly after renaming ''OpenSim.log.1'' to ''OpenSim.log.2'', should that file exist already).
 +
 +
To use the appender defined above, replace the line
 +
  <appender-ref ref="LogFileAppender" />
 +
by
 +
  <appender-ref ref="RollingFileAppender" />
 +
 +
Further information about configuration of log4net can be found on the [http://logging.apache.org/log4net/release/manual/configuration.html Log4Net configuration page].
 +
 +
=== More specialized requirements ===
 +
As an example, similar to [http://opensimulator.org/mantis/view.php?id=2603 Mantis#2603], if you want logging the [[XEngine]]'s DEBUG output into a separate file ''xengine.log'', and let only the message with level INFO and higher appear on the console, you can do that by adding the following lines to your ''OpenSim.exe.config'':
 +
 +
    <appender name="XengineLogFileAppender" type="log4net.Appender.FileAppender">
 +
      <file value="xengine.log" />
 +
      <appendToFile value="true" />
 +
      <layout type="log4net.Layout.PatternLayout">
 +
        <conversionPattern value="%date %-5level - %logger %message%newline" />
 +
      </layout>
 +
    </appender>
 +
 +
    <appender name="XengineConsole" type="OpenSim.Framework.Console.OpenSimAppender, OpenSim.Framework.Console">
 +
      <layout type="log4net.Layout.PatternLayout">
 +
        <conversionPattern value="%date{HH:mm:ss} - %message%newline" />
 +
      </layout>
 +
      <filter type="log4net.Filter.LevelRangeFilter">
 +
        <levelMin value="INFO" />
 +
        <levelMax value="FATAL" />
 +
      </filter>
 +
    </appender>
 +
 +
    <logger name="OpenSim.Region.ScriptEngine.XEngine.XEngine" additivity="false">
 +
      <appender-ref ref="XengineLogFileAppender" />
 +
      <appender-ref ref="XengineConsole" />
 +
    </logger>
 +
 +
(if there is a shorter way to do it, please replace those lines above) ;-)
 +
 +
Or, as an easier example, if you want to have the normal logging, except for the HttpServers which you want only INFO messages for, you can add the following lines after the ''</root>''-tag:
 +
 +
    <logger name="OpenSim.Framework.Servers.HttpServerLogWriter">
 +
      <level value="INFO" />
 +
    </logger>
 +
 +
=== MySQL Logging ===
 +
This example can be used to log the data to a MySQL table.
 +
 +
Step 1: Create a MySQL Database "OSLog" and add the following table to which the data will be stored to
 +
 +
  CREATE TABLE `opensim_log` (
 +
  `ID` int(10) NOT NULL AUTO_INCREMENT,
 +
  `DATE` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
 +
  `Level` varchar(100) DEFAULT '',
 +
  `Logger` varchar(512) DEFAULT '',
 +
  `Message` varchar(1000) DEFAULT '',
 +
  PRIMARY KEY (`ID`)
 +
  ); 
 +
 +
Step 2: Replace the "LogFileAppender" appender Section with
 +
 +
  <appender name="MySql_ADONetAppender" type="log4net.Appender.ADONetAppender">
 +
    <bufferSize value="5" />
 +
    <lossy value="false"/>
 +
    <connectionType value="MySql.Data.MySqlClient.MySqlConnection, MySql.Data"/>
 +
    <connectionString value="Server=localhost;Database=OSLog;Uid=DBUsername;Pwd=DBUserPassword"/>
 +
    <commandText value="INSERT INTO opensim_log(Date,Level,Logger,Message) VALUES (@log_date, @log_level, @logger, @message)"/>
 +
    <parameter>
 +
      <parameterName value="@log_date"/>
 +
      <dbType value="DateTime"/>
 +
      <layout type="log4net.Layout.RawTimeStampLayout"/>
 +
    </parameter>
 +
    <parameter>
 +
      <parameterName value="@log_level"/>
 +
      <dbType value="String"/>
 +
      <size value="512"/>
 +
      <layout type="log4net.Layout.PatternLayout">
 +
        <conversionPattern value="%level"/>
 +
      </layout>
 +
    </parameter>
 +
    <parameter>
 +
      <parameterName value="@logger"/>
 +
      <dbType value="String"/>
 +
      <size value="512"/>
 +
      <layout type="log4net.Layout.PatternLayout">
 +
        <conversionPattern value="%logger"/>
 +
      </layout>
 +
    </parameter>
 +
    <parameter>
 +
      <parameterName value="@message"/>
 +
      <dbType value="String"/>
 +
      <size value="1000"/>
 +
      <layout type="log4net.Layout.PatternLayout">
 +
        <conversionPattern value="%message"/>
 +
      </layout>
 +
    </parameter>
 +
  </appender>
 +
 +
To use the appender defined above, replace the line
 +
  <appender-ref ref="LogFileAppender" />
 +
by
 +
  <appender-ref ref="MySql_ADONetAppender" />
 +
 +
Note: One also can continue logging to File, in which case we do not need to replace the LogFileAppender section.
  
 
== Setting log levels during runtime ==
 
== Setting log levels during runtime ==
  
It isn't currently possible to change the level of logging to the log file during runtime. However, it is possible to change the level sent to the console. You can do this by executing the
+
It isn't currently possible to change the level of logging to the log file during runtime. However, it is possible to change the level sent to the console. You can do this by executing the
  
 
  set log level [<level>]
 
  set log level [<level>]
  
command. For example
+
command. For example
  
 
  set log level error
 
  set log level error
  
will mean only errors are sent to the console. The log still receives messages that meet the level set in the OpenSim.exe.config file at startup.
+
will mean only errors are sent to the console. The log still receives messages that meet the level set in the OpenSim.exe.config file at startup.
 +
 
 +
get log level
 +
 
 +
will tell you what the current console logging level is.
 +
 
 +
Changes to the log level sent to the console will not persist over restarts. If you want the change to be permanent, you can set a threshold value in the ConsoleAppender in a config file such as OpenSim.exe.config as described above.
 +
 
 +
== Specifying log file location per instance ==
 +
 
 +
Logging for multiple instances run from a single OpenSim.exe isn't something that the default log4net configuration handles. Fortunately, log4net accepts environment variables. This allows a script wrapping OpenSim.exe to specify a log location by setting an environment variable. An example snippet for ''Opensim.exe.config'' might be:
 +
 
 +
    <appender name="LogFileAppender" type="log4net.Appender.FileAppender">
 +
      <file type="log4net.Util.PatternString" value="%env{OSIM_LOGPATH}\OpenSim.log" />
 +
      <appendToFile value="true" />
 +
      <layout type="log4net.Layout.PatternLayout">
 +
        <conversionPattern value="%date %-5level - %logger %message%newline" />
 +
      </layout>
 +
    </appender>
 +
 
 +
 
 +
When OpenSimulator is running under Mono in Linux, then you should have something in your startscript.sh like
 +
 
 +
    export LOGFILEPATH='/some/absolute/path/'
 +
 
 +
 
  
Not specifying any level will tell you what the current console logging level actually is.
+
... and in Opensim.exe.config
  
Changing the log level sent to the console will not persist over restarts. If you want the change to be permanent, you can set a threshold value in the ConsoleAppender (see the log4net docs for more details).
+
    <file type="log4net.Util.PatternString" value="${LOGFILEPATH}OpenSim.log" />

Latest revision as of 08:42, 14 March 2021


[edit] Changing logging levels before startup

OpenSimulator uses the log4net package for logging. This means that every executable you run for OpenSimulator has an accompanying .config file which contains the logging configuration

For instance

  • OpenSim.exe -> config is OpenSim.exe.config
  • OpenSim.32BitLaunch.exe -> config is OpenSim.32BitLaunch.exe.config
  • Robust.exe -> config is Robust.exe.config

The OpenSim.exe.config file looks like this.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
 <configSections>
   <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler,log4net" />
 </configSections>
 <appSettings>
 </appSettings>
 <log4net>
   <appender name="Console" type="OpenSim.Framework.Console.OpenSimAppender, OpenSim.Framework.Console">
     <layout type="log4net.Layout.PatternLayout">
       <conversionPattern value="%date{HH:mm:ss} - %message%newline" />
     </layout>
   </appender>

   <appender name="LogFileAppender" type="log4net.Appender.FileAppender">
     <file value="OpenSim.log" />
     <appendToFile value="true" />
     <layout type="log4net.Layout.PatternLayout">
       <conversionPattern value="%date %-5level - %logger %message%newline" />
     </layout>
   </appender>

   <logger name="NHibernate" additivity="false">
     <level value="INFO"/>
     <appender-ref ref="NHibernateFileLog"/>
   </logger>

   <root>
     <level value="DEBUG" />
     <appender-ref ref="Console" />
     <appender-ref ref="LogFileAppender" />
   </root>
 </log4net>
</configuration>

This looks rather complicated, but if you want to change the level of messages logged, then you could change the value in the <root> section (right at the end) which is

<level value="DEBUG" />

in the example above to something different, e.g.

<level value="WARN" />

which will only display warning and error level log messages. Permissible values are ALL, DEBUG, INFO, WARN, ERROR, FATAL, OFF

You can also see from the OpenSim.exe.config file that log files are written to OpenSim.log (as well as the console).

[edit] Rolling file appender and maximum log-file size

Log4net provides several log-file appenders. One of them is the RollingFileAppender, which limits log-file size and rotates log-files automatically. To use this appender, add the following section to the log4net-configuration:

<appender name="RollingFileAppender" type="log4net.Appender.RollingFileAppender">
  <file value="OpenSim.log" />
  <appendToFile value="true" />
  <maximumFileSize value="1000KB" />
  <maxSizeRollBackups value="2" />
  <layout type="log4net.Layout.PatternLayout">
    <conversionPattern value="%date %-5level - %logger %message%newline" />
  </layout>
</appender>

The maximum size can be set in the maximumFileSize element, the maxSizeRollBackups element determines the maximum number of rolling log-files. So, the setting above will create a log-file named OpenSim.log with a maximum size of 1000KB. When the limit is reached, OpenSim.log will be renamed to OpenSim.log.1, and a fresh OpenSim.log is started (possibly after renaming OpenSim.log.1 to OpenSim.log.2, should that file exist already).

To use the appender defined above, replace the line

 <appender-ref ref="LogFileAppender" />

by

 <appender-ref ref="RollingFileAppender" />

Further information about configuration of log4net can be found on the Log4Net configuration page.

[edit] More specialized requirements

As an example, similar to Mantis#2603, if you want logging the XEngine's DEBUG output into a separate file xengine.log, and let only the message with level INFO and higher appear on the console, you can do that by adding the following lines to your OpenSim.exe.config:

   <appender name="XengineLogFileAppender" type="log4net.Appender.FileAppender">
     <file value="xengine.log" />
     <appendToFile value="true" />
     <layout type="log4net.Layout.PatternLayout">
       <conversionPattern value="%date %-5level - %logger %message%newline" />
     </layout>
   </appender>

   <appender name="XengineConsole" type="OpenSim.Framework.Console.OpenSimAppender, OpenSim.Framework.Console">
     <layout type="log4net.Layout.PatternLayout">
       <conversionPattern value="%date{HH:mm:ss} - %message%newline" />
     </layout>
     <filter type="log4net.Filter.LevelRangeFilter">
       <levelMin value="INFO" />
       <levelMax value="FATAL" />
     </filter>
   </appender>

   <logger name="OpenSim.Region.ScriptEngine.XEngine.XEngine" additivity="false">
     <appender-ref ref="XengineLogFileAppender" />
     <appender-ref ref="XengineConsole" />
   </logger>

(if there is a shorter way to do it, please replace those lines above) ;-)

Or, as an easier example, if you want to have the normal logging, except for the HttpServers which you want only INFO messages for, you can add the following lines after the </root>-tag:

   <logger name="OpenSim.Framework.Servers.HttpServerLogWriter">
     <level value="INFO" />
   </logger>

[edit] MySQL Logging

This example can be used to log the data to a MySQL table.

Step 1: Create a MySQL Database "OSLog" and add the following table to which the data will be stored to

 CREATE TABLE `opensim_log` (
  `ID` int(10) NOT NULL AUTO_INCREMENT,
  `DATE` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `Level` varchar(100) DEFAULT ,
  `Logger` varchar(512) DEFAULT ,
  `Message` varchar(1000) DEFAULT ,
  PRIMARY KEY (`ID`) 
 );  

Step 2: Replace the "LogFileAppender" appender Section with

 <appender name="MySql_ADONetAppender" type="log4net.Appender.ADONetAppender">
   <bufferSize value="5" />
   <lossy value="false"/>
   <connectionType value="MySql.Data.MySqlClient.MySqlConnection, MySql.Data"/>
   <connectionString value="Server=localhost;Database=OSLog;Uid=DBUsername;Pwd=DBUserPassword"/>
   <commandText value="INSERT INTO opensim_log(Date,Level,Logger,Message) VALUES (@log_date, @log_level, @logger, @message)"/>
   <parameter>
     <parameterName value="@log_date"/>
     <dbType value="DateTime"/>
     <layout type="log4net.Layout.RawTimeStampLayout"/>
   </parameter>
   <parameter>
     <parameterName value="@log_level"/>
     <dbType value="String"/>
     <size value="512"/>
     <layout type="log4net.Layout.PatternLayout">
       <conversionPattern value="%level"/>
     </layout>
   </parameter>
   <parameter>
     <parameterName value="@logger"/>
     <dbType value="String"/>
     <size value="512"/>
     <layout type="log4net.Layout.PatternLayout">
       <conversionPattern value="%logger"/>
     </layout>
   </parameter>
   <parameter>
     <parameterName value="@message"/>
     <dbType value="String"/>
     <size value="1000"/>
     <layout type="log4net.Layout.PatternLayout">
       <conversionPattern value="%message"/>
     </layout>
   </parameter>
 </appender>

To use the appender defined above, replace the line

 <appender-ref ref="LogFileAppender" />

by

 <appender-ref ref="MySql_ADONetAppender" />

Note: One also can continue logging to File, in which case we do not need to replace the LogFileAppender section.

[edit] Setting log levels during runtime

It isn't currently possible to change the level of logging to the log file during runtime. However, it is possible to change the level sent to the console. You can do this by executing the

set log level [<level>]

command. For example

set log level error

will mean only errors are sent to the console. The log still receives messages that meet the level set in the OpenSim.exe.config file at startup.

get log level

will tell you what the current console logging level is.

Changes to the log level sent to the console will not persist over restarts. If you want the change to be permanent, you can set a threshold value in the ConsoleAppender in a config file such as OpenSim.exe.config as described above.

[edit] Specifying log file location per instance

Logging for multiple instances run from a single OpenSim.exe isn't something that the default log4net configuration handles. Fortunately, log4net accepts environment variables. This allows a script wrapping OpenSim.exe to specify a log location by setting an environment variable. An example snippet for Opensim.exe.config might be:

   <appender name="LogFileAppender" type="log4net.Appender.FileAppender">
     <file type="log4net.Util.PatternString" value="%env{OSIM_LOGPATH}\OpenSim.log" /> 
     <appendToFile value="true" />
     <layout type="log4net.Layout.PatternLayout">
       <conversionPattern value="%date %-5level - %logger %message%newline" />
     </layout>
   </appender>


When OpenSimulator is running under Mono in Linux, then you should have something in your startscript.sh like

   export LOGFILEPATH='/some/absolute/path/'


... and in Opensim.exe.config

   <file type="log4net.Util.PatternString" value="${LOGFILEPATH}OpenSim.log" />
Personal tools
General
About This Wiki