Monitor dependencies, caught exceptions and method execution times in Java web apps

If you have instrumented your Java web app with Application Insights, you can use the Java Agent to get deeper insights, without any code changes:

  • Dependencies: Data about calls that your application makes to other components, including:
    • REST calls made via HttpClient, OkHttp, and RestTemplate (Spring) are captured.
    • Redis calls made via the Jedis client are captured.
    • JDBC calls - MySQL, SQL Server and Oracle DB commands are automatically captured. For MySQL, if the call takes longer than 10s, the agent reports the query plan.
  • Caught exceptions: Information about exceptions that are handled by your code.
  • Method execution time: Information about the time it takes to execute specific methods.

To use the Java agent, you install it on your server. Your web apps must be instrumented with the Application Insights Java SDK.

Install the Application Insights agent for Java

  1. On the machine running your Java server, download the agent. Please ensure to download the same version of Java Agent as Application Insights Java SDK core and web packages.

  2. Edit the application server startup script, and add the following JVM:

    javaagent:full path to the agent JAR file

    For example, in Tomcat on a Linux machine:

    export JAVA_OPTS="$JAVA_OPTS -javaagent:<full path to agent JAR file>"

  3. Restart your application server.

Configure the agent

Create a file named AI-Agent.xml and place it in the same folder as the agent JAR file.

Set the content of the xml file. Edit the following example to include or omit the features you want.


    <?xml version="1.0" encoding="utf-8"?>
    <ApplicationInsightsAgent>
      <Instrumentation>

        <!-- Collect remote dependency data -->
        <BuiltIn enabled="true">
           <!-- Disable Redis or alter threshold call duration above which arguments are sent.
               Defaults: enabled, 10000 ms -->
           <Jedis enabled="true" thresholdInMS="1000"/>

           <!-- Set SQL query duration above which query plan is reported (MySQL, PostgreSQL). Default is 10000 ms. -->
           <MaxStatementQueryLimitInMS>1000</MaxStatementQueryLimitInMS>
        </BuiltIn>

        <!-- Collect data about caught exceptions
             and method execution times -->

        <Class name="com.myCompany.MyClass">
           <Method name="methodOne"
               reportCaughtExceptions="true"
               reportExecutionTime="true"
               />
           <!-- Report on the particular signature
                void methodTwo(String, int) -->
           <Method name="methodTwo"
              reportExecutionTime="true"
              signature="(Ljava/lang/String;I)V" />
        </Class>

      </Instrumentation>
    </ApplicationInsightsAgent>

You have to enable reports exception and method timing for individual methods.

By default, reportExecutionTime is true and reportCaughtExceptions is false.

Additional config (Spring Boot)

java -javaagent:/path/to/agent.jar -jar path/to/TestApp.jar

For Azure App Services do the following:

  • Select Settings > Application Settings
  • Under App Settings, add a new key value pair:

Key: JAVA_OPTS Value: -javaagent:D:/home/site/wwwroot/applicationinsights-agent-2.3.1-SNAPSHOT.jar

For the latest version of the Java agent check the releases here.

The agent must be packaged as a resource in your project such that it ends up in the D:/home/site/wwwroot/ directory. You can confirm that your agent is in the correct App Service directory by going to Development Tools > Advanced Tools > Debug Console and examining the contents of the site directory.

  • Save the settings and Restart your app. (These steps only apply to App Services running on Windows.)

Note

AI-Agent.xml and the agent jar file should be in the same folder. They are often placed together in the /resources folder of the project.

Spring Rest Template

In order for Application Insights to successfully instrument HTTP calls made with Spring's Rest Template, use of the Apache HTTP Client is required. By default Spring's Rest Template is not configured to use the Apache HTTP Client. By specifying HttpComponentsClientHttpRequestfactory in the constructor of a Spring Rest Template, it will use Apache HTTP.

Here's an example of how to do this with Spring Beans. This is a very simple example which uses the default settings of the factory class.

@bean
public ClientHttpRequestFactory httpRequestFactory() {
return new HttpComponentsClientHttpRequestFactory()
}
@Bean(name = 'myRestTemplate')
public RestTemplate dcrAccessRestTemplate() {
    return new RestTemplate(httpRequestFactory())
}

Enable W3C distributed tracing

Add the following to AI-Agent.xml:

<Instrumentation>
        <BuiltIn enabled="true">
            <HTTP enabled="true" W3C="true" enableW3CBackCompat="true"/>
        </BuiltIn>
    </Instrumentation>

Note

Backward compatibility mode is enabled by default and the enableW3CBackCompat parameter is optional and should be used only when you want to turn it off.

Ideally this would be the case when all your services have been updated to newer version of SDKs supporting W3C protocol. It is highly recommended to move to newer version of SDKs with W3C support as soon as possible.

Make sure that both incoming and outgoing (agent) configurations are exactly same.

View the data

In the Application Insights resource, aggregated remote dependency and method execution times appears under the Performance tile.

To search for individual instances of dependency, exception, and method reports, open Search.

Diagnosing dependency issues - learn more.

Questions? Problems?