.. index:: Logging

.. _enabling_verbose_logging:
.. _logging:

Logging
=======

DPBuddy always logs to the console/standard out. When used from Apache Ant, DPBuddy uses Ant logging, so you can use `Ant logging options <https://ant.apache.org/manual/running.html>`_ when running your Ant scripts.

In addition to the Ant log and the console, DPBuddy creates a log file using `logback <http://logback.qos.ch/>`_ logging framework. This logfile is configured in `logback.xml <http://logback.qos.ch/manual/configuration.html>`_ and it is separate from the Ant/console logging. In other words, DPBuddy logs to both the console and to the logfile set in "logback.xml". By default, "logback.xml" is set to non-verbose (INFO) level. You can easily switch it to the "DEBUG" (verbose) mode so that verbose output is captured for all DPBuddy commands in the logfile:

.. code-block:: xml

    <logger level="DEBUG" name="dpbuddy">
        <appender-ref ref="dpbuddylog"/>
    </logger>

Note that you will still see the regular (INFO) level of logging in the console/Ant log.

You can also disable logging to the file by deleting "dpbuddy" logger line in "logback.xml" (you can also set it to the "ERROR" level to restrict the output only to errors).

"logback.xml" is located in the "$DPBUDDY_HOME/conf" directory. In Ant, this directory needs to be explicitly added to the classpath of the DPBuddy's "taskdef":

.. code-block:: xml

    <taskdef uri="antlib:com.myarch.dpbuddy">
        <classpath>
            <pathelement location="${dpbuddy.home}/conf"/>
            <fileset dir="${dpbuddy.home}/lib" excludes="ant-*"/>
        </classpath>
    </taskdef>

By default, the log file is created in ``${user.home}/.dpbuddy/log`` directory (``/home/username/.dpbuddy/log`` on Linux or ``c:\Users\username\.dpbuddy\log`` on Windows). The name of the file is "dpbuddy.log". You can change the name and the location of the file, as well as its history/rollover policy in "logback.xml".

You can also override the location of all log files by defining ``DPBUDDY_LOG_HOME`` environment variable.

In verbose/debug mode, DPBuddy prints detailed debug information including SOAP/XML generated by DPBuddy and responses returned by DataPower.

To simplify the viewing of request/response XML, DPBuddy does not print Base64-encoded strings used by DataPower to transfer files.

To see verbose output in the console, provide the ``-v`` option to a DPBuddy command or to Ant, e.g.:

.. code-block:: bat

   dpbuddy import -file domain.zip -v

Note that ``-v`` does not affect the log level of the logfile mentioned earlier since it is controlled from "logback.xml".

In some cases, there might be a need to troubleshoot HTTPS connection and traffic between DPBuddy and DataPower. This can be enabled by ``dpbuddy.log.http`` property. Set this property to ``true`` and run DPBuddy in verbose mode.

You can also set `javax.net.debug <http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/ReadDebug.html>`_ system property if you need to troubleshoot SSL/TLS. This could be helpful if you use a custom SSL proxy profile for your XML management interface in DataPower.

To set this propery, simply add it to ``ANT_OPTS`` or ``DPBUDDY_OPTS``, e.g.:

.. code-block:: bat

   set ANT_OPTS=-Djavax.net.debug=ssl

To view results of :ref:`transformations <transform>` when running Ant in non-verbose mode, set ``dp.verbose.transform`` property to ``true``.