Configure Azure Monitor Application Insights for Java

This article shows you how to configure Azure Monitor Application Insights for Java. For more information, see Get started with OpenTelemetry.

Configure the Java agent

JSON configuration source

Custom dimensions

If you want to add custom dimensions to all your telemetry:

{
 "customDimensions": {
 "mytag": "my value",
 "anothertag": "${ANOTHER_VALUE}"
 }
}

You can use ${...} to read the value from the specified environment variable at startup.

Inherited attributes (preview)

You can set a custom dimension programmatically on your request telemetry. It ensures inheritance by dependency and log telemetry. All are captured in the context of that request.

{
 "preview": {
 "inheritedAttributes": [
 {
 "key": "mycustomer",
 "type": "string"
 }
 ]
 }
}

And then at the beginning of each request, call:

Span.current().setAttribute("mycustomer", "xyz");

See also Add a custom property to a Span.

Configure sampling overrides

Sampling overrides allow you to override the default sampling percentage. For example, you can:

• Set the sampling percentage to 0, or some small value, for noisy health checks.
• Set the sampling percentage to 0, or some small value, for noisy dependency calls.
• Set the sampling percentage to 100 for an important request type. For example, you can use /login even though you have the default sampling configured to something lower.

Sampling overrides terminology

Before you learn about sampling overrides, you should understand the term span.

A span is a type of telemetry that represents one of the following:

• An incoming request.
• An outgoing dependency (for example, a remote call to another service).
• An in-process dependency (for example, work being done by subcomponents of the service).

For sampling overrides, these span components are important:

• Attributes

The span attributes represent both standard and custom properties of a given request or dependency.

Getting started with sampling overrides

To begin, create a configuration file named applicationinsights.json. Save it in the same directory as applicationinsights-agent-*.jar. Use the following template.

{
 "connectionString": "...",
 "sampling": {
 "percentage": 10,
 "overrides": [
 {
 "telemetryType": "request",
 "attributes": [
 ...
 ],
 "percentage": 0
 },
 {
 "telemetryType": "request",
 "attributes": [
 ...
 ],
 "percentage": 100
 }
 ]
 }
}

How sampling overrides work

telemetryType (telemetryKind in Application Insights 3.4.0) must be one of request, dependency, trace (log), or exception.

When a span is started, the type of span and the attributes present on it at that time are used to check if any of the sampling overrides match. Matches can be either strict or regexp. Regular expression matches are performed against the entire attribute value, so if you want to match a value that contains abc anywhere in it, then you need to use .*abc.*.

A sampling override can specify multiple attribute criteria, in which case all of them must match for the sampling override to match. If one of the sampling overrides matches, then its sampling percentage is used to decide whether to sample the span or not.

Only the first sampling override that matches is used. If no sampling overrides match:

• If it's the first span in the trace, then the top-level sampling configuration is used.
• If it isn't the first span in the trace, then the parent sampling decision is used.

Span attributes available for sampling

OpenTelemetry span attributes are autocollected and based on the OpenTelemetry semantic conventions.

You can also programmatically add span attributes and use them for sampling.

Sampling override use cases

Expand any of the following use cases to view the sample configuration.

Sampling overrides troubleshooting

See the dedicated troubleshooting article.

Sampling overrides FAQ

To review frequently asked questions (FAQ), see Sampling overrides FAQ.

Configure telemetry collection

In this section:

• Configure JMX metrics
• Autocollect logging
• Autocollected Micrometer metrics (including Spring Boot Actuator metrics)
• Autocollect InProc dependencies (preview)
• Browser SDK Loader (preview)

Configure JMX metrics

How to collect extra JMX metrics

Application Insights Java 3.x collects some of the Java Management Extensions (JMX) metrics by default, but in many cases it isn't enough. This section describes the JMX configuration option in detail.

