Listeners & Loggers

Overview

Apache Ant has two related features to allow the build process to be monitored: listeners and loggers.

Listeners

A listener is alerted of the following events:

These are used internally for various recording and housekeeping operations, however new listeners may registered on the command line through the -listener argument.

Loggers

Loggers extend the capabilities of listeners and add the following features:

Built-in Listeners/Loggers

Classname Description Type
org.apache.tools.ant.DefaultLogger The logger used implicitly unless overridden with the -logger command-line switch. BuildLogger
org.apache.tools.ant.NoBannerLogger This logger omits output of empty target output. BuildLogger
org.apache.tools.ant.listener.MailLogger Extends DefaultLogger such that output is still generated the same, and when the build is finished an e-mail can be sent. BuildLogger
org.apache.tools.ant.listener.AnsiColorLogger Colorifies the build output. BuildLogger
org.apache.tools.ant.listener.Log4jListener Passes events to Apache Log4j for highly customizable logging.
Deprecated: Apache Log4j (1.x) is not developed any more. Last release is 1.2.17 from 26-May-2012 and contains vulnerability issues. 		BuildListener
org.apache.tools.ant.XmlLogger Writes the build information to an XML file. BuildLogger
org.apache.tools.ant.TimestampedLogger Prints the time that a build finished BuildLogger
org.apache.tools.ant.listener.BigProjectLogger Prints the project name every target BuildLogger
org.apache.tools.ant.listener.SimpleBigProjectLogger Prints the project name for subprojects only, otherwise like NoBannerLogger Since Ant 1.8.1 BuildLogger
org.apache.tools.ant.listener.ProfileLogger The default logger, with start times, end times and durations added for each task and target. BuildLogger

DefaultLogger

Simply run Ant normally, or:

ant -logger org.apache.tools.ant.DefaultLogger

NoBannerLogger

Removes output of empty target output.

ant -logger org.apache.tools.ant.NoBannerLogger

MailLogger

The MailLogger captures all output logged through DefaultLogger (standard Ant output) and will send success and failure messages to unique e-mail lists, with control for turning off success or failure messages individually.

Properties controlling the operation of MailLogger:

Property Description Required
MailLogger.mailhost Mail server to use No, default "localhost"
MailLogger.port SMTP Port for the Mail server No, default "25"
MailLogger.user user name for SMTP auth Yes, if SMTP auth is required on your SMTP server
the email message will be then sent using Mime and requires JavaMail
MailLogger.password password for SMTP auth Yes, if SMTP auth is required on your SMTP server
the email message will be then sent using Mime and requires JavaMail
MailLogger.ssl on or true if ssl is needed
This feature requires JavaMail		 no
MailLogger.from Mail "from" address Yes, if mail needs to be sent
MailLogger.replyto Mail "replyto" address(es), comma-separated No
MailLogger.failure.notify Send build failure e-mails? No, default "true"
MailLogger.success.notify Send build success e-mails? No, default "true"
MailLogger.failure.to Address(es) to send failure messages to, comma-separated Yes, if failure mail is to be sent
MailLogger.success.to Address(es) to send success messages to, comma-separated Yes, if success mail is to be sent
MailLogger.failure.cc Address(es) to send failure messages to carbon copy (cc), comma-separated No
MailLogger.success.cc Address(es) to send success messages to carbon copy (cc), comma-separated No
MailLogger.failure.bcc Address(es) to send failure messages to blind carbon copy (bcc), comma-separated No
MailLogger.success.bcc Address(es) to send success messages to blind carbon copy (bcc), comma-separated No
MailLogger.failure.subject Subject of failed build No, default "Build Failure"
MailLogger.success.subject Subject of successful build No, default "Build Success"
MailLogger.failure.body Fixed body of the email for a failed build. Since Ant 1.8.0 No, default is to send the full log output.
MailLogger.success.body Fixed body of the email for a successful build. Since Ant 1.8.0 No, default is to send the full log output.
MailLogger.mimeType MIME-Type of the message. Since Ant 1.8.0 No, default is text/plain
MailLogger.charset Character set of the message. Since Ant 1.8.0 No
MailLogger.starttls.enable on or true if STARTTLS should be supported (requires JavaMail). Since Ant 1.8.0 No, default is false
MailLogger.properties.file Filename of properties file that will override other values. No

ant -logger org.apache.tools.ant.listener.MailLogger

AnsiColorLogger

The AnsiColorLogger adds color to the standard Ant output by prefixing and suffixing ANSI color code escape sequences to it. It is just an extension of DefaultLogger and hence provides all features that DefaultLogger does.

AnsiColorLogger differentiates the output by assigning different colors depending upon the type of the message.

