1) Login to Application Insights for Visual Studio Online. 

If necessary, sign-up here first.

2) Download the Java APM Agent

Again, I will defer to the official documentation for describing how to navigate the UI pages as this contains several pretty pictures.  The short version is that after logging-in to the site, choose the settings icon and navigate to the Keys and Downloads tab.

3) Unzip the Agent locally

For the purposes of this quickstart guide, let's assume that after downloading you have decided to place the zip files to the root folder.  For your own sanity, a folder without spaces tends to make life easier.  The rest of the guide will assume that the Java agent exists in a folder \JavaAgent.

4) Update the Account ID and Account Key in SEAgent.config.xml

In the unzipped folder, locate the SEAgent.config.xml file

    <dataWriter>
      <ApmProcessingAddress>https://eus-amt-wt1.tofino.windowsazure.com</ApmProcessingAddress>
      <!--<accountId>Put the account id obtained from app-analytics portal here</accountId>-->
      <!--<accountKey>Put the instrumentation key obtained from app-analytics portal here</accountKey>-->
      <batchSize>100</batchSize>
    </dataWriter>

change to (for some reason, the blog is fubar'ing the XML below - just make sure to uncomment these accountId and accountKey elements and replace them with the values from the Application Insights web page)

    <dataWriter>
      <ApmProcessingAddress>https://eus-amt-wt1.tofino.windowsazure.com</ApmProcessingAddress>
      <accountId>00000000-0000-0000-0000-000000000000</accountId>
      <accountKey>00/00000000000000000000000000000000000000000000000000000000000000000000000000000000000==</accountKey>
      <batchSize>100</batchSize>
    </dataWriter>

5a) Modify Start-up Script (Windows)

Locate the catalina.bat script and the following line:

:noJuliManager 
set JAVA_OPTS=%JAVA_OPTS% %LOGGING_MANAGER%

set APM_DIR=\JavaAgent
set APM_OPTS=-Djava.library.path="%APM_DIR%" 
-javaagent:"%APM_DIR%\apm_facade.jar" 
-Xbootclasspath/p:"%APM_DIR%\apm_facade.jar" 
-Xbootclasspath/p:"%APM_DIR%\apm_producers.jar"
set JAVA_OPTS=%JAVA_OPTS% %APM_OPTS%
 
rem ----- Execute The Requested Command ---------------------------------------

The above code should be on a single line; however, for formatting reasons this has been broken into several lines to improve readability. For more details, see here.

5b) [Alternate] Modify Start-up Script (Windows as a Service)

The exact syntax will change slightly depending on the version of Tomcat, but the general invocation should look like:

.\bin\Tomcat7 //US//Tomcat7 ++JvmOptions=-javaagent:"\JavaAgent\apm_facade.jar"
#-Xbootclasspath/p:"\JavaAgent\apm_facade.jar"
#-Xbootclasspath/p:"\JavaAgent\apm_producers.jar"
#-Djava.library.path="\JavaAgent"

The above code should be on a single line; however, for formatting reasons this has been broken into several lines to improve readability.  For more details, see this blog post.

5c) [Alternate] Modify Start-up Script (Linux)

Locate the catalina.sh script and the following line:

if [ -z "$LOGGING_MANAGER" ]; then
 JAVA_OPTS="$JAVA_OPTS -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager"
else
 JAVA_OPTS="$JAVA_OPTS $LOGGING_MANAGER"
fi
 
APM_DIR=/path/to/apm/agent/zip/contents 
APM_OPTS="-javaagent:$APM_DIR/apm_facade.jar 
-Xbootclasspath/p:$APM_DIR/apm_producers.jar 
-Xbootclasspath/p:$APM_DIR/apm_facade.jar"
JAVA_OPTS="$JAVA_OPTS $APM_OPTS"

# ----- Execute The Requested Command -----------------------------------------

The above code should be on a single line; however, for formatting reasons this has been broken into several lines to improve readability. For more details, see here.

6) (Re-)Start Apache Tomcat

How Can I Know What Version I Have

Due to some technical requirements, the name of the zip file needs to remain constant between versions.  Hence, when you download the zip file the file does not contain the version string in the file name.  The good news is that in the ZIP file there is a XML file version.xml that contains.... (what for it)... the version!  This human-readable file is intended for information use:

<?xml version="1.0" encoding="utf-8"?>
<!-- /////////////////////////////////////////////////// -->
<!--         Copyright (c) Microsoft Corporation         -->
<!-- /////////////////////////////////////////////////// -->
<!-- Human-readable file with version/build information. -->
<!-- This is an auto-generated file (i.e. modifying this -->
<!-- file will not change the version information        -->
<!-- displayed in the running program.                   -->
<VersionInformation>
  <Version>1.13.100.1</Version>
  <LabelName>NotFromLabel</LabelName>
  <BuildDate>20140325</BuildDate>
</VersionInformation>

Additionally, each jar file contains an XML file with the version number in it.  To access it, rename the jar file to a zip file (you may need to update your Windows Explorer settings to show know file extensions).  And if you are curious, no you may not unzip the file, update the version number, and re-zip the jar file.   If you do, chaos will ensue!  :)

