Problem determination and log analysis

Introduction

The DITA-OT command-line tool has a logging method 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. By analyzing these messages, user can know what cause the problem and how to solve it. In the command-line tool the logger use is specified internally, so you do not need to specify it.

When running DITA-OT directly with Ant, different loggers provided by Ant can be used to get different log output. See Ant documentation for more information.

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:

Turn on debug mode

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 on, you need to follow the usage below:
  • Append -v and -Dargs.debug=yes in Ant command.
  • Append /d or /debug in command-line tool.

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.