JMX metrics collection can be configured by adding a "jmxMetrics" section to the applicationinsights.json file. Enter a name for the metric as you want it to appear in Azure portal in your Application Insights resource. Object name and attribute are required for each of the metrics you want collected. You may use * in object names for glob-style wildcard.

How to know what metrics are available to configure

Properties like object names and attributes are different for various libraries, frameworks, and application servers, and are often not well documented.

To view the available JMX metrics for your particular environment, set the self-diagnostics level to DEBUG in your applicationinsights.json configuration file, for example:

{
 "selfDiagnostics": {
 "level": "DEBUG"
 }
}

Available JMX metrics, with object names and attribute names, appear in your Application Insights log file.

Log file output looks similar to these examples. In some cases, it can be extensive.

👁 Screenshot of available JMX metrics in the log file.

You can also use a command line tool to check the available JMX metrics.

JMX configuration example

Knowing what metrics are available, you can configure the agent to collect them.

"jmxMetrics": [
 {
 "name": "Demo - GC Thread Count",
 "objectName": "java.lang:type=GarbageCollector,name=PS MarkSweep",
 "attribute": "LastGcInfo.GcThreadCount"
 },
 {
 "name": "Demo - GC Collection Count",
 "objectName": "java.lang:type=GarbageCollector,name=PS MarkSweep",
 "attribute": "CollectionCount"
 },
 {
 "name": "Demo - Thread Count",
 "objectName": "java.lang:type=Threading",
 "attribute": "ThreadCount"
 }
]

"jmxMetrics": [
 {
 "name": "Demo - G1 Collection Count Young",
 "objectName": "java.lang:name=G1 Young Generation,type=GarbageCollector",
 "attribute": "CollectionCount"
 },
 {
 "name": "Demo - G1 Collection Count Old",
 "objectName": "java.lang:name=G1 Old Generation,type=GarbageCollector",
 "attribute": "CollectionCount"
 },
 {
 "name": "Demo - Thread Count",
 "objectName": "java.lang:type=Threading",
 "attribute": "ThreadCount"
 }
]

If you want to collect some other Java Management Extensions (JMX) metrics:

{
 "jmxMetrics": [
 {
 "name": "JVM uptime (millis)",
 "objectName": "java.lang:type=Runtime",
 "attribute": "Uptime"
 },
 {
 "name": "MetaSpace Used",
 "objectName": "java.lang:type=MemoryPool,name=Metaspace",
 "attribute": "Usage.used"
 }
 ]
}

In the preceding configuration example:

• name is the metric name that is assigned to this JMX metric (can be anything).
• objectName is the Object Name of the JMX MBean that you want to collect. Wildcard character asterisk (*) is supported.
• attribute is the attribute name inside of the JMX MBean that you want to collect.

Numeric and boolean JMX metric values are supported. Boolean JMX metrics are mapped to 0 for false and 1 for true.

Where to find JMX metrics in Application Insights

You can view the JMX metrics collected while your application is running by navigating to your Application Insights resource in the Azure portal. On the Metrics pane, select the dropdown as shown to view the metrics.

👁 Screenshot of the Metrics pane in the Azure portal.

Autocollect logging

Log4j, Logback, JBoss Logging, and java.util.logging are autoinstrumented. Logging performed via these logging frameworks is autocollected.

Logging is only captured if it:

• Meets the configured level for the logging framework.
• Also meets the configured level for Application Insights.

For example, if your logging framework is configured to log WARN (and you configured it as described earlier) from the package com.example, and Application Insights is configured to capture INFO (and you configured as described), Application Insights only captures WARN (and more severe) from the package com.example.

The default level configured for Application Insights is INFO. If you want to change this level:

{
 "instrumentation": {
 "logging": {
 "level": "WARN"
 }
 }
}

You can also set the level by using the environment variable APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL. It then takes precedence over the level specified in the JSON configuration.

You can use these valid level values to specify in the applicationinsights.json file. The table shows how they correspond to logging levels in different logging frameworks.

union traces, (exceptions | extend message = outerMessage)
| project timestamp, message, itemType

