Difference between revisions of "Category:Logging"

From Apache OpenOffice Wiki
Jump to: navigation, search
 
m
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
==Overview==
 
==Overview==
  
With the integration of [http://eis.services.openoffice.org/EIS2/cws.ShowCWS?logon=true&Id=5132&Path=SRC680%2Fsdblogging CWS sdblogging], OpenOffice.org got (will get, at the moment of this writing) capabilities to log arbitrary events to targets such as files or the console.
+
With the integration of [http://eis.services.openoffice.org/EIS2/cws.ShowCWS?logon=true&Id=5132&Path=SRC680%2Fsdblogging 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.
 
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.
Line 8: Line 8:
  
 
Loggers configuration happens either at runtime, or via the configuration module <code>org.openoffice.Office.Logging</code>.
 
Loggers configuration happens either at runtime, or via the configuration module <code>org.openoffice.Office.Logging</code>.
 +
 +
==Known Loggers==
 +
<DPL>category=Logging</DPL>
  
 
==Configuration==
 
==Configuration==
Line 19: Line 22:
 
The following Basic procedure allows to tweak the log level of a certain logger:
 
The following Basic procedure allows to tweak the log level of a certain logger:
  
<code>[starbasic]
+
<source lang="oobas">
 
Sub setLogLevel( sLoggerName as String, nLevel as Long )
 
Sub setLogLevel( sLoggerName as String, nLevel as Long )
 
   Dim oLoggerSettings as Object
 
   Dim oLoggerSettings as Object
Line 53: Line 56:
 
   getLoggerSettings = oLoggerSettings
 
   getLoggerSettings = oLoggerSettings
 
End Function
 
End Function
</code>
+
</source>
  
 
With this, the following line of StarBasic code will turn OpenOffice.org's default logger <em>on</em>:
 
With this, the following line of StarBasic code will turn OpenOffice.org's default logger <em>on</em>:
<code>[starbasic]
+
<source lang="oobas">
 
   setLogLevel( "org.openoffice.logging.DefaultLogger", com.sun.star.logging.LogLevel.SEVERE )
 
   setLogLevel( "org.openoffice.logging.DefaultLogger", com.sun.star.logging.LogLevel.SEVERE )
</code>
+
</source>
  
 
This alone is usually sufficient to get a log file, since the default configuration of all loggers is to write to a file named <code><loggername>.log</code>, 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 <code>org.openoffice.logging.DefaultLogger.log</code> in <code>~/.openoffice.org</code> resp. <code>C:\Documents And Settings\<username>\Application Data\OpenOffice.org</code>.
 
This alone is usually sufficient to get a log file, since the default configuration of all loggers is to write to a file named <code><loggername>.log</code>, 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 <code>org.openoffice.logging.DefaultLogger.log</code> in <code>~/.openoffice.org</code> resp. <code>C:\Documents And Settings\<username>\Application Data\OpenOffice.org</code>.
Line 66: Line 69:
 
The configuration also allows to modify the output channel of a logger. For this, you need to specify the service name of the [http://api.openoffice.org/docs/common/ref/com/sun/star/logging/XLogHandler.html log handler] which should be used by the logger. Currently, there exist two log handler implementations:
 
The configuration also allows to modify the output channel of a logger. For this, you need to specify the service name of the [http://api.openoffice.org/docs/common/ref/com/sun/star/logging/XLogHandler.html log handler] which should be used by the logger. Currently, there exist two log handler implementations:
 
* A [http://api.openoffice.org/docs/common/ref/com/sun/star/logging/ConsoleHandler.html ConsoleHandler] writes its output to the console. By default, all events of level <code>LogLevel.SEVERE</code> are directed to stderr, all others to stdout.
 
* A [http://api.openoffice.org/docs/common/ref/com/sun/star/logging/ConsoleHandler.html ConsoleHandler] writes its output to the console. By default, all events of level <code>LogLevel.SEVERE</code> are directed to stderr, all others to stdout.
* A [http://api.openoffice.org/docs/common/ref/com/sun/star/logging/ConsoleHandler.html FileHandler] writes its output to a file, with a configurable encoding.
+
* A [http://api.openoffice.org/docs/common/ref/com/sun/star/logging/FileHandler.html 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:
 
The following piece of code sets a logger to direct its output to a console:
  
<code>[starbasic]
+
<source lang="oobas">
 
Sub logToConsole( sLoggerName as String, nThreshold as Long )
 
Sub logToConsole( sLoggerName as String, nThreshold as Long )
 
   Dim oLoggerSettings as Object
 
   Dim oLoggerSettings as Object
Line 81: Line 84:
  
 
   If oHandlerSettings.hasByName( "Threshold" ) Then
 
   If oHandlerSettings.hasByName( "Threshold" ) Then
     oHandlerSettings.Threshold = nThreshold
+
     oHandlerSettings.replaceByName( "Threshold", nThreshold )
 
   Else
 
   Else
 
     oHandlerSettings.insertByName( "Threshold", nThreshold )
 
     oHandlerSettings.insertByName( "Threshold", nThreshold )
Line 88: Line 91:
 
   oLoggerSettings.commitChanges()
 
   oLoggerSettings.commitChanges()
 
End Sub
 
End Sub
</code>
+
</source>
  
 
Alternatively, if you want to direct a logger's output to a file, use:
 
Alternatively, if you want to direct a logger's output to a file, use:
  
<code>[starbasic]
+
<source lang="oobas">
 
Sub logToFile( sLoggerName as String, sFileURL as String )
 
Sub logToFile( sLoggerName as String, sFileURL as String )
 
   Dim oLoggerSettings as Object
 
   Dim oLoggerSettings as Object
Line 103: Line 106:
  
 
   If oHandlerSettings.hasByName( "FileURL" ) Then
 
   If oHandlerSettings.hasByName( "FileURL" ) Then
     oHandlerSettings.Threshold = sFileURL
+
     oHandlerSettings.replaceByName( "FileURL", sFileURL )
 
   Else
 
   Else
 
     oHandlerSettings.insertByName( "FileURL", sFileURL )
 
     oHandlerSettings.insertByName( "FileURL", sFileURL )
Line 110: Line 113:
 
   oLoggerSettings.commitChanges()
 
   oLoggerSettings.commitChanges()
 
End Sub
 
End Sub
</code>
+
</source>
  
 
Note that as before, you might need to restart OpenOffice.org for the changes to take effect.
 
Note that as before, you might need to restart OpenOffice.org for the changes to take effect.
Line 121: Line 124:
  
 
However, currently the only implementation of a log formatter is the [http://api.openoffice.org/docs/common/ref/com/sun/star/logging/PlainTextFormatter.html PlainTextFormatter], which does not have any configuration options.
 
However, currently the only implementation of a log formatter is the [http://api.openoffice.org/docs/common/ref/com/sun/star/logging/PlainTextFormatter.html PlainTextFormatter], which does not have any configuration options.
 +
 +
=== Basic Code Download ===
 +
 +
The Basic code from above can be downloaded, in the form of an extension, here: [[image:Logging.oxt]] (if anybody knows how to upload a non-image as non-image, feel free to change this ...)
 +
[[Category:framework]]

Latest revision as of 12:41, 26 October 2009

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:

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

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.

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 ...)

Pages in category "Logging"

This category contains only the following page.

Personal tools