Azure Monitor OpenTelemetry-based auto-instrumentation for Java applications

This article describes how to enable and configure the OpenTelemetry-based Azure Monitor Java offering. When you complete the instructions in this article, you’ll be able to use Azure Monitor Application Insights to monitor your application.

Get started

Java auto-instrumentation can be enabled without any code changes.

Prerequisites

Enable Azure Monitor Application Insights

1. Download the auto-instrumentation jar file

1. Download jar file

Download the applicationinsights-agent-3.2.1.jar file.

Warning

  • If you're upgrading from 3.0 Preview

    Please review all the configuration options carefully, as the json structure has completely changed, in addition to the file name itself which went all lowercase.

  • If you're upgrading from 3.0.x

    The operation names and request telemetry names are now prefixed by the http method (GET, POST, etc.). This can affect custom dashboards or alerts if they relied on the previous values. See the 3.1.0 release notes for more details.

  • If you're upgrading from 3.1.x

    Database dependency names are now more concise, with the full (sanitized) query still present in the data field. And HTTP dependency names are now more descriptive. This can affect custom dashboards or alerts if they relied on the previous values. See the 3.2.0 release notes for more details.

2. Point the JVM to the jar file

Add -javaagent:path/to/applicationinsights-agent-3.2.1.jar to your application's JVM args.

Tip

For help with configuring your application's JVM args, see Tips for updating your JVM args.

3. Set Application Insights connection string

Point the jar file to your Application Insights resource, either by setting an environment variable:

APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=...

Or by creating a configuration file named applicationinsights.json, and placing it in the same directory as applicationinsights-agent-3.2.1.jar, with the following content:

{
  "connectionString": "InstrumentationKey=..."
}

Find the connection string on your Application Insights Resource.

Application Insights connection string

4. Confirm data is flowing

Run your application and open your Application Insights Resource tab on the Azure portal. It may take a few minutes for data to show up in the portal.

Note

If you're not able to run the application or not getting data as expected, please go to Troubleshooting.

Screenshot of Application Insights Overview tab with server requests and server response time highlighted.

Important

If you have two or more services emitting telemetry to the same Application Insights resource, you are required to set cloud role names to represent them properly on the Application Map.

Note

As part of using Application Insights instrumentation, we collect and send diagnostic data to Microsoft. This data helps us run and improve Application Insights. You have the option to disable non-essential data collection. Learn More.

Configuration options

In the applicationinsights.json file, you can additionally configure:

  • Cloud role name
  • Cloud role instance
  • Sampling
  • JMX metrics
  • Custom dimensions
  • Telemetry processors (preview)
  • Auto-collected logging
  • Auto-collected Micrometer metrics (including Spring Boot Actuator metrics)
  • Heartbeat
  • HTTP Proxy
  • Self-diagnostics

See configuration options for full details.

Instrumentation libraries

Java 3.X includes the following instrumentation libraries.

Auto-collected requests

  • JMS Consumers
  • Kafka Consumers
  • Netty/WebFlux
  • Servlets
  • Spring Scheduling

Auto-collected dependencies

Auto-collected dependencies plus downstream distributed trace propagation:

  • Apache HttpClient
  • Apache HttpAsyncClient
  • AsyncHttpClient
  • Google HttpClient
  • gRPC
  • java.net.HttpURLConnection
  • Java 11 HttpClient
  • JAX-RS Client
  • Jetty HttpClient
  • JMS
  • Kafka
  • Netty client
  • OkHttp

Auto-collected dependencies (without downstream distributed trace propagation):

  • Cassandra
  • JDBC
  • MongoDB (async and sync)
  • Redis (Lettuce and Jedis)

Auto-collected logs

  • java.util.logging
  • Log4j (including MDC properties)
  • SLF4J/Logback (including MDC properties)

Auto-collected metrics

  • Micrometer (including Spring Boot Actuator metrics)
  • JMX Metrics

Azure SDKs

Telemetry emitted by these Azure SDKs is auto-collected by default:

Modify telemetry

Add span attributes

You may use opentelemetry-api to add attributes to spans. These attributes may include adding a custom business dimension to your telemetry. You may also use attributes to set optional fields in the Application Insights Schema such as User ID or Client IP.

Add custom dimension

Adding one or more custom dimensions will populate the customDimensions field in the requests, dependencies, and/or exceptions table.

Note

This feature is only in 3.2.0 and later

Add opentelemetry-api-1.6.0.jar to your application

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.6.0</version>
</dependency>

and add custom dimensions in your code:

import io.opentelemetry.api.trace.Span;

