Upgrading from Application Insights Java 2.x SDK

There are typically no code changes when upgrading to 3.x. The 3.x SDK dependencies are just no-op API versions of the 2.x SDK dependencies, but when used along with the 3.x Java agent, the 3.x Java agent provides the implementation for them, and your custom instrumentation will be correlated with all the new auto-instrumentation which is provided by the 3.x Java agent.

Step 1: Update dependencies

2.x dependency Action Remarks
applicationinsights-core Update the version to 3.4.3 or later
applicationinsights-web Update the version to 3.4.3 or later, and remove the Application Insights web filter your web.xml file.
applicationinsights-web-auto Replace with 3.4.3 or later of applicationinsights-web
applicationinsights-logging-log4j1_2 Remove the dependency and remove the Application Insights appender from your log4j configuration. No longer needed since Log4j 1.2 is auto-instrumented in the 3.x Java agent.
applicationinsights-logging-log4j2 Remove the dependency and remove the Application Insights appender from your log4j configuration. No longer needed since Log4j 2 is auto-instrumented in the 3.x Java agent.
applicationinsights-logging-log4j1_2 Remove the dependency and remove the Application Insights appender from your logback configuration. No longer needed since Logback is auto-instrumented in the 3.x Java agent.
applicationinsights-spring-boot-starter Replace with 3.4.3 or later of applicationinsights-web The cloud role name will no longer default to spring.application.name, see the 3.x configuration docs for configuring the cloud role name.

Step 2: Add the 3.x Java agent

Add the 3.x Java agent to your JVM command-line args, for example

-javaagent:path/to/applicationinsights-agent-3.4.4.jar

If you were using the Application Insights 2.x Java agent, just replace your existing -javaagent:... with the above.

Note

If you were using the spring-boot-starter and if you prefer, there is an alternative to using the Java agent. See 3.x Spring Boot.

Step 3: Configure your Application Insights connection string

See configuring the connection string.

Additional notes

The rest of this document describes limitations and changes that you may encounter when upgrading from 2.x to 3.x, as well as some workarounds that you may find helpful.

TelemetryInitializers and TelemetryProcessors

The 2.x SDK TelemetryInitializers and TelemetryProcessors will not be run when using the 3.x agent. Many of the use cases that previously required these can be solved in Application Insights Java 3.x by configuring custom dimensions or configuring telemetry processors.

Multiple applications in a single JVM

This use case is supported in Application Insights Java 3.x using Instrumentation key overrides (preview).

Note

On March 31, 2025, support for instrumentation key ingestion will end. Instrumentation key ingestion will continue to work, but we'll no longer provide updates or support for the feature. Transition to connection strings to take advantage of new capabilities.

Operation names

In the Application Insights Java 2.x SDK, in some cases, the operation names contained the full path, for example

Screenshot showing operation names with full path

Operation names in Application Insights Java 3.x have changed to generally provide a better aggregated view in the Application Insights Portal U/X, for example

Screenshot showing operation names parameterized

However, for some applications, you may still prefer the aggregated view in the U/X that was provided by the previous operation names, in which case you can use the telemetry processors (preview) feature in 3.x to replicate the previous behavior.

The snippet below configures 3 telemetry processors that combine to replicate the previous behavior. The telemetry processors perform the following actions (in order):

  1. The first telemetry processor is an attribute processor (has type attribute), which means it applies to all telemetry that has attributes (currently requests and dependencies, but soon also traces).

    It will match any telemetry that has attributes named http.method and http.url.

    Then it will extract the path portion of the http.url attribute into a new attribute named tempName.

  2. The second telemetry processor is a span processor (has type span), which means it applies to requests and dependencies.

    It will match any span that has an attribute named tempPath.

    Then it will update the span name from the attribute tempPath.

  3. The last telemetry processor is an attribute processor, same type as the first telemetry processor.

    It will match any telemetry that has an attribute named tempPath.

    Then it will delete the attribute named tempPath, so that it won't be reported as a custom dimension.

{
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "http.method" },
            { "key": "http.url" }
          ]
        },
        "actions": [
          {
            "key": "http.url",
            "pattern": "https?://[^/]+(?<tempPath>/[^?]*)",
            "action": "extract"
          }
        ]
      },
      {
        "type": "span",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "tempPath" }
          ]
        },
        "name": {
          "fromAttributes": [ "http.method", "tempPath" ],
          "separator": " "
        }
      },
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "tempPath" }
          ]
        },
        "actions": [
          { "key": "tempPath", "action": "delete" }
        ]
      }
    ]
  }
}