Logging in DeltaXML Products
Introduction
Logging is being introduced primarily to assist DeltaXML support teams to diagnose problems that would be otherwise hard to identify or diagnose.
It has been designed so that by default users do not have to do anything differently and existing behaviour is maintained.
We are making use of the java.util.logging API in our code to add the logging information. This requires no new jar files for the end user unless they have specific requirements for a back-end logging destination or handler, beyond those provided by their Java runtime, application or other servers.
Logging configuration
Rather than follow the Logger-per-class pattern that is useful for developers we are grouping classing together and providing logging or 'Loggers' for different areas of functionality in our products, while still using the dot-separated hierarchical naming scheme. We will refer to these as 'Loggers'.
The current list of Loggers is:
com.deltaxml.logging.resolvers- internal entity and URI resolution and delegation to catalog systems and/or user provided resolvers
Other Loggers will be added in future to meet internal debug and customer support demands.
It is possible to configure the Loggers individually by controlling their level. java.util.logging provides the following ordered levels: FINEST, FINER, FINE, CONFIG, INFO, WARNING, SEVERE
Setting a low level, such as FINER means that log messages at the higher levels are also reported. There are also the OFF and ALL meta levels with their obvious meanings.
Here is some guidance as to how we use these levels:
INFO: we will use this when unexpected events happen. This is the default configured JRE level.CONFIG: we will report API and pipeline configuration at this level.FINE: we will use this level for per filter, per pipeline, per comparison type information.FINER/FINEST: these two levels will be used for multiple logging events per comparison operation, for example for each general entity or external URL resolution, or when a specific element is found in an input to a comparison.
Configuration examples
Logging configuration depends very much on the environment in which DeltaXML software is being run, such as the command-line or a servlet system or application server. Logging configuration is something that a system administrator should be familiar with; we will not go into details other than provide a command-line example and some online resources.
Configuration on the command line can be achieved using a Java properties file called 'logging.properties'. The following example contents can be used to configure FINER logging on "resolvers":
Finer logging example
handlers = java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level = ALL
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
com.deltaxml.logging.resolver.level = FINERTo invoke the command-line driver, to use this properties file another system property is used. The following example also uses a system property to configure catalog support in the DeltaXML Core command line driver (command.jar):
Command line use of properties
java -Djava.util.logging.config.file=/Users/nigelw/logging.properties
-Dxml.catalog.files=/Users/nigelw/dita/dtd/1.1/catalog-dita.xml
-jar command.jar compare diffreport ~/f1.dita ~/f2.dita result.ditaConfiguration resources
Other configuration techniques are possible including adding logging.properties to your classpath, editing the system/JRE property file or writing configuration code in Java. Please see:
For logging configuration in Apache Tomcat please see:
Tomcat and other systems have support for java.util.logging. If your system does not, and only supports log4j for example, consider using the jul-to-slf4j bridge:
We would suggest that the performance issues in the documentation would not normally be a problem for our logging use. If you do find a severe performance penalty please let us know; it will shape future product plans.