If used with the -logfile option, the output file will contain all the necessary escape codes to display the text in colorized mode when displayed in the console using applications like cat, more, etc.

This is designed to work on terminals that support ANSI color codes. It works on XTerm, ETerm, Win9x Console (with ANSI.SYS loaded.), etc.

NOTE: It doesn't work on WinNT and successors, even when a COMMAND.COM console loaded with ANSI.SYS is used.

If the user wishes to override the default colors with custom ones, a file containing zero or more of the custom color key-value pairs must be created. The recognized keys and their default values are shown below:

AnsiColorLogger.ERROR_COLOR=2;31
AnsiColorLogger.WARNING_COLOR=2;35
AnsiColorLogger.INFO_COLOR=2;36
AnsiColorLogger.VERBOSE_COLOR=2;32
AnsiColorLogger.DEBUG_COLOR=2;34

Each key takes as value a color combination defined as Attribute;Foreground;Background. In the above example, background value has not been used.

This file must be specified as the value of a system variable named ant.logger.defaults and passed as an argument using the -D option to the java command that invokes the Ant application. An easy way to achieve this is to add -Dant.logger.defaults= /path/to/your/file to the ANT_OPTS environment variable. Ant's launching script recognizes this flag and will pass it to the java command appropriately.

Format:

AnsiColorLogger.*=Attribute;Foreground;Background

Attribute is one of the following:
0 -> Reset All Attributes (return to normal mode)
1 -> Bright (Usually turns on BOLD)
2 -> Dim
3 -> Underline
5 -> link
7 -> Reverse
8 -> Hidden

Foreground is one of the following:
30 -> Black
31 -> Red
32 -> Green
33 -> Yellow
34 -> Blue
35 -> Magenta
36 -> Cyan
37 -> White

Background is one of the following:
40 -> Black
41 -> Red
42 -> Green
43 -> Yellow
44 -> Blue
45 -> Magenta
46 -> Cyan
47 -> White

ant -logger org.apache.tools.ant.listener.AnsiColorLogger

Log4jListener

Deprecated: Apache Log4j (1) is not developed any more. Last release is 1.2.17 from 26-May-2012 and contains vulnerability issues.

Passes build events to Log4j, using the full classname's of the generator of each build event as the category:

All start events are logged as INFO.  Finish events are either logged as INFO or ERROR depending on whether the build failed during that stage. Message events are logged according to their Ant logging level, mapping directly to a corresponding Log4j level.

ant -listener org.apache.tools.ant.listener.Log4jListener

To use Log4j you will need the Log4j JAR file and a 'log4j.properties' configuration file. Both should be placed somewhere in your Ant classpath. If the log4j.properties is in your project root folder you can add this with -lib option:

ant -listener org.apache.tools.ant.listener.Log4jListener -lib .

If, for example, you wanted to capture the same information output to the console by the DefaultLogger and send it to a file named 'build.log', you could use the following configuration:

log4j.rootLogger=ERROR, LogFile
log4j.logger.org.apache.tools.ant.Project=INFO
log4j.logger.org.apache.tools.ant.Target=INFO
log4j.logger.org.apache.tools.ant.taskdefs=INFO
log4j.logger.org.apache.tools.ant.taskdefs.Echo=WARN

log4j.appender.LogFile=org.apache.log4j.FileAppender
log4j.appender.LogFile.layout=org.apache.log4j.PatternLayout
log4j.appender.LogFile.layout.ConversionPattern=[%6r] %8c{1} : %m%n
log4j.appender.LogFile.file=build.log

For more information about configuring Log4J see its documentation page.

Using the Log4j 1.2 Bridge

You could use the Log4j Bridge if your application is written against the Log4j (1.x) API, but you want to use the Log4j 2.x runtime. For using the bridge with Ant you have to add to your classpath (e.g. via the -lib option). (For using the bridge Ant 1.9.10/1.10.2 or higher is required.) Translating the 1.x properties file into the 2.x xml syntax would result in 
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
  <Appenders>
    <File name="file" fileName="build.log">
      <PatternLayout>
        <Pattern>[%6r] %8c{1} : %m%n</Pattern>
      </PatternLayout>
    </File>
  </Appenders>
  <Loggers>
    <Root level="ERROR">
      <AppenderRef ref="file" level="DEBUG"/>
    </Root>
    <Logger name="org.apache.tools.ant.Project" level="INFO"/>
    <Logger name="org.apache.tools.ant.Project" level="INFO"/>
    <Logger name="org.apache.tools.ant.taskdefs" level="INFO"/>
    <Logger name="org.apache.tools.ant.taskdefs.Echo" level="WARN"/>
  </Loggers>
</Configuration>

XmlLogger

