Category:Logging

From Apache OpenOffice Wiki
Jump to: navigation, search

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:

[starbasic] 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: [starbasic]

 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.replaceByNBame( "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.

Pages in category "Logging"

This category contains only the following page.

Personal tools