Log markers (preview)

Starting from 3.4.2, you can capture the log markers for Logback and Log4j 2:

{
 "preview": {
 "captureLogbackMarker": true,
 "captureLog4jMarker": true
 }
}

Other log attributes for Logback (preview)

Starting from 3.4.3, you can capture FileName, ClassName, MethodName, and LineNumber, for Logback:

{
 "preview": {
 "captureLogbackCodeAttributes": true
 }
}

Logging level as a custom dimension

Starting with Java agent version 3.3.0, LoggingLevel isn't captured by default as part of the Traces custom dimension because that data is already captured in the SeverityLevel field.

If needed, you can temporarily re-enable the previous behavior:

{
 "preview": {
 "captureLoggingLevelAsCustomDimension": true
 }
}

Autocollected Micrometer metrics (including Spring Boot Actuator metrics)

If your application uses Micrometer, metrics that are sent to the Micrometer global registry are autocollected.

If your application uses Spring Boot Actuator, metrics configured by Spring Boot Actuator are also autocollected.

Send custom metrics using Micrometer

1. Add Micrometer to your application as shown in the following example.

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

2. Use the Micrometer global registry to create a meter as shown in the following example.

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

3. Use the counter to record metrics by using the following command.

   counter.increment();
   

4. The metrics are ingested into the customMetrics table, with tags captured in the customDimensions column. You can also view the metrics in the metrics explorer under the Log-based metrics metric namespace.

   Note

   Application Insights Java replaces all nonalphanumeric characters (except dashes) in the Micrometer metric name with underscores. As a result, the preceding test.counter metric will show up as test_counter.

Disable metrics autocollection

To disable autocollection of Micrometer metrics and Spring Boot Actuator metrics:

{
 "instrumentation": {
 "micrometer": {
 "enabled": false
 }
 }
}

Autocollect InProc dependencies (preview)

If you want to capture controller "InProc" dependencies, use the following configuration:

{
 "preview": {
 "captureControllerSpans": true
 }
}

Browser SDK Loader (preview)

This feature automatically injects the Browser SDK Loader into your application's HTML pages, including configuring the appropriate Connection String.

For example, when your Java application returns a response like:

<!DOCTYPE html>
<html lang="en">
 <head>
 <title>Title</title>
 </head>
 <body>
 </body>
</html>

The reponse is modified as follows:

<!DOCTYPE html>
<html lang="en">
 <head>
 <script type="text/javascript">
 !function(v,y,T){var S=v.location,k="script"
 <!-- Removed for brevity -->
 connectionString: "YOUR_CONNECTION_STRING"
 <!-- Removed for brevity --> }});
 </script>
 <title>Title</title>
 </head>
 <body>
 </body>
</html>

The script helps collect client-side web telemetry and sends it together with server-side telemetry to the user's Azure portal. Details can be found at ApplicationInsights-JS.

If you want to enable this feature, add the below configuration option:

{
 "preview": {
 "browserSdkLoader": {
 "enabled": true
 }
 }
}

Configure telemetry processors (preview)

You can use telemetry processors to configure rules that are applied to request, dependency, and trace telemetry. Application Insights Java 3.x can process telemetry data before the data is exported.

Use cases:

• Mask sensitive data.
• Conditionally add custom dimensions.
• Update the span name, which is used to aggregate similar telemetry in the Azure portal.
• Drop specific span attributes to control ingestion costs.
• Filter out some metrics to control ingestion costs.

If you are looking to drop specific (whole) spans for controlling ingestion cost, see Configure sampling overrides.

Telemetry processors terminology

Before you learn about telemetry processors, you should understand the terms span and log.

A span is a type of telemetry that represents one of the following:

• An incoming request.
• An outgoing dependency (for example, a remote call to another service).
• An in-process dependency (for example, work being done by subcomponents of the service).

A log is a type of telemetry that represents:

• log data captured from Log4j, Logback, and java.util.logging

