The complete MoSKito integration guide – Step 1

After we created our guinea pig in the previous step, it’s now time to integrate MoSKito-Essential into our application. Our plan for today is:

  • Add monitoring to the core parts of our code.
  • Download and connect MoSKito Inspect
  • Learn about WebFilters and Listeners

At the end of the guide we want to:

  • see the access data in MoSKito Inspect,
  • record a Journey.

Lets go!

Before we start, you will need to checkout the project (unless already done in previous step):

git clone https://github.com/dvayanu/burgershop
cd burgershop
git checkout moskito-integration-guide-step0 
mvn clean install

Note: we will make a maven based integration on a branch named guide-2.5.0-maven, for ant or graddle use the corresponding branches, even if the steps are very similar.

Note: this guide was initially written for 2.4.0 and updated for 2.5.0, if you want to work with 2.4.x switch to the branch guide.

Note: this guide was updated for 2.5.5.

I. Mark classes for monitoring.

First, we want to add some classes to the monitoring. We don’t want to add all classes, because it just spams the monitoring. For example, this class:

public class ShopableItem {
	private int price;
	private String name;
	private Category category;

	public ShopableItem(){
	}
...
}

which is a simple DTO which doesn’t need to be monitored. We should monitor classes that actually do some job, have some payload. In case of a spring application, these classes should at least include Services and Controllers. 

In general, everything that does something of interest should be monitored, but the ‘property holders’ classes shouldn’t.

To monitor our Services and Controllers, we are going to use the AOP Integration. We could also use Proxies or even Spring-aop, but AOP is the best right now.

To enable AOP Integration, we have to perform 2 steps:

  • Add dependencies and build plugins to the pom.xml.
  • Annotate classes.

II. Declare dependencies

We are going to add some dependencies to MoSKito artifacts in the course of this guide, so it makes sense to define a variable for version, to use same version in all artifacts, and to be able to change it easy. In our case the version is 2.5.5.

Add those lines somewhere in your pom.xml, preferably above the dependencies section, since this is where we’re going to use it:

    <properties>
        <moskito.version>2.5.5</moskito.version>
    </properties>

Now add the dependencies, needed for AOP:

        <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>
      </dependencies>

and the AOP plugin in the build section.

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

Also, you can simply checkout commit fb34286 on branch guide-2.5.0-maven.

Note: this guide was updated for 2.5.5. So you have to update moskito version in pom.xml.

However, we haven’t achieved much yet. We need to annotate the classes now. To do so, we open the ShopController, OrderController, HomeController and ShopServiceImpl classes  and add @Monitor above the class declarations, like this:

@Monitor
public class ShopServiceImpl implements ShopService {

Your IDE should be able to suggest the right import for the @Monitor annotation, but in case it doesn’t, it is: net.anotheria.moskito.aop.annotation.Monitor.

After we made sure that build still builds, we can try to start the built application. We will see if it still works. The only new thing, after we open http://localhost:8080/burgershop/, are some new output lines in the logs, , like this one:

00:43:33.864 [http-bio-8080-exec-8] INFO  n.a.m.c.r.ProducerRegistryImpl - Registry register producer: ShopController / OnDemandProducer (unlimited): ShopController:default:annotated

So, great, we now do have MoSKito integrated into our application, but we can’t see anything. Lets change this by connecting inspect.

III. Connect Inspect

To connect inspect we need to perform two steps: enable a connector inside our app and actually download and start inspect.

To enable MoSKito Inspect to connect to your application, we must start an endpoint in your application (which is in this case burgershop), and this is done by adding one dependency to the pom and one line to catalina.sh:

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

Now, please locate your catalina.sh (or bat) and add following line to it, right on top:

export JAVA_OPTS="$JAVA_OPTS -DlocalRmiRegistryPort=9401"

This will tell the MoSKito Inspect endpoint to accept incoming RMI connections at port 9401. You can of course specify another port.

Now, please rebuild and restart your app.

So now we just have to download inspect from here: http://www.moskito.org/download.html or directly by this link. Note, you can always build your own MoSKito Inspect by simply putting the moskito-inspect-standalone war file in a servlet container of your choice, be it resin, tomcat or jetty. Just keep in mind that you will need a servlet3.0 compatible container, so tomcat5 or 6 won’t work. But for now let’s stay with our prepared download.

After you downloaded MoSKito Inspect archive unpack it somewhere. For example I did it under /opt:

cd /opt
tar -xzf ~/Downloads/moskito-inspect.tgz
cd moskito-inspect/

MoSKito Inspect download is basically a tomcat with a war file, so you can start it like a normal tomcat:

cd tomcat/
bin/startup.sh

Default port for MoSKito Inspect is 8088, simply because it seemed to have less conflicts as 8080. So you can access http://localhost:8088/moskito/

If you did everything right you will see this page a running MoSKito Inspect. MoSKitoInspectStarted

You can click around a little and celebrate 😉 But before you get too excited, what you see now is data from the MoSKito Inspect tomcat itself, not your burger-selling-app. To change it, you have to tell the Inspect to connect to the burgershop. Click on the producers tab (or any other tab). In the lower left part of the screen you will see a ‘QuickConnect’ box:

LocateQuickConnectBox

Enter localhost as host and 9401 as port and click Connect:

BurgershopConnect

 

The screen should reload, and now you see data from your application. You can verify it, but clicking this url: http://localhost:8088/moskito/moskito-inspect/mskShowProducersByCategory?pCategory=controller

It will show you the previously annotated controllers and requests to them:

BurgerSHopController

 

You can now make some orders in the shop and see the numbers increasing in the controllers overview.

We didn’t specify any category for the ShopService itself, so it will be under the default category for annotated classes which is … annotated: http://localhost:8088/moskito/moskito-inspect/mskShowProducersByCategory?pCategory=annotated

 

I will not describe the usage of the MoSKito Inspect here, you may find it in MoSKito Inspect User Guide. (Warning: at the time this guide is written, the User Guide still refers to 2.4.x version)

IV. Built-in stuff.

By adding the MoSKito Inspect Connector to our application we actually added some extra features, I would briefly describe here.

The built-in producers add some useful information about what’s happening in your app:

BuiltinProducers

 

I will shortly name few:

Memory Pools

Memory pools are collecting information about memory usage in different memory spaces, being it old generation or young generation. This is very helpful to detect potential memory problems.

ThreadStates and ThreadCount

Those give you information about different states that you threads are in, and the amount of the threads in each state. Typically you would like to avoid having threads in blocked state.

HttpSession

The current session count as well as number of created and deleted sessions over time.

Accumulators

But you will also get some accumulators ready to use:Accumulators

For example the development of your threads can be visualized out of the box:

ThreadStates

URLs

MoSKito also tracks all called urls in your application and many more things.

URLS

But the real jewel are the journeys:

V. Make our first Journey.

A Journey is a recording of user actions in the form of actual calls/steps that occur inside an application. Read more…

There are multiple ways to start the journey. One of the easiest is to supply a special parameter along with your request. MoSKito will check the presence of the parameter and record everything that happens in that user session.

To start our first Journey we call the Homepage of the Burgershop with the special parameter: http://localhost:8081/burgershop/home.html?mskJourney=start&mskJourneyName=GUIDE

The GUIDE journey will show up in MoSKito Inspect immediately (tab Journeys):

JourneyGUIDE

 

Now I can click in the application in one window and trace what it actually does in another. And the best thing is, the overhead of this production profiling is so minimal, that you actually can do it without harm to your users, what a normal profiler couldn’t do (or not named commercial products).

After performing a full order process (well in burgershop the whole process are three requests ;-)), I can see it at once:

