Problem determination and log analysis

Introduction

In the DITA Open Toolkit 1.2 or above, a new logging method is supported to log messages both on the screen and into the log file. The messages on the screen present user with the status information, warning, error, and fatal error messages. The messages in the log file present user with more detailed information about the transformation process. By analyzing these messages, user can know what cause the problem and how to solve it.

The logging method is based on Ant's Logger & Listener interface. By default, this logging method is disabled, and all the messages occur on the screen just like previous releases.

To start this new logging method, you need to follow the usage below:
  • In Ant command, specify the logger by appending -logger org.dita.dost.log.DITAOTBuildLogger in the command parameters, for example:
    ant sample.web -logger org.dita.dost.log.DITAOTBuildLogger
            
  • In Java command, the logger is specified internally, so you do not need to specify it again.

Analyze messages on the screen

During the building process, some information or messages occur on the screen to tell you about the status, warnings, errors, or fatal errors. You need to analyze the messages to solve the problems.
  • If the build succeeded with some warning messages on the screen, it means that there are something incorrect within the user input parameters or source DITA files; but you can still get the correct output.
  • If the build succeeded with some error messages on the screen, it means that there are something incorrect within the user input parameters or source DITA files; the output maybe not correct.
  • If the build failed with fatal error message on the screen, it means that there are something illegal or invalid within the user input parameters or source DITA files; you may get no output, or wrong output.

Analyze messages in the log file

A log file in plain text format is generated in the log directory, which has a name combined with both input file name and transform type. You can open it and find more detailed information, which are helpful for solving problems. You can use the same way introduced above to analyze the messages and solve the problems.

The log directory can be specified by using the parameter /logdir:{args.logdir} for the output options.

Note: In some cases, there would be no log file generated:
  • You have entered an invalid Ant command or Java command to start the toolkit.
  • The log file with the same name in the same directory exists and can not be deleted.

Turn on debug mode

Debug mode is supported along with the new logging method. Under debug mode, diagnostic information, such as: environment variables, stack trace, will be logged into the log file. These information can help the user or developer to go deep into the problems and find the root cause.

By default, the debug mode is disabled. To turn on the debug mode, you need to follow the usage below:
  • Append -d or -debug in Ant command.
  • Append /d or /debug in Java command.

About message file

The message file is used to store the detailed log messages, these messages are read dynamically from this file. To ensure those messages can be read correctly during the transform process, the message file should be located properly. In some situations, the toolkit may fails to load the message file due to some exceptions thrown. Please refer to Troubleshooting for detailed information.

For high level users and developers, there is a property args.message.file in the toolkit's ant script, it is used to config the message file, you can override it in your ant script.

Note: Due to the difference of underly implementation between Java, And, and XSL, the property args.message.file is only useful for Java and Ant; To keep the normal function of log handling, you still need to ensure there are files 'resource/messages.xml' and 'resource/messages.dtd' both in the toolkit's root directory and in the directory that you run the toolkit.