For telemetry processors, the following span/log components are important:

Types of telemetry processors

Currently, the four types of telemetry processors are:

Getting started with telemetry processors

To begin, create a configuration file named applicationinsights.json. Save it in the same directory as applicationinsights-agent-*.jar. Use the following template.

{
 "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
 "preview": {
 "processors": [
 {
 "type": "attribute",
 ...
 },
 {
 "type": "span",
 ...
 },
 {
 "type": "log",
 ...
 },
 {
 "type": "metric-filter",
 ...
 }
 ]
 }
}

"processors": [
 {
 "type": "span",
 "name": {
 "fromAttributes": [
 "attributeKey1",
 "attributeKey2",
 ],
 "separator": "::"
 }
 }
] 

"processors": [
 {
 "type": "span",
 "name": {
 "toAttributes": {
 "rules": [
 "rule1",
 "rule2",
 "rule3"
 ]
 }
 }
 }
]

"processors": [
 {
 "type": "log",
 "body": {
 "fromAttributes": [
 "attributeKey1",
 "attributeKey2",
 ],
 "separator": "::"
 }
 }
] 

"processors": [
 {
 "type": "log",
 "body": {
 "toAttributes": {
 "rules": [
 "rule1",
 "rule2",
 "rule3"
 ]
 }
 }
 }
]

Telemetry processor samples

"processors": [
 {
 "type": "attribute",
 "include": {
 "matchType": "strict",
 "spanNames": [
 "spanA",
 "spanB"
 ]
 },
 "exclude": {
 "matchType": "strict",
 "attributes": [
 {
 "key": "redact_trace",
 "value": "false"
 }
 ]
 },
 "actions": [
 {
 "key": "credit_card",
 "action": "delete"
 },
 {
 "key": "duplicate_key",
 "action": "delete"
 }
 ]
 }
]

"processors": [
 {
 "type": "span",
 "include": {
 "matchType": "strict",
 "spanNames": [
 "spanA",
 "spanB"
 ]
 },
 "exclude": {
 "matchType": "strict",
 "attributes": [
 {
 "key": "attribute1",
 "value": "attributeValue1"
 }
 ]
 },
 "name": {
 "toAttributes": {
 "rules": [
 "rule1",
 "rule2",
 "rule3"
 ]
 }
 }
 }
]

"processors": [
 {
 "type": "log",
 "include": {
 "matchType": "strict",
 "attributes": [
 {
 "key": "attribute1",
 "value": "value1"
 }
 ]
 },
 "exclude": {
 "matchType": "strict",
 "attributes": [
 {
 "key": "attribute2",
 "value": "value2"
 }
 ]
 },
 "body": {
 "toAttributes": {
 "rules": [
 "rule1",
 "rule2",
 "rule3"
 ]
 }
 }
 }
]

"processors": [
 {
 "type": "metric-filter",
 "exclude": {
 "matchType": "strict",
 "metricNames": [
 "metricA",
 "metricB"
 ]
 }
 }
]

"processors": [
 {
 "type": "metric-filter",
 "exclude": {
 "matchType": "regexp",
 "metricNames": [
 ".*"
 ]
 }
 }
]

Include and exclude span samples

Expand the sections below to view various include and exclude span samples.

Telemetry processors FAQ

To review frequently asked questions (FAQ), see Telemetry processors FAQ

Override or suppress default behavior

In this section:

• Connection string overrides (preview)
• Cloud role name overrides (preview)
• Configure the connection string at runtime
• Locally disable ingestion sampling (preview)

Connection string overrides (preview)

This feature is in preview, starting from 3.4.0.

Connection string overrides allow you to override the default connection string. For example, you can:

• Set one connection string for one HTTP path prefix /myapp1.
• Set another connection string for another HTTP path prefix /myapp2/.

{
 "preview": {
 "connectionStringOverrides": [
 {
 "httpPathPrefix": "/myapp1",
 "connectionString": "..."
 },
 {
 "httpPathPrefix": "/myapp2",
 "connectionString": "..."
 }
 ]
 }
}

