Let's get to the code

How to integrate MoSKito into your code and your environment

Welcome to the integration reference page. This page will provide you with integration option for different type of applications, integration via AOP which is suitable for almost everyone, CDI - for JEE Containers, Spring for ... yes Spring, and also some other integration option. We will round this up with the integration manual for the MoSKito Inspect Web Application.

If you prefer step by step integration instructions, we recommend you to visit our blog series: The complete MoSKito integration guide: step by step.

AOP

One of the easiest way to integrate MoSKito into your code is to use AOP with AspectJ. You need three steps:

<properties>
    <moskito.version>2.5.5</moskito.version>
</properties>
<dependency>
    <groupId>net.anotheria</groupId>
    <artifactId>moskito-core</artifactId>
    <version>${moskito.version}</version>
</dependency>
<dependency>
    <groupId>net.anotheria</groupId>
    <artifactId>moskito-aop</artifactId>
    <version>${moskito.version}</version>
</dependency>
<plugins>
    <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>aspectj-maven-plugin</artifactId>
        <version>1.4</version>
        <configuration>
            <aspectLibraries>
                <aspectLibrary>
                    <groupId>net.anotheria</groupId>
                    <artifactId>moskito-aop</artifactId>
                </aspectLibrary>
            </aspectLibraries>
            <source>1.6</source>
            <target>1.6</target>
        </configuration>
        <executions>
            <execution>
                <goals>
                    <goal>compile</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
</plugins>
//simply add @Monitor to any class you want to monitor
@Monitor
public class MonitoredClass {
    public void firstMethod() {
        //do something
    }

    public void secondMethod() {
        //do something else
    }

//you can also exclude methods from monitoring:
    @DontMonitor
    public void doNotMonitorMe() {

    }

//or you can just monitor one or multiple methods:
public class ClassWithMonitoredMethod {
    @Monitor
    public void firstMethod() {
        //do something
    }

Check out MoSKito examples, AOP Module on GitHub and Guide on Annotations for more information.

CDI (JBoss, Glassfish)

If you want to use MoSKito in JEE Environment or simply in context of JSR-299, MoSKito CDI support is the way to go.

<properties>
    <moskito.version>2.5.5</moskito.version>
</properties>
<dependency>
    <groupId>net.anotheria</groupId>
    <artifactId>moskito-core</artifactId>
    <version>${moskito.version}</version>
</dependency>
<dependency>
    <groupId>net.anotheria</groupId>
    <artifactId>moskito-cdi</artifactId>
    <version>${moskito.version}</version>
</dependency>
//simply add @Monitor to any CDI managed bean
@Monitor
public class MonitoredClass {
    public void firstMethod(){
        //do something
    }

    public void secondMethod(){
        //do something else
    }

//you can also exclude methods from monitoring:
    @DontMonitor
    public void doNotMonitorMe(){

    }

//or you can just monitor one or multiple methods:
public class ClassWithMonitoredMethod {
    @Monitor
    public void firstMethod(){
        //do something
}
<beans xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
    http://java.sun.com/xml/ns/javaee
    http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
    <interceptors>
        <class>net.anotheria.moskito.integration.cdi.CountInterceptor</class>
        <class>net.anotheria.moskito.integration.cdi.CallInterceptor</class>

