The answer to this question depends the actual logging system you use. Log4Ant supports Mapped Diagnostic Contexts(MDC) and lets you select what properties, variables, and references (as strings) you’d like passed from the Ant context for every emitted event or for a particular event. If you use a logging system like Log4J, or Logback, or another SLF4J aware system that understands MDCs you can get this information easily by using the proper layout pattern to extract MDC elements for your logging system.

The rest of this guide describes how you can include custom information into the logged event’s MDC. Log4Ant also supports a small standard set of properties that it includes with all events; this information is described in the related tip: How do I get the Ant script location in messages?

The easiest way to tell Log4Ant what fixture you want included in every emitted event’s MDC, is to define an emit configuration data object (<emit:configuration>) that you later reference from each emit call or install as the default configuration for the current thread where Log4Ant can pick it up automatically.

The following snippet shows an emit configuration “tests.logconf” that will include two variables ‘step’ and ‘rag’ and all properties in the ‘tests.diagnosis’ property set as part of the MDC. Note that you still have to extract this information according to the rules of your specific logging system, but Log4Ant ensures the information is actually available for you to read. The snippet also shows how you might install the configuration for the duration of a target.

<propertyset id="tests.diagnosis">
  <propertyref name="deployer"/>
  ...
</propertyset>
 
<emit:configuration id="tests.logconf">
  <include variable="step"/>
  <include variable="rag"/>
  <include propertyset="tests.diagnosis"/>
</emit:configuration>
...
<target name="deploytests">
  <emit:overlay configuration="tests.logconf">
     <emit:show messageid="LF.tests.start".../>
     ...

To extract the included properties you need to specify the MDC related pattern for your logging system. For Logback, the conversion pattern selector is ‘%X’ or ‘%mdc’. One setup to extract the ‘step’ and other properties named above might look like:

<appender name="DEPLOY_ARCHIVE_MONITOR"
  class="ch.qos.logback.core.FileAppender">
  <layout class="ch.qos.logback.classic.PatternLayout">
    <Pattern>[%X{rag}] [%d{ISO8601}] %X{step} - %m%n</Pattern>
  </layout>
  <File>/staging/deploy/.../deploy.log</File>
</appender>

To produce output like:

[G] [2008-12-16 19:49:42,155] activate-admin - Starting
[G] [2008-12-16 19:52:17,123] activate-admin - Loading cluster addresses
[G] [2008-12-16 19:52:49,467] activate-admin - Version sanity check
...

Sometimes you want to change the information sent with a single event only. With Log4Ant you can specify the fixture elements you want included in the MDC for a specific emit event by defining one or more <include> instructions in the emit event declaration like you do for the configuration data type. The example below defines an emit event that will include the “last.error” variable as a string (the exception message). Note that this specific information is in addition to any configuration linked with the current execution thread or enclosing taskset (as setup in the preceding example).

<iferror failvariable="last.error">
  <emit:show messageid="E.something.failed" level="error">
     <include variable="last.error"/>
  </emit:show>
</iferror>

To display the Java exception as part of the logged information (including partial stack information if requested in your layout pattern) you can define the special ‘thrown’ include filter as shown in the example below. Note you have to have a Java exception stored behind the reference named by the ‘thrown’ parameter. The AntXtras <protect> taskset with its inner <iferror> helper can do this.

<iferror capturethrown="last.error">
  <emit:show messageid="E.something.failed" level="error">
     <include thrown="last.error"/>
  </emit:show>
</iferror>

And just like the general configuration, you still need to extract the included properties using the MDC related setup for your logging system. For Logback, the conversion pattern selector is ‘%X’ or ‘%mdc’. One setup to extract the ‘last.error’ captured above might be:

<evaluator name="UNINTERESTING">
  <Expression>throwable == null || !(throwable instanceof
    org.apache.tools.ant.BuildException)</Expression>
</evaluator>
<appender name="DEPLOY_ISSUES_MONITOR"
  class="ch.qos.logback.classic.net.SMTPAppender">
  <layout class="ch.qos.logback.classic.PatternLayout">
    <Pattern>[%X{rag}] %X{step} - %m %ex{3,UNINTERESTING}%n</Pattern>
  </layout>
  ...
</appender>

To produce output like below in the event of an Ant-related exception (only):

[R] launch-mars-probe - Unable to load landing coordinates!!!
org.apache.tools.ant.BuildException: Houston we have a problem...
  at org.acmesoft.launcher.verifyIsMetric(LaunchTask.java:266)
  at org.acmesoft.launcher.execute(LaunchTask.java:373)
  at org.apache.tools.ant.UnknownElement.execute(UnknownElement.java:288)

• If Log4Ant cannot determine a value for the fixture element you’ve defined, it will install the underlying Ant or AntXtras response as-is; for instance, if you ask Log4Ant to include the value of a property that is not defined, Log4Ant will omit that property from the MDC map because Ant returns a null for that property.
  
  
• Log4Ant only includes custom MDC properties for the <emit:show> task; it does not apply custom properties to either the <emit:checkpoint> or the <emit:capturelogs> components as both of these are very specific and restrictive in what information they provide.

• How do I get the Ant script location in messages?