Cloud role name overrides (preview)

This feature is in preview, starting from 3.3.0.

Cloud role name overrides allow you to override the default cloud role name. For example, you can:

• Set one cloud role name for one HTTP path prefix /myapp1.
• Set another cloud role name for another HTTP path prefix /myapp2/.

{
 "preview": {
 "roleNameOverrides": [
 {
 "httpPathPrefix": "/myapp1",
 "roleName": "Role A"
 },
 {
 "httpPathPrefix": "/myapp2",
 "roleName": "Role B"
 }
 ]
 }
}

Configure the connection string at runtime

If you need the ability to configure the connection string at runtime, add this property to your json configuration:

{
 "connectionStringConfiguredAtRuntime": true
}

Add applicationinsights-core to your application:

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

Use the static configure(String) method in the class com.microsoft.applicationinsights.connectionstring.ConnectionString.

Locally disable ingestion sampling (preview)

By default, when the effective sampling percentage in the Java agent is 100% and ingestion sampling has been configured on your Application Insights resource, then the ingestion sampling percentage will be applied.

Note that this behavior applies to both fixed-rate sampling of 100% and also applies to rate-limited sampling when the request rate doesn't exceed the rate limit (effectively capturing 100% during the continuously sliding time window).

Starting from 3.5.3, you can disable this behavior (and keep 100% of telemetry in these cases even when ingestion sampling has been configured on your Application Insights resource):

{
 "preview": {
 "sampling": {
 "ingestionSamplingEnabled": false
 }
 }
}

Protect telemetry data

Query masking

Literal values in Java Database Connectivity (JDBC) and Mongo queries are masked by default to avoid accidentally capturing sensitive data.

Starting from 3.4.0, this behavior can be disabled. For example:

{
 "instrumentation": {
 "jdbc": {
 "masking": {
 "enabled": false
 }
 }
 }
}

{
 "instrumentation": {
 "mongo": {
 "masking": {
 "enabled": false
 }
 }
 }
}

HTTP headers

You can capture request and response headers on your server (request) and client (dependency) telemetry:

{
 "preview": {
 "captureHttpServerHeaders": {
 "requestHeaders": [
 "My-Header-A"
 ],
 "responseHeaders": [
 "My-Header-B"
 ]
 }
 }
}

{
 "preview": {
 "captureHttpClientHeaders": {
 "requestHeaders": [
 "My-Header-C"
 ],
 "responseHeaders": [
 "My-Header-D"
 ]
 }
 }
}

Configure runtime and environment configuration

In this section:

• Authentication
• HTTP proxy
• Metric interval
• Heartbeat
• Recovery from ingestion failures
• Self-diagnostics
• Telemetry correlation

Authentication

You can use authentication to configure the agent to generate token credentials that are required for Microsoft Entra authentication. For more information, see the Microsoft Entra authentication for Application Insights.

HTTP proxy

If your application is behind a firewall and can't connect directly to Application Insights, refer to Azure Monitor endpoint access and firewall configuration.

To work around this issue, you can configure Application Insights Java 3.x to use an HTTP proxy.

{
 "proxy": {
 "host": "myproxy",
 "port": 8080
 }
}

You can also set the http proxy using the environment variable APPLICATIONINSIGHTS_PROXY, which takes the format https://<host>:<port>. It then takes precedence over the proxy specified in the JSON configuration.

You can provide a user and a password for your proxy with the APPLICATIONINSIGHTS_PROXY environment variable: https://<user>:<password>@<host>:<port>.

Application Insights Java 3.x also respects the global https.proxyHost and https.proxyPort system properties if they're set, and http.nonProxyHosts, if needed.

Metric interval

By default, metrics are captured every 60 seconds. You can change this interval:

{
 "metricIntervalSeconds": 300
}

