Difference between revisions of "Category:Logging"

Latest revision as of 15:20, 27 April 2022

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

• Logging JDBC Activity

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 )

Each logger only logs to a single "DefaultHandler", which also has to be set and configured to get logging working.

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 the following 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:

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:

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

The default configuration of the FileHandler 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.) Using that handler with the line above, would create an output file org.openoffice.logging.DefaultLogger.log in ~/.openoffice.org resp. C:\Documents And Settings\<username>\Application Data\OpenOffice.org.

Or, to log to a syslog server:

Sub logToSyslog( sLoggerName As String, host as String, port )
  Dim oLoggerSettings as Object
  oLoggerSettings = getLoggerSettings( sLoggerName )
 
  oLoggerSettings.DefaultHandler = "com.sun.star.logging.SyslogHandler"
 
  Dim oHandlerSettings as Object
  oHandlerSettings = oLoggerSettings.getByName( "HandlerSettings" )
 
  If oHandlerSettings.hasByName( "Host" ) Then
    oHandlerSettings.replaceByName( "Host", host )
  Else
    oHandlerSettings.insertByName( "Host", host )
  End If
 
  If oHandlerSettings.hasByName( "Port" ) Then
    oHandlerSettings.replaceByName( "Port", port )
  Else
    oHandlerSettings.insertByName( "Port", port )
  End If
 
  oLoggerSettings.commitChanges()
End Sub

Additional settings which you can add to the HandlerSettings node are documented in the service constructors of ConsoleHandler, FileHandler, and SyslogHandler.

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.

The PlainTextFormatter is the one used by default, and does not have any configuration options. There is also a CsvLogFormatter writing the log records in CSV format, that could be set up.

Basic Code Download

The Basic code from above can be downloaded, in the form of an extension, here: File:Logging.oxt (if anybody knows how to upload a non-image as non-image, feel free to change this ...)