Writes all build information out to an XML file named log.xml, or the value of the XmlLogger.file property if present, when used as a listener. When used as a logger, it writes all output to either the console or to the value of -logfile. Whether used as a listener or logger, the output is not generated until the build is complete, as it buffers the information in order to provide timing information for task, targets, and the project.

By default the XML file creates a reference to an XSLT file "log.xsl" in the current directory; look in ANT_HOME/etc for one of these. You can set the property ant.XmlLogger.stylesheet.uri to provide a uri to a style sheet. this can be a relative or absolute file path, or an http URL. If you set the property to the empty string, "", no XSLT transform is declared at all.

ant -listener org.apache.tools.ant.XmlLogger
ant -logger org.apache.tools.ant.XmlLogger -verbose -logfile build_log.xml

TimestampedLogger

Acts like the default logger, except that the final success/failure message also includes the time that the build completed. For example: 

  BUILD SUCCESSFUL - at 16/08/05 16:24

To use this listener, use the command:

ant -logger org.apache.tools.ant.listener.TimestampedLogger

BigProjectLogger

This logger is designed to make examining the logs of a big build easier, especially those run under continuous integration tools. It

  1. When entering a child project, prints its name and directory
  2. When exiting a child project, prints its name
  3. Includes the name of the project when printing a target
  4. Omits logging the names of all targets that have no direct task output
  5. Includes the build finished timestamp of the TimeStamp logger

This is useful when using <subant> to build a large project from many smaller projects -the output shows which particular project is building. Here is an example in which "clean" is being called on all a number of child projects, only some of which perform work: 


======================================================================
Entering project "xunit"
In /home/ant/components/xunit
======================================================================

xunit.clean:
   [delete] Deleting directory /home/ant/components/xunit/build
   [delete] Deleting directory /home/ant/components/xunit/dist

======================================================================
Exiting project "xunit"
======================================================================

======================================================================
Entering project "junit"
In /home/ant/components/junit
======================================================================

======================================================================
Exiting project "junit"
======================================================================

The entry and exit messages are very verbose in this example, but in a big project compiling or testing many child components, the messages are reduced to becoming clear delimiters of where different projects are in charge -or more importantly, which project is failing.

To use this listener, use the command:

ant -logger org.apache.tools.ant.listener.BigProjectLogger

SimpleBigProjectLogger

Like BigProjectLogger, project-qualified target names are printed, useful for big builds with subprojects. Otherwise it is as quiet as NoBannerLogger:

Buildfile: /sources/myapp/build.xml

myapp-lib.compile:
Created dir: /sources/myapp/lib/build/classes
Compiling 1 source file to /sources/myapp/lib/build/classes

myapp-lib.jar:
Building jar: /sources/myapp/lib/build/lib.jar

myapp.compile:
Created dir: /sources/myapp/build/classes
Compiling 2 source files to /sources/myapp/build/classes

myapp.jar:
Building jar: /sources/myapp/build/myapp.jar

BUILD SUCCESSFUL
Total time: 1 second

since Ant 1.8.1

To use this listener, use the command:

ant -logger org.apache.tools.ant.listener.SimpleBigProjectLogger

ProfileLogger

This logger stores the time needed for executing a task, target and the whole build and prints these information. The output contains a timestamp when entering the build, target or task and a timestamp and the needed time when exiting.

since Ant 1.8.0

Example

Having that buildfile 
<project>
    <target name="aTarget">
        <echo>echo-task</echo>
        <zip destfile="my.zip">
            <fileset dir="${ant.home}"/>
        </zip>
    </target>
    <target name="anotherTarget" depends="aTarget">
        <echo>another-echo-task</echo>
    </target>
</project>
and executing with ant -logger org.apache.tools.ant.listener.ProfileLogger anotherTarget gives that output (with other timestamps and duration of course ;) : 
Buildfile: ...\build.xml

Target aTarget: started Thu Jan 22 09:01:00 CET 2009

echo: started Thu Jan 22 09:01:00 CET 2009
     [echo] echo-task

echo: finished Thu Jan 22 09:01:00 CET 2009 (250ms)

zip: started Thu Jan 22 09:01:00 CET 2009
      [zip] Building zip: ...\my.zip

zip: finished Thu Jan 22 09:01:01 CET 2009 (1313ms)

Target aTarget: finished Thu Jan 22 09:01:01 CET 2009 (1719ms)

Target anotherTarget: started Thu Jan 22 09:01:01 CET 2009

echo: started Thu Jan 22 09:01:01 CET 2009
     [echo] another-echo-task

echo: finished Thu Jan 22 09:01:01 CET 2009 (0ms)

Target anotherTarget: finished Thu Jan 22 09:01:01 CET 2009 (0ms)

BUILD SUCCESSFUL
Total time: 2 seconds

Writing your own

See the Build Events section for developers.

Notes: