Application Insights (for Java): Quickstart for Apache Tomcat

This post will highlight a quickstart guide to getting-up and running with the Visual Studio Online Application Insights for Java.  If this looks extremely similar to the content posted on MSDN, that would because it is.

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