# 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`

### 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.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.

Copyright © 2001 Apache Software Foundation. All rights Reserved.