Listeners & Loggers

Overview

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:

build started
build finished
target started
target finished
task started
task finished
message logged

Loggers

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

Receives a handle to the standard output and error print streams and therefore can log information to the console or the -logfile specified file.
Logging level (-quiet, -verbose, -debug) aware
Emacs-mode aware

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.Log4jListener`	Passes events to Log4j for highly customizable logging.	BuildListener
`org.apache.tools.ant.XmlLogger`	Writes the build information to an XML file.	BuildListener

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

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.from	Mail "from" address	Yes, if mail needs to be sent
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.subject	Subject of failed build	No, default "Build Failure"
MailLogger.success.subject	Subject of successful build	No, default "Build Success"
MailLogger.properties.file	Filename of properties file that will override other values.	No

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

Log4jListener

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

build started / build finished - org.apache.tools.ant.Project
target started / target finished - org.apache.tools.ant.Target
task started / task finished - the fully qualified classname of the task
message logged - the classname of one of the above, so if a task logs a message, its classname is the category used, and so on.

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

XmlLogger

Writes all build information out to an XML file named log.xml, or the value of the XmlLogger.file property if present.

ant -listener org.apache.tools.ant.XmlLogger

Writing your own

See the Build Events section for developers.

Notes:

A listener or logger should not write to standard output or error - Ant captures these internally and may cause an infinite loop.