1011641270 / automon

Automon combines the power of AOP (AspectJ) with monitoring or logging tools you already use to declaratively monitor your Java code, the JDK, and 3rd party libraries.

Automon

Automon combines the power of AOP (AspectJ) with monitoring tools (JAMon, JavaSimon, Yammer Metrics, StatsD, ...) or logging tools (perf4j, log4j, sl4j, ...) that you already use to declaratively monitor the following:

• Your Java code,
• The JDK,
• Any jars used by your application

Automon is typically used to track method invocation time, and exception counts. It is very easy to set-up and you should be able to start monitoring your code within minutes. The data will be stored and displayed using the monitoring tool of your choice. The following image shows the type of data Automon collects (The example below displays the data in JAMon, however the data can be displayed in whatever monitoring tool/api you choose. For example here is same data displayed in grahphite/StatsD).

The following is a sample command that will monitor your program with Automon (in this case using JAMon):

• java -Dorg.aspectj.weaver.loadtime.configuration=file:aop.xml -javaagent:aspectjweaver.jar -classpath automon-{version}.jar:myapplication.jar:jamon-2.81.jar com.mypackage.MyClass
• Running with Yammer Metrics, StatsD, JavaSimon etc. you would simply use their respective jars instead of the JAMon jar
• aop.xml (AspectJ file) is where you define what parts of your program you want monitored (through 'pointcuts'). It is often quite simple.
  • Here is a sample pointcut monitoring all methods in all classes in package 'com.stevesouza': <pointcut name="profile" expression="within(com.stevesouza..*)"/>
  • And a full AOP config file Example monitoring JDK classes (JDBC, IO, Net packages), and custom classes:
• aspectjweaver.jar is required for AspectJ to monitor the code.

See 'Getting Started' below and examples for instructions on how to run Automon with CodaHale/Yammer Metrics, JavaSimon, NewRelic, StatsD, Tomcat and Jetty.

It is important to note that Automon is complimentary to monitoring and logging tools. Automon performs no monitoring on its own. It serves as a bridge between AspectJ (AspectJ defines 'what to monitor') and monitoring and logging tools (which define 'how to monitor'). You can also easily provide your own monitoring tool by implementing the simple OpenMon interface.

The following diagram shows an AspectJ pointcut that will monitor all methods (any return type, any number of arguments) in the 'com.mycompany' package as well as its subpackages (..) using your monitoring tool of choice.

Automon requires jdk 1.5 or higher.

And finally, Automon can be dynamically enabled/disabled via the Automon MXBean (JMX).

AspectJ Weaving

AspectJ 'weaves' Automon monitoring code into your classes. This can be done...

• at runtime with the Load Time Weaver (LTW)
• at build time with the Build Time Weaver (BTW).

Both approaches replace the original class files with ones that have monitoring added to them. Regardless of whether LTW, or BTW is used the generated class files are identical. LTW is more flexible as it lets you use the powerful AspectJ pointcut language at runtime to specify what classes you want to monitor.

Here is a short video that shows how to monitor your code using Automon with LTW: Automon demo

Getting Started

The quickest way to get started with Automon is to download this distribution, and go to the examples directory and run the sample programs (*.sh). There are more directions on running the examples in the 'examples' directories README file.

If you are using Spring the following maven module shows how to monitor Spring beans with Automon. In particular look at the Spring applicationContext.xml file to see how to specify which Spring beans to monitor.

Automon does not require Spring though. Running a non-Spring program with Automon is easy too. You simply...

• Put automon-{version}.jar in your classpath,
• And make either aspectjweaver.jar (LTW), or aspectjrt.jar (BTW) available.

The examples directory shows how to invoke your programs using both LTW, and BTW.

Load Time Weaving (LTW) also involves providing an ajc-aop.xml config file. Review the config files for more information on them. The following maven projects generate plain (unwoven) java jars. Each of them has a *.sh script in the examples directory that lets you run the the java code with LTW.

• helloworld_unwoven_jamon - A simple program monitored with Jamon. If you pass a command line argument to run the program in a loop the program will run long enough that you can look at the Jamon metrics MBeans in the Jconsole.
• unwoven_jdk - A simple program that when used with LTW will monitor Java IO, Http requests, and JDBC calls.
• webapp_unwoven - A web application (war) that can be installed in a web container like Tomcat or Jetty. It monitors calls to the jdk (jdbc, io, and http requests) and custom classes. See README.md for more information.

Build Time Weaving (BTW) - And finally if you want to use Build Time Weaving in your maven build process refer to these BTW sample projects (In the examples I use 'woven' and BTW synonymously):

• helloworld_woven - A simple project that has a dependency on Automon and a simple jar that contains a HelloWorld application. The output of this project is a jar that contains AspectJ BTW woven code.
• spring_woven - This project shows how you can weave a Spring project at build time.

The examples directory has scripts (*.sh) to run these programs.

An interview that covers Automon can be found here.

Maven

Incorporate Automon into your maven project by adding the following dependency (using the most current version).

      <dependency>
          <groupId>org.automon</groupId>
          <artifactId>automon</artifactId>
          <version>1.0.2</version>
      </dependency>

Automon Source Code

The code that generates the automon-{version}.jar file is contained in this directory.

Support

And finally, if you need support contact us at Issues or email us at [email protected].

Thanks, and happy monitoring!

Steve