Listeners & LoggersOverviewApache Ant has two related features to allow the build process to be monitored:listeners and loggers. ListenersA listener is alerted of the following events: - build started
- build finished
- target started
- target finished
- task started
- task finished
- message logged
These are used internally for various recording and housekeeping operations, however new listeners may registered on the command line through the -listener argument. LoggersLoggers 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/LoggersDefaultLoggerSimply run Ant normally, or: ant -logger org.apache.tools.ant.DefaultLogger
NoBannerLoggerRemoves output of empty target output. ant -logger org.apache.tools.ant.NoBannerLogger
MailLoggerThe MailLogger captures all output logged through DefaultLogger (standard Antoutput) and will send success and failure messages to unique e-mail lists, withcontrol 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.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
AnsiColorLoggerThe AnsiColorLogger adds color to the standard Ant outputby prefixing and suffixing ANSI color code escape sequences toit. It is just an extension of DefaultLoggerand hence provides all features that DefaultLogger does. AnsiColorLogger differentiates the output by assigningdifferent colors depending upon the type of the message. If used with the -logfile option, the output filewill contain all the necessary escape codes todisplay the text in colorized mode when displayedin the console using applications like cat, more, etc. This is designed to work on terminals that support ANSIcolor 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 withANSI.SYS is used. If the user wishes to override the default colorswith custom ones, a file containing zero or more of thecustom color key-value pairs must be created. The recognized keysand their default values are shown below: AnsiColorLogger.ERROR_COLOR=2;31AnsiColorLogger.WARNING_COLOR=2;35AnsiColorLogger.INFO_COLOR=2;36AnsiColorLogger.VERBOSE_COLOR=2;32AnsiColorLogger.DEBUG_COLOR=2;34
Each key takes as value a color combination defined asAttribute;Foreground;Background. In the above example, backgroundvalue has not been used. This file must be specfied as the value of a system variablenamed ant.logger.defaults and passed as an argument using the -Doption 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 tothe java command appropriately. Format: AnsiColorLogger.*=Attribute;Foreground;BackgroundAttribute is one of the following:0 -> Reset All Attributes (return to normal mode)1 -> Bright (Usually turns on BOLD)2 -> Dim3 -> Underline5 -> link7 -> Reverse8 -> HiddenForeground is one of the following:30 -> Black31 -> Red32 -> Green33 -> Yellow34 -> Blue35 -> Magenta36 -> Cyan37 -> WhiteBackground is one of the following:40 -> Black41 -> Red42 -> Green43 -> Yellow44 -> Blue45 -> Magenta46 -> Cyan47 -> White ant -logger org.apache.tools.ant.listener.AnsiColorLogger
Log4jListenerPasses build events to Log4j, using the full classname's of the generator ofeach 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 asINFO or ERROR depending on whether the build failed during that stage. Messageevents are logged according to their Ant logging level, mapping directly to acorresponding 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 Antclasspath. If the log4j.properties is in your project root folder you canadd 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 theconsole by the DefaultLogger and send it to a file named 'build.log', youcould use the following configuration: log4j.rootLogger=ERROR, LogFilelog4j.logger.org.apache.tools.ant.Project=INFOlog4j.logger.org.apache.tools.ant.Target=INFOlog4j.logger.org.apache.tools.ant.taskdefs=INFOlog4j.logger.org.apache.tools.ant.taskdefs.Echo=WARNlog4j.appender.LogFile=org.apache.log4j.FileAppenderlog4j.appender.LogFile.layout=org.apache.log4j.PatternLayoutlog4j.appender.LogFile.layout.ConversionPattern=[%6r] %8c{1} : %m%nlog4j.appender.LogFile.file=build.log
For more information about configuring Log4J see itsdocumentation page. XmlLoggerWrites all build information out to an XML file named log.xml, or the valueof the XmlLogger.file property if present, when used as alistener. When used as a logger, it writes all output to either theconsole or to the value of -logfile . Whether used as a listeneror logger, the output is not generated until the build is complete, as itbuffers 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 propertyant.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 transformis 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 - When entering a child project, prints its name and directory
- When exiting a child project, prints its name
- Includes the name of the project when printing a target
- Omits logging the names of all targets that have no direct task output
- 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
SimpleBigProjectLoggerLike BigProjectLogger , project-qualified target names are printed,useful for big builds with subprojects.Otherwise it is as quiet as NoBannerLogger : Buildfile: /sources/myapp/build.xmlmyapp-lib.compile:Created dir: /sources/myapp/lib/build/classesCompiling 1 source file to /sources/myapp/lib/build/classesmyapp-lib.jar:Building jar: /sources/myapp/lib/build/lib.jarmyapp.compile:Created dir: /sources/myapp/build/classesCompiling 2 source files to /sources/myapp/build/classesmyapp.jar:Building jar: /sources/myapp/build/myapp.jarBUILD SUCCESSFULTotal time: 1 second since Ant 1.8.1 To use this listener, use the command: ant -logger org.apache.tools.ant.listener.SimpleBigProjectLogger
ProfileLoggerThis logger stores the time needed for executing a task, target and the whole build and printsthese 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 ExampleHaving 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: ...uild.xmlTarget aTarget: started Thu Jan 22 09:01:00 CET 2009echo: started Thu Jan 22 09:01:00 CET 2009 [echo] echo-taskecho: finished Thu Jan 22 09:01:00 CET 2009 (250ms)zip: started Thu Jan 22 09:01:00 CET 2009 [zip] Building zip: ...my.zipzip: 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 2009echo: started Thu Jan 22 09:01:01 CET 2009 [echo] another-echo-taskecho: finished Thu Jan 22 09:01:01 CET 2009 (0ms)Target anotherTarget: finished Thu Jan 22 09:01:01 CET 2009 (0ms)BUILD SUCCESSFULTotal time: 2 seconds Writing your ownSee the Build Events section fordevelopers. Notes: - A listener or logger should not write to standard output or error in the
messageLogged() method ; Ant captures these internally and it will trigger an infinite loop. - Logging is synchronous; all listeners and loggers are called one after the other, with the build blocking until the output is processed. Slow logging means a slow build.
- When a build is started, and
BuildListener.buildStarted(BuildEvent event) is called, the project is not fully functional. The build has started, yes, and the event.getProject() method call returns the Project instance, but that project is initialized with JVM and ant properties, nor has it parsed the build file yet. You cannot call Project.getProperty() for property lookup, or Project.getName() to get the project name (it will return null). - Classes that implement
org.apache.tools.ant.SubBuildListener receive notifications when child projects start and stop. |