If there is no version file, that means you are using a very old agent, in which case download a newer one in order to take advantage of the features listed below.

The Changelog

Here is a non-exhaustive list of changes to the Java Agent as far back as I was willing to look in version control.  Moving forward, I will (try to) update this blog post as new Agents roll-out.

1.12.100.4 (March 2014)

• Finalized support for gathering Custom Performance Counters from JMX
• Improved Configuration Plan format
• Added feature to send counters without waiting for entrypoints to enable support for elasticSearch, Kafka, etc…
• Bug fixes

1.12.100.1 (January 2014)

• Preliminary support for gathering Custom Performance Counters from JMX
• Bug Fixes
  

1.11.100.1 (November 2013)

• Run-time Dependency Discovery (RDD) support for HTTP methods
• Performance and bug fixes 

1.10.100.15 (November 2013)

• Version released for SCOM 2012 R2 on-premise solution
• Send events directly to the VSO Endpoint
• Java Policy Support
• Event parameter regular expression filtering
• Security Fixes

This post will discuss Exception Events generated by the Java APM Agent.  To illustrate this, let me briefly explain how instrumentation works, the limitations of this, and how to modify the configuration files to account for cases interesting to you.  In an ideal world, a method might look like:

public foo() throws Exception {
  // Do stuff
}

If foo() has been identified as a method to instrument (i.e. it is specified in pmonitor.config.xml), then at runtime the code is instrumented to look like:

public foo() throws Exception {
  prefix()
  try {
    // Do stuff
    postfix()
  }
  catch(Exception e)
  {
    handleException()
  }
}

And generally, this works.... except for when it does not.  Sometimes various web frameworks (such as Struts) may have code that catches and maps exceptions.  True, the web browser may display a message and an exception stack trace, but from a code point-of-view there was no exception.  Consider this code:

public callRestService(){
  try {
    // contains calls to all other methods, which could throw any exceptions.
  } catch(Exception ex){
    logException(ex);
  }
}

In order to address this (common) software pattern, there are two suggestions:

1. ExceptionHandler instrumentation
2. Stackborder instrumentation

Using ExceptionHandler Instrumentation

What it that?  ExceptionHandler instrumentation is for methods which are called by user code(or a framework) when an exception is occurred. These methods typically do some logging or hide exception from surfacing to webpage. As the goal is to capture exception information, we will make the assumption that these methods take the exception object as one of the function's argument. When a method is instrumented as ExceptionHandler, this instrumentation extracts the exception object from the argument list and creates an exception event.

For example, consider the before mentioned code with a master try/catch statement.

public callRestService(){
  try {
    // contains calls to all other methods, which could throw any exceptions.
  } catch(Exception ex){
    logException(ex, "uh-oh!");
  }
}

All exceptions thrown from user code gets caught in callRestService() and the method calls logException() to deal with the exception.  This would imply that in logException() is called, then there has been an exception.  If the method logException() is instrumented as ExceptionHandler, then when it is called the instrumentation code will generate an exception event.

Using this type of instrumentation is easy.   Just edit the ss:applicationSetting section of the pmonitor.config.xml file. All that needs to be done is to declare an exceptionHandler and declare the type of instrumentation to use.  A sample XML snippet is below for an exception logging method from a sample class called com.contoso.logger.logException (so if you substitute your package name and method in this syntax, you can just paste this into your configuration file).  Once done the logic describe above will be called with the exception handling code gets called.  An important caveat of note: this will only work if the method takes an exception object as one of its parameters.

The following shows the entries to be made in Pmonitor.config file to instrument the method as ExceptionHandler.

<ss:applicationSetting>
...
<ss:exceptionHandlers>
<ss:exceptionHandler name="com.contoso.logger.logException"/>
</ss:exceptionHandlers>
...
</ss:applicationSetting>
...
<ss:producers>
...
<ss:method name="com.contoso.logger.logException">
<ss:instrumentation name="com.microsoft.ManagementServices.APMAgent.Producers.GenericExceptionHandlerProducers.GenericExceptionHandlerPrefixDataProducer " value="prefix"/>
<ss:instrumentation name="com.microsoft.ManagementServices.APMAgent.Producers.GenericExceptionHandlerProducers.GenericExceptionHandlerPostfixDataProducer " value="postfix"/>
<ss:instrumentation name="com.microsoft.ManagementServices.APMAgent.Producers.GenericExceptionHandlerProducers.GenericExceptionHandlerOnExceptionDataProducer " value="onException"/>
</ss:method>
...
</ss:producers>

Using StackBorder Instrumentation

What is that?  Suppose what is really important to know is that when a given method throws an exception - regardless of whether this event gets caught elsewhere in the code.

public callRestService(){
  try {
    ...
   canaryInTheCave()
    ...
  } catch(Exception ex){
   logException(ex, "uh-oh!");
  }
}

public canaryInTheCave() throws Exception {
  // some bellweather code
}

