SCOM 2012 R2 Java APM – MP Installation and Configuration (Part 3)

Finally we are going to install and configure Java APM management pack. Just for a small recap, we have a monitored Linux server and a fully functional Tomcat application server in place which is configured for deep monitoring. Cool, huh?

Now we would like to get some hands on performance of one of the applications in Tomcat. But before we can do that, we need to install the Java APM management pack and also install the Java APM agent. The Java APM agent is a piece of software which (I think) hooks up to the Tomcat application server to get the exception and performance information out of the applications. This agent is a kind of tricky to install and get it working right away. If you follow this post you will succeed of course. I hope Microsoft will change the installation for the final release, either to create a task or an other way to deploy it automatically.

So far Microsoft has not published any documentation about the exact architecture nor any other details of Java APM. The only documentation so far available is the MP guide. There we have our first problem, where can you find the MP guide? Well, read this post :).

Let’s the journey start…

Prerequisites

• JEE deep monitoring enabled (Part 2)
• Download the Java APM management pack
• Download sample struts 2 application for testing

Install Java APM Management Pack

Once more I downloaded the Java APM management pack to C:\MP and extracted the MSI and received these files…

Import the following 3 management packs…

• Microsoft.JEE.APM.Library.mpb
• Microsoft.JEE.Tomcat.6.Library.mp
• Microsoft.JEE.Tomcat.APM.Library.mp

If all your prerequisites match you will have all green in your SCOM MP wizard, click Install…

That was the easy part, now we will separate the men from the boys :)…

Configure APM Linux Agent

Go to Monitoring and select your monitored application server under Tomcat Servers/Deep Monitored Configurations . On the right side you will see a task Extract APM Jar files, click this task…

After the task succeeded you will find a APM-Java-Agent-1.10.100.5.zip file in your C:\Windows\Temp folder…

If you are going to extract the zip file and open the APM-Java-Agent-1.10.100.5 folder…

…surprise, you will find the agent files and the Java APM MP guide in the doc folder…

Since we have all necessary files in place, we need to copy the Java APM agent files to our Ubuntu01 server. I use the WinSCP client, which is freely available here . Install the client and start it with your credentials…

Go to your Linux server and create a folder where you want to store the agent files. In my case I just create a /apm directory and give permission to read and execute. There might be better places to dump the files, but it is ok for testing :)…

In the WinSCP window select the Java APM agent files in the left window and copy it to the /apm directory on your Linux box…

The next step is to configure the catalina.sh file, which is called when you are stopping or starting Tomcat. First we need to locate the catalina.sh file by running the find command…

Navigate to the catalina.sh file and edit it in your favorite editor. Now, in the upper third of the file, there is a section where you declare variables, add the following lines to the file…

#!/bin/bash
AGENT_DIR=/apm
# Set location for native (DLL/so) library
JAVA_OPTS=”$JAVA_OPTS -Djava.library.path=$AGENT_DIR”
JAVA_OPTS=”$JAVA_OPTS -javaagent:$AGENT_DIR/apm_facade.jar -Xbootclasspath/p:AGENT_DIR/apm_producers.jar -Xbootclasspath/p:$AGENT_DIR/apm_facade.jar”
export AGENT_DIR=”$AGENT_DIR”
export JAVA_OPTS=”$JAVA_OPTS”

These lines will add parameters to the JAVA_OPTS variable, which is needed to run the agent. If you have done that, save and exit the file.

As a next step I like to know what this agent is doing and therefore I configure the logging level in the /apm/Starter.properties file to FINEST. 

DON’T DO THAT IN PRODUCTION!

This logging level creates a lot of logging entries and in production you are better of using INFO level. Save and exit the file…

Now we need to restart Tomcat therefore change into the directory /usr/share/tomcat6/bin and type…

• sh shutdown.sh
• sh startup.sh

This will shutdown and start Tomcat. If Tomcat started without an error, you need to make sure your the APM agent is started. To find this out, search for a log file called apm-java-agent.log. This file is generated if the agent installation was successful.

If your search is successful, navigate to the file and open it in your editor. The last line of the file should look like this…Java APM agent initialization successful

Congratulation, you just deployed the Java APM agent! You are THE man…

Install Sample Application

For some testing purposes I was looking for a supported and easy to deploy application. I found this application which is written using Struts. What is Struts? It is a web application framework based on JSPs, Servlets and Java Beans.

Just download the application and extract the files. Then copy the folder called first into the Tomcat webapps folder. It should look like this…

…and if you are starting the http://ubuntu01:8080/first URL you should see the application…

Now your installation for Java APM is finished…phuhh.

Let’s see what we get.

Java APM Views / Monitors

If you try to find any state view or other dedicated view, you will end up searching forever. To get performance data from the application select the application first and in the context menu click Performance View…

and here how it look like…

As you can see there are performance rules for:

• Average Request Time
• Exception Events / sec
• Monitored Requests/sec
• Performance Events/sec

There are also corresponding monitors right out of the box. Open HealthExplorer for a Tomcat application, like BeanSpy or our newly installed application first and you will notice some new monitors which are disabled by default…

If you would like to get alerts about certain parameters like…

• Average Request Time
  When looking for alerting when average request time is over threshold
• Exception Events / Second
  When looking for alerting when exception event rate threshold
• Performance Events / Second
  When looking for alerting when performance event threshold is crossed
• Requests / Second (low threshold)
  When looking for alerting when requests per second under threshold
• Requests / Second (high threshold)
  When Looking for alerting when requests per second over threshold

…you can enable / override these monitors for your application…

If you configure your thresholds properly and performance issues or exceptions are occurring, you will receive alerts and see it on the performance and/or alert views. In addition you will see events in the APM Advisor console, but this will be another story…ah I mean…blog post…

Have fun!