JourneyGuideSteps

 

I can click on one step and see all calls through all my monitoring stations (that is all classes annotated with @Monitor, configured with AOP or CDI, Filters, SQL-Interceptors etc) including parameters and return values:

JourneyGuideStep

Now we can see what is happening in our application when the order is placed: which Controller calls which Service, what the Service does. And how long it takes. And what parameters are submitted. And the failures (if any).

The Burger Shop is a pretty simple application, therefore there is not much to see in the above journey. But I’ve seen applications with journey’s length up to 10000 steps, and believe me: there are a lot of surprises in analysing such long calls.

The above topic should give you a brief idea of what the journeys are capable of. We will return to the Journeys in later steps, especially when we talk about the Analyze function. 

So, what have we done today?

  • We integrated MoSKito into our application.
  • We installed and connected MoSKito Inspect.
  • We added monitoring for key classes of our application.
  • We recorded a Journey.

In the next chapter, we’ll be adding a Counter, a Producer with custom stats object, thresholds and accumulators. After that, we will add another server and put both servers into Live Monitoring with MoSKito-Control. And last but not least – we’ll set up MoSKito-Central.

As usual, I added a tag, moskito-integration-guide-step1-maven, which can be used to checkout the resulting code directly:

git checkout guide-2.5.0-maven-step1

Since most of our changes (almost all of them) are taking place in the pom.xml, I decided to put it here in full length, for quick review:

Enjoy and see you soon!

Next Step.

13 thoughts on “The complete MoSKito integration guide – Step 1

  1. Pingback: The complete MoSKito integration guide – Step 0 | anotheria devblog

  2. Pingback: The complete MoSKito integration guide – Step 2 – Add some counters | anotheria devblog

  3. Pingback: The complete MoSKito integration guide – Step 3 – Custom producers | anotheria devblog

  4. Hi, thanks for providing the details. However, I got status code 404, while clicking this link ‘http://localhost:8080/burgershop/mui/mskShowAllProducers’ from the middle of this page. Do I need to do something with the web.xml?

    Thanks, Scott

  5. Hi Scott,
    The problem with tomcat5 (and 6 for that matter) is that we are using web-fragments to configure MoSKito filter and other stuff. The web-fragments are a feature of servlet 3.0 and neither tomcat5 nor tomcat6 support it. But you shouldn’t really run anything on a 10 years old tomcat 5 anyway 😉

    regards
    Leon

    • Actually it was, what would you point it to? 🙂
      Look, example is all about localhost, so if you followed previous steps it actually will point to your local installation and open a working screen.

  6. Hi,
    in our company we are looking for a tomcat monitoring tool.
    We would like to monitor or answer the question
    “which session is using which JDBC connection?”.

    I found moskito and wanted to test it.
    I am using tomcat 8, and moskito-inspect as standalone.
    moskto-inspect worked well, i can also connect to the RMI Port 9401

    I insert the moskito-Annotation in my App,
    but i can t see my controler as shown in picture “BurgerSHopController.png”
    In the service-Table there is no controller Category.

    Any suggestion what im doing wrong?

    thx,
    Bertrand

  7. For Windows users:
    the right command to add in catalina.bat is
    set “JAVA_OPTS=%JAVA_OPTS% -DlocalRmiRegistryPort=9401”

  8. Pingback: Newest. Hottest. Tracers. | anotheria devblog

Leave a Reply

Your email address will not be published. Required fields are marked *

*