Span.current().setAttribute("mycustomdimension", "myvalue1");

Set user ID

Populate the user ID field in the requests, dependencies, and/or exceptions table.

Important

Consult applicable privacy laws before setting Authenticated User ID.

Note

This feature is only in 3.2.0 and later

Add opentelemetry-api-1.6.0.jar to your application

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.6.0</version>
</dependency>

and set the user_Id in your code:

import io.opentelemetry.api.trace.Span;

Span.current().setAttribute("enduser.id", "myuser");

Get trace ID or span ID

You may use opentelemetry-api to get trace ID or span ID. This may be done to add these identifiers to existing logging telemetry to improve correlation when debugging and diagnosing issues.

Note

This feature is only in 3.2.0 and later

Add opentelemetry-api-1.6.0.jar to your application

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.6.0</version>
</dependency>

and get the request trace ID and the span ID in your code:

import io.opentelemetry.api.trace.Span;

String traceId = Span.current().getSpanContext().getTraceId();
String spanId = Span.current().getSpanContext().getSpanId();

Custom telemetry

Our goal in Application Insights Java 3.x is to allow you to send your custom telemetry using standard APIs.

We support Micrometer, popular logging frameworks, and the Application Insights Java 2.x SDK so far. Application Insights Java 3.x automatically captures the telemetry sent through these APIs, and correlates it with auto-collected telemetry.

Supported custom telemetry

The table below represents currently supported custom telemetry types that you can enable to supplement the Java 3.x agent. To summarize, custom metrics are supported through micrometer, custom exceptions and traces can be enabled through logging frameworks, custom requests, dependencies, and exceptions can be enabled through opentelemetry-api and any type of the custom telemetry is supported through the Application Insights Java 2.x SDK.

Micrometer Log4j, logback, JUL 2.x SDK opentelemetry-api
Custom Events Yes
Custom Metrics Yes Yes
Dependencies Yes Yes
Exceptions Yes Yes Yes
Page Views Yes
Requests Yes Yes
Traces Yes Yes

We're not planning to release an SDK with Application Insights 3.x at this time.

Application Insights Java 3.x is already listening for telemetry that is sent to the Application Insights Java 2.x SDK. This functionality is an important part of the upgrade story for existing 2.x users, and it fills an important gap in our custom telemetry support until the OpenTelemetry API is GA.

Send custom metrics using Micrometer

Add Micrometer to your application:

<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-core</artifactId>
  <version>1.6.1</version>
</dependency>

Use the Micrometer global registry to create a meter:

static final Counter counter = Metrics.counter("test_counter");

and use that to record metrics:

counter.increment();

Send custom traces and exceptions using your favorite logging framework

Log4j, Logback, and java.util.logging are auto-instrumented, and logging performed via these logging frameworks is auto-collected as trace and exception telemetry.

By default, logging is only collected when that logging is performed at the INFO level or above. See the configuration options for how to change this level.

If you want to attach custom dimensions to your logs, you can use Log4j 1.2 MDC, Log4j 2 MDC, or Logback MDC, and Application Insights Java 3.x will automatically capture those MDC properties as custom dimensions on your trace and exception telemetry.

Send custom telemetry using the 2.x SDK

Add applicationinsights-core-2.6.3.jar to your application (all 2.x versions are supported by Application Insights Java 3.x, but it's worth using the latest if you have a choice):

<dependency>
  <groupId>com.microsoft.azure</groupId>
  <artifactId>applicationinsights-core</artifactId>
  <version>2.6.3</version>
</dependency>

Create a TelemetryClient:

static final TelemetryClient telemetryClient = new TelemetryClient();

and use that to send custom telemetry:

Events
telemetryClient.trackEvent("WinGame");
Metrics
telemetryClient.trackMetric("queueLength", 42.0);
Dependencies
boolean success = false;
long startTime = System.currentTimeMillis();
try {
    success = dependency.call();
} finally {
    long endTime = System.currentTimeMillis();
    RemoteDependencyTelemetry telemetry = new RemoteDependencyTelemetry();
    telemetry.setSuccess(success);
    telemetry.setTimestamp(new Date(startTime));
    telemetry.setDuration(new Duration(endTime - startTime));
    telemetryClient.trackDependency(telemetry);
}
Logs
telemetryClient.trackTrace(message, SeverityLevel.Warning, properties);
Exceptions
try {
    ...
} catch (Exception e) {
    telemetryClient.trackException(e);
}

Troubleshooting

See Troubleshooting.

Support

OpenTelemetry feedback

Next steps