Category:Logging
Contents
Overview
With the integration of CWS sdblogging, OpenOffice.org got capabilities to log arbitrary events to targets such as files or the console.
A component which wants to log events can access a named logger (where the name should be unique across all OOo components), and forward log messages to it. The logger will emit those messages, together with additional information, e.g. a time stamp, to its output medium. Currently, files and the processes console are supported output mediums.
Log messages have so-called log levels associated with it, which define the severity of the logged event. Loggers can be configured to ignore all events below a certain level, which allows fine-tuning of the events you get to see.
Loggers configuration happens either at runtime, or via the configuration module org.openoffice.Office.Logging
.
Known Loggers
Configuration
Assume you know a component uses a certain named logger to log events. Usually, every component will ship with it's logger turned off, so the logging overhead will only apply when you explicitly enable it.
Enabling a logger / Setting a LogLevel
So, the first thing you want to configure is to turn the logger on. This is done implicitly by modifying its LogLevel
. This setting defines which events are logged (all with a level greater than or equal the LogLevel
), and which are ignored (all others). By default, a logger's LogLevel
is configured to be LogLevel.OFF.
The following Basic procedure allows to tweak the log level of a certain logger:
Sub setLogLevel( sLoggerName as String, nLevel as Long ) Dim oLoggerSettings as Object oLoggerSettings = getLoggerSettings( sLoggerName ) oLoggerSettings.LogLevel = nLevel oLoggerSettings.commitChanges() End Sub Function getLoggerSettings( sLoggerName as String ) as Object Dim oConfigProvider as Object oConfigProvider = createUnoService( "com.sun.star.configuration.ConfigurationProvider" ) Dim aArgs(0) as new com.sun.star.beans.NamedValue aArgs(0).Name = "nodepath" aArgs(0).Value = "/org.openoffice.Office.Logging/Settings" Dim oAllSettings as Object oAllSettings = oConfigProvider.createInstanceWithArguments( _ "com.sun.star.configuration.ConfigurationUpdateAccess", aArgs() ) ' if not configuration for this logger exists, yet, create it if ( Not oAllSettings.hasByName( sLoggerName ) ) Then oAllSettings.insertByName( sLoggerName, oAllSettings.createInstance() ) oAllSettings.commitChanges() End If Dim oLoggerSettings as Object aArgs(0).Value = "/org.openoffice.Office.Logging/Settings/" & sLoggerName oLoggerSettings = oConfigProvider.createInstanceWithArguments( _ "com.sun.star.configuration.ConfigurationUpdateAccess", aArgs() ) getLoggerSettings = oLoggerSettings End Function
With this, the following line of StarBasic code will turn OpenOffice.org's default logger on:
setLogLevel( "org.openoffice.logging.DefaultLogger", com.sun.star.logging.LogLevel.SEVERE )
This alone is usually sufficient to get a log file, since the default configuration of all loggers is to write to a file named <loggername>.log
, located in the user's data directory. (Note, however, that currently you might need to restart OpenOffice.org for the changes to take effect.) That is, with the line above, the default logger would create an output file org.openoffice.logging.DefaultLogger.log
in ~/.openoffice.org
resp. C:\Documents And Settings\<username>\Application Data\OpenOffice.org
.
Changing the Output Channel
The configuration also allows to modify the output channel of a logger. For this, you need to specify the service name of the log handler which should be used by the logger. Currently, there exist two log handler implementations:
- A ConsoleHandler writes its output to the console. By default, all events of level
LogLevel.SEVERE
are directed to stderr, all others to stdout. - A FileHandler writes its output to a file, with a configurable encoding.
The following piece of code sets a logger to direct its output to a console:
[starbasic]
Sub logToConsole( sLoggerName as String, nThreshold as Long )
Dim oLoggerSettings as Object oLoggerSettings = getLoggerSettings( sLoggerName )
oLoggerSettings.DefaultHandler = "com.sun.star.logging.ConsoleHandler"
Dim oHandlerSettings as Object oHandlerSettings = oLoggerSettings.getByName( "HandlerSettings" )
If oHandlerSettings.hasByName( "Threshold" ) Then oHandlerSettings.replaceByName( "Threshold", nThreshold ) Else oHandlerSettings.insertByName( "Threshold", nThreshold ) End If
oLoggerSettings.commitChanges()
End Sub
Alternatively, if you want to direct a logger's output to a file, use:
[starbasic]
Sub logToFile( sLoggerName as String, sFileURL as String )
Dim oLoggerSettings as Object oLoggerSettings = getLoggerSettings( sLoggerName )
oLoggerSettings.DefaultHandler = "com.sun.star.logging.FileHandler"
Dim oHandlerSettings as Object oHandlerSettings = oLoggerSettings.getByName( "HandlerSettings" )
If oHandlerSettings.hasByName( "FileURL" ) Then oHandlerSettings.replaceByName( "FileURL", sFileURL ) Else oHandlerSettings.insertByName( "FileURL", sFileURL ) End If
oLoggerSettings.commitChanges()
End Sub
Note that as before, you might need to restart OpenOffice.org for the changes to take effect.
Additional settings which you can add to the HandlerSettings node are documented in the service constructors of ConsoleHandler resp. FileHandler.
Changing the Output Format
An additional facet to configure is the formatting of the output. Well, at least in theory. There exist configuration nodes DefaultFormatter
and FormatterSettings
, which work exactly the same way as DefaultHandler
and HandlerSettings
.
However, currently the only implementation of a log formatter is the PlainTextFormatter, which does not have any configuration options.