Activate tracing debugging in DiffKit

By default DiffKit emits a small amount of helpful information on stdout. But DiffKit is capable of producing very fine-grained tracing and debugging information that cover all aspect of operation. You might find this helpful for diagnosing some type of problem with DiffKit. Or you might simply want a better understanding of how DiffKit works. If you are a Java programmer and interested in learning about the internals of DiffKit, reading the "logs", configured for the appropriate logging level, is a very productive technique. The DiffKit logs are designed to be highly readable and they try to tell a story.

DiffKit uses the Open Source Logback Java framework to configure and control all logging. Logback is the official successor project to the ubiquitous log4j. In DiffKit, logback is configured by editing a file named "logback.xml", which is found in the "conf/" directory under the DiffKit home (DiffKit home is usually the directory where you unzipped the distribution zip file; it usually contains the diffkit-app.jar executable).

logback.xml

...
   <logger name="org.diffkit">
      <level value="warn" />
   </logger>

   <logger name="user" additivity="false">
      <level value="info" />
      <appender-ref ref="USER" />
   </logger>
...

DiffKit uses two tiers of logging information: "user" and "system". "User" log messages are intended for regular DiffKit users and represent typical operational information that is presented on your console (standard out, or stdout). The standard output you see when you invoke DiffKit comes from the "user" tier. The "system" tier of messages is targeted at engineers who need to trace or debug DiffKit internals in order to better understand what is going on. Each of these tiers has it’s own "domain" (entry) in the configuration file. The "system" tier is represented by this entry:

logback.xml

...
   <logger name="org.diffkit">
      <level value="warn" />
   </logger>
...

DiffKit adheres to the standard logging "level" conventions used by logback and log4j:

• trace: a crazy level of detail, only suitable for the deepest debugging.
• debug: high level of detail, useful for debugging, not suitable for day-to-day operations.
• info: a normal, conversational, level of information. Includes routine operational messages that help orient and inform the user about normal operating parameters and outcomes.
• warn: something that needs to be looked into. Represents an abnormal operating condition, but not necessarily fatal.
• error: something is totally broken, and things are probably not working, but there is some slim chance the program can still stagger on.
• fatal: game over.

As you can see from the logback.xml configuration file, DiffKit normally logs info level messages in the "user" tier, but only warn (or worse) level messages in the system tier. If you want to see what’s going on at the system level, you can do this:

logback.xml

...
   <logger name="org.diffkit">
      <level value="info" />
   </logger>
...

If you want a lot more information, you can do this:

logback.xml

...
   <logger name="org.diffkit">
      <level value="debug" />
   </logger>
...