Starting with Java agent version 3.4.9 (GA), you can also set the metricIntervalSeconds by using the environment variable APPLICATIONINSIGHTS_METRIC_INTERVAL_SECONDS. It then takes precedence over the metricIntervalSeconds specified in the JSON configuration.

The setting applies to the following metrics:

• Default performance counters: For example, CPU and memory.
• Default custom metrics: For example, garbage collection timing.
• Configured JMX metrics: See the JMX metric section.
• Micrometer metrics: See the Autocollected Micrometer metrics section.

Heartbeat

By default, Application Insights Java 3.x sends a heartbeat metric once every 15 minutes. If you're using the heartbeat metric to trigger alerts, you can increase the frequency of this heartbeat:

{
 "heartbeat": {
 "intervalSeconds": 60
 }
}

Recovery from ingestion failures

When sending telemetry to the Application Insights service fails, Application Insights Java 3.x stores the telemetry to disk and continues retrying from disk.

The default limit for disk persistence is 50 Mb. If you have high telemetry volume or need to be able to recover from longer network or ingestion service outages, you can increase this limit:

{
 "preview": {
 "diskPersistenceMaxSizeMb": 50
 }
}

Self-diagnostics

"Self-diagnostics" refers to internal logging from Application Insights Java 3.x. This functionality can be helpful for spotting and diagnosing issues with Application Insights itself.

By default, Application Insights Java 3.x logs at level INFO to both the file applicationinsights.log and the console, corresponding to this configuration:

{
 "selfDiagnostics": {
 "destination": "file+console",
 "level": "INFO",
 "file": {
 "path": "applicationinsights.log",
 "maxSizeMb": 5,
 "maxHistory": 1
 }
 }
}

In the preceding configuration example:

• level can be one of OFF, ERROR, WARN, INFO, DEBUG, or TRACE.
• path can be an absolute or relative path. Relative paths are resolved against the directory where applicationinsights-agent-3.7.8.jar is located.

Starting with Java agent version 3.0.2, you can also set the self-diagnostics level by using the environment variable APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_LEVEL. It then takes precedence over the self-diagnostics level specified in the JSON configuration.

Starting with Java agent version 3.0.3, you can also set the self-diagnostics file location by using the environment variable APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_FILE_PATH. It then takes precedence over the self-diagnostics file path specified in the JSON configuration.

Telemetry correlation

Telemetry correlation is enabled by default, but you may disable it in configuration:

{
 "preview": {
 "disablePropagation": true
 }
}

Advanced and preview features

Custom instrumentation (preview)

You can capture spans for a method in your application:

{
 "preview": {
 "customInstrumentation": [
 {
 "className": "my.package.MyClass",
 "methodName": "myMethod"
 }
 ]
 }
}

Preview instrumentations

You can enable the following preview instrumentations:

{
 "preview": {
 "instrumentation": {
 "akka": {
 "enabled": true
 },
 "apacheCamel": {
 "enabled": true
 },
 "grizzly": {
 "enabled": true
 },
 "ktor": {
 "enabled": true
 },
 "play": {
 "enabled": true
 },
 "r2dbc": {
 "enabled": true
 },
 "springIntegration": {
 "enabled": true
 },
 "vertx": {
 "enabled": true
 }
 }
 }
}

Configuration file example

This example shows what a configuration file looks like with multiple components. Configure specific options based on your needs.

{
 "connectionString": "...",
 "role": {
 "name": "my cloud role name"
 },
 "sampling": {
 "percentage": 100
 },
 "jmxMetrics": [
 ],
 "customDimensions": {
 },
 "instrumentation": {
 "logging": {
 "level": "INFO"
 },
 "micrometer": {
 "enabled": true
 }
 },
 "proxy": {
 },
 "preview": {
 "processors": [
 ]
 },
 "selfDiagnostics": {
 "destination": "file+console",
 "level": "INFO",
 "file": {
 "path": "applicationinsights.log",
 "maxSizeMb": 5,
 "maxHistory": 1
 }
 }
}