In this case, the method to instrument is canaryInTheCave() decides to throw an exception and the type of instrumentation is StackBorder.  If any unhandled exceptions is thrown from a method with this instrumentation, it will result in "Critical Exception".  What this means is that irrespective of whether this exception is handled at a higher level or not, the code will create an exception event. This is ideal for scenarios where all exceptions generated from user code are handled by a framework code (or even a master try catch in use code itself). Without this type of instrumentation, this scenario would not generate any exception events because at a code level no exceptions surface.  Some other level of framework code is handling the exception and the StackBorder instrumentation comes to rescue. By instrumenting the method which stands at the boundary of user code and framework code (aka the stack border), then the exception crossing the method will be marked as critical and an exception event will be created.

This is not any more difficult from an XML perspective, an appropriate method should be marked in the pmonitor.config.xml.  The catch is to know the method name!  This is little tricky (we're looking at you Struts) as one must identify method(s) between where the user code generates an exception and the framework code that handles the exception. 

The following shows the entries to be made in Pmonitor.config file to instrument the method as StackBorder.

<ss:applicationSetting>
...
<ss:stackBorders>
<ss:stackBorder name="com.contoso.restService.canaryInTheCave"/>
</ss:stackBorders>
..
</ss:applicationSetting>
..

<ss:producers>
...
<ss:method name="com.contoso.restService.canaryInTheCave">
<ss:instrumentation name="com.microsoft.ManagementServices.APMAgent.Producers.LightWeightProducers.LightWeightPrefixDataProducer" value="prefix"/>
<ss:instrumentation name="com.microsoft.ManagementServices.APMAgent.Producers.LightWeightProducers.LightWeightPostfixDataProducer" value="postfix"/>
<ss:instrumentation name="com.microsoft.ManagementServices.APMAgent.Producers.LightWeightProducers.LightWeightOnExceptionDataProducer" value="onException"/>
</ss:method>
...
</ss:producers>

The Application Insight feature is presently preview-only.  To gain access to this feature create a Visual Studio Online account and choose the Application Insights tile in your account page.

The officially supported platforms are:

• Tomcat (5.5, 6, 7)
• JBoss Application Server 6

Unofficially, it is possible to get some level of monitoring from most any Java application because the means of instrumenting the Java process is done via the java.lang.instrument package.  While the data may not be as rich as the above supported platforms, there will be some information available and I will detail how to do this is a future blog post.

Wrapping up, here are some external links that will be of interest.  The general feature description of Application Insights are available on MSDN, with the Java installation notes available here.  In addition, the Application Insight forum is available here.

Note: this supersedes the Preview release mentioned here.

The MSI contains the following Management Packs

• Microsoft.JEE.APM.Library.mpb
• Microsoft.JEE.Tomcat.5.Apm.mp
• Microsoft.JEE.Tomcat.6.Apm.mp
• Microsoft.JEE.Tomcat.7.Apm.mp
• Microsoft.JEE.Tomcat.APM.Library.mp

With these Management Packs, it will be possible to get APM Performance and Exception events for deployed Java Web Applications.

Supported Operating System Platforms

• Windows
• Red Hat
• Oracle
• Centos
• Ubuntu

Support JVMs

• Oracle Java version 5
• Oracle Java version 6
• Oracle Java version 7

Supported Web/Application Servers

• Apache Tomcat version 5.5
• Apache Tomcat version 6.0
• Apache Tomcat version 7.0

Supported Web Frameworks

• General Servlets
• Axis 2
• Struts  

Forum Location

For questions, comments, feature requests, etc…, please add a note to the System Center Operations Manager Application Performance Management (SCOM APM) forum on TechNet:

http://social.technet.microsoft.com/Forums/en-US/home?forum=scomapm

Other Resources

Video: Feature Overview

Tutorial of setting-up and using the Java APM Features

In-depth discussion of configuration file settings

Download Link

https://www.microsoft.com/en-us/download/details.aspx?id=39709

:noJuliManager 
set JAVA_OPTS=%JAVA_OPTS% %LOGGING_MANAGER%
set APM_DIR=\path\to\apm\agent\zip\contentsset 
APM_OPTS=-Djava.library.path="%APM_DIR%" -javaagent:"%APM_DIR%\apm_facade.jar" -Xbootclasspath/p:"%APM_DIR%\apm_facade.jar" -Xbootclasspath/p:"%APM_DIR%\apm_producers.jar"
set JAVA_OPTS=%JAVA_OPTS% %APM_OPTS%
rem ----- Execute The Requested Command ---------------------------------------

.\bin\Tomcat7 //US//Tomcat7 ++JvmOptions=-javaagent:"\apm\apm_facade.jar"#-Xbootclasspath/p:"\apm\apm_facade.jar"#-Xbootclasspath/p:"\apm\apm_producers.jar"#-Djava.library.path="\apm"

The initial release targets supports for Tomcat 6, Tomcat 7, or JBoss 6.  If you have more questions, please post them in the Visual Studio Forums.

I must warning that if you are doing this in a work environment, you may want to double-check that the inclusion of photos from the Camera Roll folder is disabled.  You never know who might happen to walk by your computer when that picture from last night's party appears.  :)