146 lines
8.7 KiB
XML
146 lines
8.7 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
|
|
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
|
|
<concept id="loghandling">
|
|
<title>Logging build information</title>
|
|
<titlealts>
|
|
<navtitle>Logging</navtitle>
|
|
</titlealts>
|
|
<shortdesc>When you run DITA-OT, key information is logged on the screen. This information can also be written to a
|
|
log file. If you encounter a problem, you can analyze this information to determine the source of the problem and
|
|
then take action to resolve it.</shortdesc>
|
|
<prolog>
|
|
<metadata>
|
|
<keywords>
|
|
<indexterm>Apache FOP
|
|
<indexterm>log files</indexterm></indexterm>
|
|
<indexterm><cmdname>dita</cmdname> command
|
|
<indexterm>logging</indexterm></indexterm>
|
|
<indexterm>logging</indexterm>
|
|
<indexterm>verbose logging</indexterm>
|
|
<indexterm>Ant
|
|
<indexterm>logging</indexterm></indexterm>
|
|
<indexterm>debugging
|
|
<index-see-also>logging</index-see-also></indexterm>
|
|
<indexterm>Java
|
|
<indexterm>logging</indexterm></indexterm>
|
|
</keywords>
|
|
</metadata>
|
|
</prolog>
|
|
<conbody>
|
|
<p>The logging behavior varies depending on whether you use the <cmdname>dita</cmdname> command or Ant to invoke a
|
|
toolkit build.</p>
|
|
<dl>
|
|
<dlentry>
|
|
<dt><cmdname>dita</cmdname> command</dt>
|
|
<dd>
|
|
<p>By default, only warning and error messages are written to the screen.</p>
|
|
<ul>
|
|
<li>
|
|
<p>For more information, enable verbose logging with <cmdname>dita</cmdname>
|
|
<parmname>--verbose</parmname>.</p>
|
|
<p>Verbose logging prints additional information to the console, including directory settings, effective
|
|
values for Ant properties, input/output files, and informational messages to assist in
|
|
troubleshooting.</p></li>
|
|
<li>
|
|
<p>To enable debug logging, use <cmdname>dita</cmdname>
|
|
<parmname>--debug</parmname>.</p>
|
|
<p>Debug logging prints considerably more additional information. The debug log includes all information
|
|
from the verbose log, plus details on Java classes, additional Ant properties and overrides,
|
|
preprocessing filters, parameters, and stages, and the complete build sequence.</p>
|
|
<note type="attention">Debug logging requires additional resources and can slow down the build process, so
|
|
it should only be enabled when further details are required to diagnose problems.</note>
|
|
</li>
|
|
<li>
|
|
<p>To write the log to a file, use <cmdname>dita</cmdname>
|
|
<parmname>--logfile</parmname>=<varname>file</varname> and specify the path to the log file.</p>
|
|
<p>Unless an absolute path is specified, the value will be interpreted relative to the current
|
|
directory.</p></li>
|
|
</ul></dd>
|
|
</dlentry>
|
|
<dlentry>
|
|
<dt>Ant</dt>
|
|
<dd>By default, status information is written to the screen. If you issue the <parmname>-l</parmname> parameter,
|
|
the build runs silently and the information is written to a log file with the name and location that you
|
|
specified.</dd>
|
|
</dlentry>
|
|
</dl>
|
|
<section>
|
|
<title>Using other Ant loggers</title>
|
|
<p>You also can use other Ant loggers; see
|
|
<xref href="https://ant.apache.org/manual/listeners.html" format="html" scope="external">Listeners &
|
|
Loggers</xref> in the Ant documentation for more information.</p>
|
|
<p>For example, you can use the <b>AnsiColorLogger</b> to colorize the messages written on the screen.</p>
|
|
<dl>
|
|
<dlentry>
|
|
<dt><cmdname>dita</cmdname> command</dt>
|
|
<dd>
|
|
<p>To use a custom Ant logger with the <cmdname>dita</cmdname> command, add the logger to the
|
|
<codeph>ANT_ARGS</codeph> environment variable by calling the following command before calling the
|
|
<cmdname>dita</cmdname> command:</p>
|
|
<codeblock
|
|
outputclass="syntax-bash"
|
|
>export ANT_ARGS="-logger org.apache.tools.ant.listener.AnsiColorLogger"</codeblock>
|
|
<p>Now you will get colorized messages when the <cmdname>dita</cmdname> command runs.</p>
|
|
<note type="tip">Environment variables can also be set permanently. See
|
|
<xref href="https://www.java.com/en/download/help/path.xml" format="html" scope="external">How do I set or
|
|
change the PATH system variable?</xref> for information on how to set the
|
|
<xref keyref="PATH"/>. You can set the <codeph>ANT_ARGS</codeph> environment variable in the same
|
|
way.</note>
|
|
</dd>
|
|
</dlentry>
|
|
<dlentry>
|
|
<dt>Ant</dt>
|
|
<dd>
|
|
<p>If you prefer to launch DITA-OT directly from Ant, you can also add the logger to the
|
|
<codeph>ANT_ARGS</codeph> environment variable, as explained above. You can also set the logger with the
|
|
<codeph>-logger</codeph> parameter when calling Ant.</p>
|
|
<codeblock outputclass="syntax-bash">ant -logger org.apache.tools.ant.listener.AnsiColorLogger</codeblock>
|
|
</dd>
|
|
</dlentry>
|
|
</dl>
|
|
</section>
|
|
<section>
|
|
<title>FOP debug logging</title>
|
|
<indexterm>logback.xml</indexterm>
|
|
<indexterm>classpath
|
|
<indexterm>logging</indexterm></indexterm>
|
|
<p>In PDF processing with <tm trademark="Apache" tmtype="tm">Apache</tm> FOP, DITA-OT uses the Simple Logging
|
|
Facade for Java (SLF4J) for better control and formatting of FOP log messages. To reduce noise on the console,
|
|
all FOP messages are set to the Info level and hidden by default.</p>
|
|
<p>To enable debug logging, modify the <filepath>config/logback.xml</filepath> file or add your own
|
|
<filepath>logback.xml</filepath> to the classpath with a higher priority to override the default settings. For
|
|
more information, see the
|
|
<xref href="https://logback.qos.ch/manual/configuration.html" format="html" scope="external">Logback
|
|
configuration documentation</xref>.</p>
|
|
<note type="attention">Enabling FOP debug logging will dramatically increase the size of generated log
|
|
files.</note>
|
|
</section>
|
|
<!--<section><title>Analyze messages on the screen</title><p>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. <ul>
|
|
<li>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.</li>
|
|
<li>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.</li>
|
|
<li>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.</li>
|
|
</ul>
|
|
</p></section>-->
|
|
<!--<section><title>Analyze messages in the log file</title><p>A log file in plain text format is generated in the log
|
|
directory, which has a name combined with both input file name and transformation 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.</p><p>The log directory can be specified by:</p><ul>
|
|
<li>using Ant, with argument <codeph>-logfile=<userinput>log-file</userinput></codeph></li>
|
|
<li>using command-line tool, the parameter <codeph>/logdir:<userinput>log-dir</userinput></codeph>.</li>
|
|
</ul></section>-->
|
|
<!--<section><title>Turn on debug mode</title><p>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.</p><p>By default, the debug mode is disabled. To turn on the
|
|
debug mode on, you need to follow the usage below: <ul>
|
|
<li>Append <codeph>-v</codeph> and <codeph>-Dargs.debug=yes</codeph> in Ant command.</li>
|
|
<li>Append <codeph>/d</codeph> or <codeph>/debug</codeph> in command-line tool.</li>
|
|
</ul></p></section>-->
|
|
</conbody>
|
|
</concept>
|