        <!-- add those to be able to mark a category or subsystem -->
        <class>net.anotheria.moskito.integration.cdi.WebCallInterceptor<class>
        <class>net.anotheria.moskito.integration.cdi.ServiceCallInterceptor</class>
        <class>net.anotheria.moskito.integration.cdi.DaoCallInterceptor</class>
    </interceptors>
</beans>

Check out MoSKito JBoss example project on GitHub and Guide on Annotations for more information.

Javaagent

MoSKito comes with 2 Javaagents, a light version for quick fixes and a full blown javaagent with all features similar to the AOP. The later is yet BETA (as of 2.8.4). The javaagents can be downloaded from the moskito download page. Alternatively you can build them yourself from github sources here: https://github.com/anotheria/moskito-javaagent and here: https://github.com/anotheria/moskito-javaagent-lite. The download packages contain READMEs with instructions.

Spring

There are two easy ways to integrate MoSKito into your spring application. First: use classic AOP straight away.

You can also use spring-aop to even spare the annotations. Check out MoSKito Spring AOP Example on how to create your spring aspects and declare beans. Example:

<!-- start AOP -->
<bean id="moskitoAspect" class="org.anotheria.moskitoexamples.spring2.SpringAspect"/>

<aop:config proxy-target-class="true">
    <aop:aspect ref="moskitoAspect" order="1">
        <aop:around method="doProfiling"
                    pointcut="org.anotheria.moskitoexamples.spring2.SpringAspect.aroundEveryMethod() and target(org.anotheria.moskitoexamples.spring2.b.BServiceImpl)"/>
    </aop:aspect>
    <aop:aspect ref="moskitoAspect" order="1">
        <aop:around method="doProfiling"
                    pointcut="org.anotheria.moskitoexamples.spring2.SpringAspect.aroundEveryMethod() and @within(net.anotheria.moskito.aop.annotation.Monitor)"/>
    </aop:aspect>

</aop:config>
<!-- end of AOP -->

Web

MoSKito comes with some juicy set of out-of-the-box web statistics. To include them in monitoring you simply have to add the jar to your dependencies (or put it into the WEB-INF/lib folder):

<dependency>
    <groupId>net.anotheria</groupId>
    <artifactId>moskito-webui</artifactId>
    <version>2.4.2</version>
</dependency>

If you don't have servlet 3.0 compliant container, you will have to add the filters either programmatically or to your web.xmlstrong>. It is pretty simple still:

<filter>
    <filter-name>RequestURIFilter</filter-name>
    <filter-class>net.anotheria.moskito.web.filters.RequestURIFilter</filter-class>
    <init-param>
        <param-name>limit</param-name>
        <param-value>100</param-value>
    </init-param>
</filter>
<filter-mapping>
    <filter-name>RequestURIFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>
Check the MoSKito Web Fragment for the further examples and our web integration page for explanations on filters and listeners.

Ehcache

The ehcache integration guide will make his appearance shortly, however, in the meantime there is an ehcache integration example project on github.

Proxies

Java Runtime Proxies (java.lang.reflect.Proxy) was the first available way of MoSKito Integration back in 2007. The proxies are less convenient as aspect oriented monitoring but they have their positive sides:

  • They monitor interfaces, not implementations, meaning that you only monitor declared methods and public contracts.
  • They monitor from client perspective, so each client that obtains an instance of a service-proxy is monitored separately and you can learn which parts of your application are causing the load.

Proxies are part of the moskito-core package and are integrated via maven, gradle or ant, similar to the AOP or CDI pom magic. Assuming you have a service:

public interface SimpleService{
    void doSomethingMethod();
}
and an implementation:
public class SimpleServiceImpl implements SimpleService{
    public void doSomethingMethod(){
}
With declared dependencies simply call this line in your code:
SimpleService service = ProxyUtils.createServiceInstance(new SimpleServiceImpl(), "default", SimpleService.class);
Every call that you perform through your service variable is monitored. If you create a second proxied SimpleService instance, you will have them both in MoSKito Inspect and can separate between them.

Of course you are not limited to monitor 'services', each and every interface can be monitored. Visit Integration guide on proxies for more options and details.
One note, though: monitored proxies are memory resident, and it's generally not a good idea to create them on each call, since they will be referenced by the registry and never die. So in cases you want to measure what happens in a class, which objects are continuously reinstantiated, you need CallExecution.

Call Execution

In case you want to monitor just a part of your method or your code is splittered in multiple chunks along multiple threads/classes/methods or you simply don't have an object that is supposed to live long and create new executors continuously (for example the command pattern) - Call Execution is what you need.
Basically CallExecution consists of two steps:

private OnDemandStatsProducer<ServiceStats> producer;
public SomeConstructorOrInitMethod(){
    producer = new OnDemandStatsProducer<ServiceStats>("my-business-process", "category", "subsystem", ServiceStatsFactory.DEFAULT_INSTANCE);
    ProducerRegistryFactory.getProducerRegistryInstance().registerProducer(producer);
}
CallExecution execution = producer.getStats("phase1").createCallExecution();
execution.startExecution();
//now we are doing something extremely important...
execution.finishExecution();

The producer my-business-process will show up in MoSKito Inspect with stat phase1. Of course you can have multiple phases associated with one producer (or multiple calls for that matter). You will also be able to pause/resume phases with multiple execution parts in 2.5.0.
See Example on CallExecution on GitHub for more details.

Enable MoSKito Inspect with Agent/Standalone

Usually after integrating something into something else, you want to see the results. To see the results of your MoSKito Integration you need a kind of UI. Surely you can watch the logs, but this is kind of boring, and there are no good pictures to show. Therefore, we will stick with the Web User Interface - short MoSKito Inspect. There are two ways of integrating MoSKito Inspect, either as standalone or directly embedded into your application. Which one to choose depends on you, standalone version is easier to setup and can connect to multiple servers, embedded - simplifies you deploment.
The integration of the standalone version is explained here, scroll down for the embedded version.
For more information on MoSKito Inspect visit MoSKito Inspect Documentation.

First you'll need to download the Standalone MoSKito Inspect bundle.

Maven

The Maven integration of the MoSKito Inspect is basically one dependency in your pom. Thanks to servlet 3 MoSKito Agent for Inspect is automagically started once you add MoSKito jars to your project.


<properties>
    <moskito.version>2.6.0</moskito.version>
</properties>
<dependency>
    <groupId>net.anotheria</groupId>
    <artifactId>moskito-inspect-remote</artifactId>
    <version>${moskito.version}</version>
</dependency>
	

Without tools

Without maven you will need to add all related jars to your project. We don't provide it, because it can break your other dependencies, but feel free to ask for it on the mailing list or build yourself. Another option would be to pick all the libs from MoSKito Inspect installation.

try{
  StartMoSKitoInspectBackendForRemote.startMoSKitoInspectBackend();
}catch(MoSKitoInspectStartException e){
  //handle error
  log.error("Couldn't auto-start MoSKito Inspect in embedded mode ", e);
}

Enable MoSKito Inspect in Embedded Mode

Embedded mode allows you to embed MoSKito Inspect into your application. This is easier to handle if you only have limited amount of servers, all your components run in web containers anyway and/or you can not allow network connection from standalone inspect to your servers.
For more information on MoSKito Inspect visit MoSKito Inspect Documentation.

Maven

The Maven integration of the MoSKito Inspect is basically a small set of pom manipulations. Thanks to servlet 3 MoSKito is automagically added once you add MoSKito jars to your project. All you need are following simple additions to your pom.

<properties>
    <moskito.version>2.6.0</moskito.version>
</properties>
<dependency>
    <groupId>net.anotheria</groupId>
    <artifactId>moskito-web</artifactId>
    <version>${moskito.version}</version>
</dependency>
<dependency>
    <groupId>net.anotheria</groupId>
    <artifactId>moskito-inspect-embedded</artifactId>
    <version>${moskito.version}</version>
</dependency>
<dependency>
    <groupId>net.anotheria</groupId>
    <artifactId>moskito-inspect-jersey</artifactId>
    <version>${moskito.version}</version>
</dependency>
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <configuration>
        <artifactItems><artifactItem>
            <groupId>net.anotheria</groupId>
            <artifactId>moskito-webui</artifactId>
            <version>${moskito.version}</version>
            <type>jar</type>
            <overWrite>true</overWrite>
            <outputDirectory>${project.build.directory}/tmp</outputDirectory>
            <includes>moskito/**,**/*.jsp</includes>
        </artifactItem></artifactItems>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>unpack</goal>
            </goals>
        </execution>
    </executions>
</plugin>

<plugin>
    <artifactId>maven-war-plugin</artifactId>
    <version>2.1</version>
    <configuration>
        <webResources>
            <resource>
              <directory>${project.build.directory}/tmp</directory>
            </resource>
        </webResources>
    </configuration>
</plugin>

Gradle

We do not provide graddle support ourselves, but there is a blog entry on moskito and graddle: http://coders-kitchen.com/2013/03/29/tutorial-using-moskito-with-cdi/