Skip to content

Latest commit

 

History

History
421 lines (312 loc) · 15.2 KB

java-in-process-agent.md

File metadata and controls

421 lines (312 loc) · 15.2 KB
title description ms.topic ms.date author ms.custom ms.author
Azure Monitor Application Insights Java
Application performance monitoring for Java applications running in any environment without requiring code modification. Distributed tracing and application map.
conceptual
06/24/2021
MS-jgol
devx-track-java
jgol

Java codeless application monitoring Azure Monitor Application Insights

Note

If you are looking for the old 2.x docs, go here.

Java codeless application monitoring is all about simplicity - there are no code changes, the Java agent can be enabled through just a couple of configuration changes.

The Java agent works in any environment, and allows you to monitor all of your Java applications. In other words, whether you are running your Java apps on VMs, on-premises, in AKS, on Windows, Linux - you name it, the Application Insights Java agent will monitor your app.

Adding the Application Insights Java 2.x SDK to your application is no longer required, as the Application Insights Java 3.x agent auto-collects requests, dependencies and logs all on its own.

You can still send custom telemetry from your application. The 3.x agent will track and correlate it along with all of the auto-collected telemetry.

The 3.x agent supports Java 8 and above.

Quickstart

1. Download the agent

Warning

If you are 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.

Warning

If you are 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 unprefixed values. See the 3.1.0 release notes for more details.

Download applicationinsights-agent-3.1.1.jar

2. Point the JVM to the agent

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

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

3. Point the agent to your Application Insights resource

If you do not already have an Application Insights resource, you can create a new one by following the steps in the resource creation guide.

Point the agent 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.1.1.jar, with the following content:

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

You can find your connection string in your Application Insights resource:

:::image type="content" source="media/java-ipa/connection-string.png" alt-text="Application Insights Connection String":::

4. That's it!

Now start up your application and go to your Application Insights resource in the Azure portal to see your monitoring data.

Note

It may take a couple of minutes for your monitoring data to show up in the portal.

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.

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 and HttpAsyncClient
  • gRPC
  • java.net.HttpURLConnection
  • 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 (preview)

See the configuration options to enable this preview feature and auto-collect the telemetry emitted by these Azure SDKs:

Send custom telemetry from your application

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, and any type of the custom telemetry is supported through the Application Insights Java 2.x SDK.

Micrometer Log4j, logback, JUL 2.x SDK
Custom Events Yes
Custom Metrics Yes Yes
Dependencies Yes
Exceptions Yes Yes
Page Views Yes
Requests 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);
}

Add request custom dimensions using the 2.x SDK

Note

This feature is only in 3.0.2 and later

Add applicationinsights-web-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-web</artifactId>
  <version>2.6.3</version>
</dependency>

and add custom dimensions in your code:

import com.microsoft.applicationinsights.web.internal.ThreadContext;

RequestTelemetry requestTelemetry = ThreadContext.getRequestTelemetryContext().getHttpRequestTelemetry();
requestTelemetry.getProperties().put("mydimension", "myvalue");

Set the request telemetry user_Id using the 2.x SDK

Note

This feature is only in 3.0.2 and later

Add applicationinsights-web-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-web</artifactId>
  <version>2.6.3</version>
</dependency>

and set the user_Id in your code:

import com.microsoft.applicationinsights.web.internal.ThreadContext;

RequestTelemetry requestTelemetry = ThreadContext.getRequestTelemetryContext().getHttpRequestTelemetry();
requestTelemetry.getContext().getUser().setId("myuser");

Override the request telemetry name using the 2.x SDK

Note

This feature is only in 3.0.2 and later

Add applicationinsights-web-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-web</artifactId>
  <version>2.6.3</version>
</dependency>

and set the name in your code:

import com.microsoft.applicationinsights.web.internal.ThreadContext;

RequestTelemetry requestTelemetry = ThreadContext.getRequestTelemetryContext().getHttpRequestTelemetry();
requestTelemetry.setName("myname");

Get the request telemetry Id and the operation Id using the 2.x SDK

Note

This feature is only in 3.0.3 and later

Add applicationinsights-web-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-web</artifactId>
  <version>2.6.3</version>
</dependency>

and get the request telemetry Id and the operation Id in your code:

import com.microsoft.applicationinsights.web.internal.ThreadContext;

RequestTelemetry requestTelemetry = ThreadContext.getRequestTelemetryContext().getHttpRequestTelemetry();
String requestId = requestTelemetry.getId();
String operationId = requestTelemetry.getContext().getOperation().getId();