Difference between revisions of "Category:Logging"
(Document the new syslog handler) |
|||
(14 intermediate revisions by 4 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 | + | 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: | ||
− | < | + | <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 | ||
− | </ | + | </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>: | ||
− | < | + | <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 ) | ||
− | </ | + | </source> |
− | + | Each logger only logs to a single "DefaultHandler", which also has to be set and configured to get logging working. | |
===Changing the Output Channel=== | ===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 [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 | + | 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 the following 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/ | + | * 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: | ||
− | < | + | <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 | + | 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 | ||
− | </ | + | </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: | ||
− | < | + | <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. | + | 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 | ||
− | </ | + | </source> |
− | Note | + | The default configuration of the FileHandler 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.) Using that handler with the line above, 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>. |
− | Additional settings which you can add to the HandlerSettings node are documented in the service constructors of [http://api.openoffice.org/docs/common/ref/com/sun/star/logging/ConsoleHandler.html ConsoleHandler] | + | Or, to log to a syslog server: |
+ | |||
+ | <source lang="oobas"> | ||
+ | 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 | ||
+ | </source> | ||
+ | |||
+ | Additional settings which you can add to the HandlerSettings node are documented in the service constructors of [http://api.openoffice.org/docs/common/ref/com/sun/star/logging/ConsoleHandler.html ConsoleHandler], [http://api.openoffice.org/docs/common/ref/com/sun/star/logging/FileHandler.html FileHandler], and [http://api.openoffice.org/docs/common/ref/com/sun/star/logging/SyslogHandler.html SyslogHandler]. | ||
===Changing the Output Format=== | ===Changing the Output Format=== | ||
Line 120: | Line 151: | ||
An additional facet to configure is the formatting of the output. Well, at least in theory. There exist configuration nodes <code>DefaultFormatter</code> and <code>FormatterSettings</code>, which work exactly the same way as <code>DefaultHandler</code> and <code>HandlerSettings</code>. | An additional facet to configure is the formatting of the output. Well, at least in theory. There exist configuration nodes <code>DefaultFormatter</code> and <code>FormatterSettings</code>, which work exactly the same way as <code>DefaultHandler</code> and <code>HandlerSettings</code>. | ||
− | + | The [http://api.openoffice.org/docs/common/ref/com/sun/star/logging/PlainTextFormatter.html PlainTextFormatter] is the one used by default, and does not have any configuration options. There is also a [http://www.openoffice.org/api/docs/common/ref/com/sun/star/logging/CsvLogFormatter.html 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: [[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 15:20, 27 April 2022
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 )
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 ...)