Java App Insights on Azure: Troubleshoot Like a Pro with This Guide

Table of Contents

Successfully monitoring Java applications on Azure using Application Insights is crucial for maintaining application health and performance. However, various issues can arise during instrumentation and operation, leading to missing telemetry or unexpected behavior. This comprehensive guide provides detailed troubleshooting information to help you diagnose and resolve common problems encountered when leveraging the Application Insights Java agent, a key feature of the Azure Monitor platform service.

Understanding and addressing these challenges efficiently ensures that your Java applications running on Azure provide complete and accurate observability data, enabling you to proactively identify and fix performance bottlenecks or errors. By following the steps outlined below, you can effectively troubleshoot common pitfalls and optimize your application’s monitoring setup.

Checking the Self-Diagnostic Log File¶

The applicationinsights.log file is your primary resource for initial troubleshooting. By default, Application Insights Java 3.x generates this log file in the same directory where the applicationinsights-agent-3.2.11.jar file resides. This log provides critical insights into the agent’s startup process, configuration loading, and any encountered errors.

When faced with issues, this log file should always be the first place you examine. It often contains clear indicators of misconfigurations, permission problems, or network connectivity failures. Regular review of this log can help in early detection of potential monitoring gaps.

If Application Insights fails to generate this log file, the first step is to verify the Java application’s write permissions for the directory containing the applicationinsights-agent-3.2.11.jar file. Insufficient permissions are a common reason for log file creation failures. Ensure the user running the Java application has full write access to this location.

Should the log file still not appear after verifying permissions, direct your attention to the stdout log of your Java application. Application Insights Java 3.x is designed to output any errors preventing it from writing to its designated log file directly to stdout. This mechanism ensures that even severe initial errors are captured and made visible for debugging.

mermaid graph TD A[Java Application Startup] --> B{Application Insights Agent Initialized?}; B -- Yes --> C[Generate applicationinsights.log]; B -- No --> D{Check Write Permissions}; D -- Permissions OK --> E[Output Errors to stdout]; D -- Permissions Denied --> F[Fix Directory Permissions]; C -- Errors/Warnings --> G[Review applicationinsights.log]; E --> G; F --> A;
Figure 1: Application Insights Log File Troubleshooting Flow

Troubleshooting Connectivity Issues¶

Application Insights SDKs and agents transmit telemetry data to ingestion endpoints using REST calls. Connectivity problems between your application host and these endpoints can prevent telemetry from reaching Azure Monitor. To diagnose these issues, you can simulate these REST calls using raw REST clients from PowerShell or curl commands from your server.

This allows you to directly test the network path and firewall rules between your application and the Azure ingestion services. For a more detailed guide on testing connectivity and troubleshooting missing telemetry, refer to the Azure documentation on Troubleshoot missing application telemetry in Azure Monitor Application Insights. Understanding network routing and firewall configurations is paramount here.

If the Application Insights Java agent itself appears to be the root cause of connectivity issues, consider the following troubleshooting steps:

• Verify the Connection String for Application Insights: A common oversight is an incorrect or missing connection string in your Application Insights configuration. Ensure that the connection string, which includes your instrumentation key and ingestion endpoint details, is accurately configured and accessible to the Java agent. Any typos or misconfigurations here will prevent telemetry from being sent.

• Check Java Keystore for Required Certificates (Java 3.4.6+): Application Insights Java version 3.4.6 and later versions can help diagnose SSL certificate issues. To leverage this, enable the self-diagnostics feature at the TRACE level. Look for the following entry in your Application Insights logs: TRACE c.m.applicationinsights.agent - Application Insights root certificate in the Java keystore: false. This message indicates that a necessary root certificate for establishing secure communication with Azure ingestion endpoints is absent from your Java keystore. If this entry appears, you’ll need to import the root certificate as detailed in the “Import SSL certificates” section.

• Review -Djsse.enableSNIExtension=false Usage: The -Djsse.enableSNIExtension=false JVM option disables Server Name Indication (SNI) extension. While this might be necessary in some legacy environments, it can lead to connectivity problems with modern TLS endpoints, including Azure Application Insights. If you’re using Application Insights Java version 3.4.5 or later, and this option is present, you’ll see a warning in your logs: WARN c.m.applicationinsights.agent - System property -Djsse.enableSNIExtension=false is detected. If you have connection issues with Application Insights, please remove this. It’s strongly recommended to remove this option if possible to ensure proper TLS handshake.

• Utilize Additional Troubleshooting Tools: If the above steps do not resolve your connectivity problems, Microsoft provides additional troubleshooting tools and documentation specifically for diagnosing connection issues to the Application Insights backend. These resources can offer more advanced diagnostic techniques and insights into complex network scenarios. Exploring these tools should be your next step for persistent issues.

Java Virtual Machine (JVM) Fails to Start¶

A critical problem that can occur during the instrumentation process is the failure of the Java Virtual Machine (JVM) to start. This often manifests with an error message such as “Error opening zip file or JAR manifest missing.” This indicates a fundamental issue with how the JVM is attempting to load the Application Insights agent’s JAR file. Addressing this immediately is essential to get your application running and monitored.

The table below outlines common causes for this startup failure and their corresponding actions:

Problem	Action
The Java archive (JAR) file for the agent is not found.	Ensure that you have specified a valid and correct agent JAR path in the -javaagent JVM argument. Double-check the path for any typos or incorrect file names. The path should point directly to the applicationinsights-agent-3.2.11.jar file.
The agent JAR file might have been corrupted during file transfer.	If the path is correct, the file itself might be compromised. Try re-downloading the Application Insights agent JAR file from a trusted source. Verify its integrity by comparing checksums if available.

This issue typically indicates that the JVM cannot locate or properly read the agent’s JAR file. Carefully review the -javaagent argument in your JVM startup script. Even a subtle mistake in the file path or name can prevent the agent from loading, thereby causing the JVM to halt. Always ensure the path is absolute or correctly relative to the working directory of your application.

Tomcat Java Apps Take Several Minutes to Start¶

When Application Insights is enabled to monitor a Tomcat application, you might observe a significant delay, sometimes several minutes, in the application’s startup time. This delay is a known behavior caused by Tomcat’s default startup process, during which it attempts to scan all JAR files within its deployment for TLDs (Tag Library Descriptors) and other metadata. This scanning process, while generally useful, becomes a bottleneck when large monitoring agent JARs, like those from Application Insights, are present.

The Application Insights JAR files do not contain content that needs to be scanned by Tomcat during startup. Therefore, including them in the scanning process is an unnecessary overhead that directly contributes to the extended startup times. By explicitly excluding these JARs, you can significantly reduce the time it takes for your Tomcat application to become fully operational, leading to quicker deployments and restarts.

To mitigate this startup delay, you can configure Tomcat to exclude the Application Insights JAR files from its scanning list. This is typically done by modifying the catalina.properties file, which is located in the conf directory of your Tomcat installation. Within this file, you can specify JARs to be ignored during scanning.

Add or modify the tomcat.util.scan.DefaultJarScanner.jarsToSkip property to include the Application Insights agent JAR file. An example modification might look like this:

tomcat.util.scan.DefaultJarScanner.jarsToSkip=\
applicationinsights-agent-3.2.11.jar,another-jar-to-skip.jar

Remember to replace applicationinsights-agent-3.2.11.jar with the exact filename of your deployed Application Insights agent. This configuration change tells Tomcat to bypass scanning these specific JARs, thereby streamlining the startup sequence and enhancing application responsiveness.

Upgrading from Application Insights Java 2.x SDK¶

If your application currently incorporates the Application Insights Java 2.x SDK, you generally do not need to remove it when introducing the Application Insights Java 3.x agent. The 3.x agent is designed for seamless coexistence and provides advanced capabilities for modern Java applications. This backward compatibility ensures a smoother transition for existing monitoring setups.

The Application Insights Java 3.x agent intelligently detects, captures, and correlates any custom telemetry that you send through your existing 2.x SDK. This means your application’s custom metrics, events, and traces, which are already defined using the 2.x SDK, will continue to flow into Application Insights without requiring significant code changes. This feature greatly simplifies the upgrade path, allowing you to leverage the new agent’s benefits while preserving your custom monitoring logic.

Furthermore, the 3.x agent actively prevents duplicate telemetry by suppressing any auto-collection that the 2.x SDK might perform. This intelligent de-duplication ensures that you don’t receive redundant data in Azure Monitor, which can lead to cleaner dashboards, more accurate alerts, and optimized ingestion costs. For a detailed guide on the upgrade process and best practices, consult the official documentation on Upgrade from the Java 2.x SDK. It outlines specific considerations and configuration adjustments to ensure a successful migration.

Upgrading from Application Insights Java 3.0 Preview¶

For users upgrading from the Application Insights Java 3.0 Preview agent to a later General Availability (GA) release, it’s imperative to carefully review all configuration options. The JSON structure of the configuration file underwent significant changes between the preview and GA versions. Neglecting to update your configuration file to reflect these changes can lead to agent malfunction or incorrect telemetry collection.

Several key changes were introduced that require your attention:

• Configuration File Name Change: The name of the primary configuration file was standardized from ApplicationInsights.json (with a capital ‘A’ and ‘I’) to applicationinsights.json (all lowercase). Ensure your deployment uses the correct lowercase filename to be recognized by the GA agent.
• Removal of instrumentationSettings Node: The instrumentationSettings node, which previously encapsulated various configurations, is no longer present in the GA release. All content that was previously nested under instrumentationSettings has been elevated and moved to the root level of the JSON configuration. This flattens the configuration structure, making it potentially easier to read and manage.
• Relocation of Key Configuration Nodes: Configuration nodes such as sampling, jmxMetrics, instrumentation, and heartbeat were previously nested under a preview node in the preview versions. In the GA release, these nodes have also been moved out of the preview section and now reside directly at the root level of the applicationinsights.json file. This change signifies their graduation from preview features to stable, core functionalities.

It is crucial to adapt your applicationinsights.json file according to these structural changes. Reviewing the official documentation for the latest GA version will provide the most accurate and up-to-date schema. Failing to do so might result in the agent failing to load configurations, leading to a complete absence of monitoring data.

Some Logging Isn’t Auto-Collected¶

When configuring Application Insights to auto-collect logging data, it’s important to understand that logs are only captured if they meet a dual set of criteria. This involves both the logging level configured within your application’s logging framework and the level configured for Application Insights itself. Discrepancies between these two settings can lead to logging data being missed in Azure Monitor.

For instance, if your application’s logging framework (e.g., Log4j, Logback) is configured to log WARN level messages (and above) from a specific package like com.example, and Application Insights is simultaneously configured to capture INFO level messages (and above), then only WARN level messages (and above) from the com.example package will actually be collected and sent to Azure. Any INFO messages from com.example will be filtered out by the logging framework before Application Insights can even process them.

To confirm that a particular logging statement is meeting your logging framework’s configured threshold, verify that it appears in your application’s usual log output, whether that’s to a file or the console. If a log message isn’t visible there, it means your application’s logging framework is already filtering it out, and Application Insights will not receive it. Adjust your logging framework’s configuration if you need to capture lower-level messages.

A crucial point to note is the handling of exceptions within log messages. If an exception object is passed to the logger along with the log message, the entire log entry, including the log message and detailed exception information, will appear in the exceptions table in the Azure portal, rather than the traces table. This distinction helps categorize and analyze error conditions separately.

To view all your log messages, encompassing both standard traces and exception-related logs, you can run the following Kusto query in Azure Logs (Kusto):

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

This query combines data from both tables, standardizes the message field, and presents a unified view of your application’s logging activity. For comprehensive details on configuring auto-collected logging and understanding various options, refer to the auto-collected logging configuration documentation. This section provides insights into fine-tuning logging levels and destinations within Application Insights.

Importing SSL Certificates¶

Secure Sockets Layer (SSL) certificate-related exceptions are a common cause of connectivity issues when using the Java agent. These exceptions typically arise when the Java Virtual Machine (JVM) cannot establish a secure connection to the Application Insights ingestion endpoints due to an inability to validate the server’s SSL certificate. Resolving these issues is critical for ensuring encrypted and reliable telemetry transmission.

There are two primary scenarios for resolving SSL certificate problems, depending on your JVM’s keystore configuration:
1. Using a Default Java Keystore: This is the most common scenario for many Java applications.
2. Using a Custom Java Keystore: This occurs when applications explicitly define a custom keystore for certificate management.

To determine which path to follow, inspect your JVM arguments for -Djavax.net.ssl.trustStore=.... If this argument is present, you are likely using a custom keystore, and the argument points to its location. If absent, your JVM is probably relying on the default Java keystore.

If You’re Using the Default Java Keystore¶

The default Java keystore, typically located at $JAVA_HOME/jre/lib/security/cacerts, usually contains a broad collection of trusted CA root certificates. However, sometimes the specific root certificate used to sign the Application Insights endpoint’s certificate might be missing or an older version. Follow these steps to diagnose and resolve this:

1. List Existing Certificates: Begin by listing the certificates already present in your default keystore. Use the keytool command:
   

   keytool -list -v -keystore $JAVA_HOME/jre/lib/security/cacerts > temp.txt
   

   
   This command outputs all certificate details to temp.txt, making it easier to search through later.

2. Download and Verify Application Insights SSL Certificate: Follow the Steps to download the SSL certificate provided below to obtain the certificate used by the Application Insights endpoint. Once downloaded, generate its SHA-1 hash:
   

   keytool -printcert -v -file "<downloaded-ssl-certificate>.cer"
   

   
   Copy the SHA-1 value from the output. Search for this SHA-1 value within your temp.txt file. If the value is not found, the downloaded SSL certificate, or its signing chain, is missing from your default Java keystore.

3. Import the Missing SSL Certificate: If the certificate is missing, import it into the default Java keystore using the following command. You will need to provide the keystore password, which is often ‘changeit’ by default:
   

   keytool -import -file "<downloaded-ssl-certificate-file>" -alias "<some-meaningful-name>" -keystore $JAVA_HOME/jre/lib/security/cacerts
   

   
   Choose a meaningful alias for easy identification. This action securely adds the necessary certificate to your JVM’s trusted store, enabling secure communication with Application Insights.

If You’re Using a Custom Java Keystore¶

If your application utilizes a custom Java keystore, you will need to manually import the SSL certificates for the Application Insights endpoints into that specific keystore. This ensures that your application, when configured to use this custom keystore, can properly validate the secure connections.

1. Download the SSL Certificate: Begin by following the Steps to download the SSL certificate to obtain the necessary certificate from the Application Insights endpoint.
2. Import to Custom Keystore: Once you have the certificate file, import it into your custom Java keystore using the keytool command. Remember to replace placeholders with your specific details:
   

   keytool -importcert -alias <your-ssl-certificate-alias> -file "<your-downloaded-ssl-certificate-name>.cer" -keystore "<your-keystore-name>" -storepass "<your-keystore-password>" -noprompt
   

   
   The -noprompt option is useful for automated scripts, but ensure you understand its implications for security confirmations. This ensures your custom keystore trusts the Azure ingestion endpoints.

Steps to Download the SSL Certificate¶

To obtain the SSL certificate from an Application Insights endpoint, follow these browser-based steps:

1. Open your web browser and navigate to the Application Insights ingestion URL, for example: https://westeurope-5.in.applicationinsights.azure.com/api/ping.
2. In the browser’s address bar, locate and select the View site information icon, which typically appears as a lock symbol next to the URL.
3. Choose the option indicating that the Connection is secure.
4. Select the Show certificate icon or a similar option to open the certificate viewer.
5. Within the Certificate Viewer dialog box, navigate to the Details tab.
6. In the Certificate Hierarchy list, select the specific certificate you wish to download. You may need to download the CA root certificate, any intermediate certificates, and the leaf SSL certificate to build a complete trust chain. Start with the root or intermediate certificates.
7. Click the Export button.
8. In the Save As dialog box, select a directory where you want to save the certificate file (which will typically have a .crt or .cer extension), and then click Save.
9. Finally, close the Certificate Viewer dialog box.

Understanding UnknownHostException¶

Encountering an UnknownHostException after upgrading your Java agent to a version later than 3.2.0 is a common issue with a specific root cause. This exception indicates that your application’s network environment, specifically its DNS resolver, is unable to locate the hostname of the Application Insights ingestion endpoint. This problem is directly related to a change in the endpoint strategy introduced in newer agent versions.

Versions of the Application Insights Java agent greater than 3.2.0 point to a new ingestion endpoint: v2.1/track. This differs from the older v2/track endpoint used in previous versions. The v2.1/track endpoint is designed to automatically redirect telemetry to the ingestion endpoint geographically closest to the storage location of your Application Insights resource. This redirection mechanism enhances performance and reduces latency by optimizing data routing.

The new endpoint used for redirection might be a different hostname than what your network was previously configured to resolve or what your firewalls permit. To resolve the UnknownHostException, you need to ensure that your network configuration, including DNS servers and any proxy settings, is updated to correctly resolve the new endpoint hostname shown in the exception message. This might involve updating DNS records, firewall rules, or proxy configurations to allow traffic to the new, dynamically determined ingestion endpoint. Verifying that your DNS can resolve this new hostname is the primary step to fix this issue.

Missing Cipher Suites¶

If the Application Insights Java agent detects that your Java Virtual Machine (JVM) does not support any of the cipher suites required by the endpoints it connects to, it will issue an alert. This alert typically includes a link or reference to the list of missing cipher suites, providing clear guidance on what needs to be addressed. This issue directly impacts the ability to establish a secure TLS/SSL connection for telemetry transmission.

Background on Cipher Suites¶

Cipher suites are fundamental to establishing secure SSL/TLS connections. Before any client application and server can exchange information securely, they must perform an SSL/TLS handshake. During this handshake, the client application initiates the process by notifying the server of all the cipher suites it supports. A cipher suite is a set of algorithms that define how the secure connection will be established, including authentication, encryption, and message integrity.

The server then receives this list and compares the client’s supported cipher suites with its own set of algorithms. If a compatible cipher suite is found, the server selects one and informs the client, and a secure connection is successfully established using those chosen algorithms. If no common cipher suite can be agreed upon, the server refuses the connection, resulting in a connection failure that prevents telemetry from being sent to Application Insights.

How to Determine Client-Side Cipher Suites¶

In this context, the client refers to the JVM on which your instrumented application is running. Starting from version 3.2.5, Application Insights Java proactively logs a warning message if it detects that missing cipher suites could be causing connection failures to one of its service endpoints. This self-diagnostic capability simplifies the identification of this particular issue.

If you are using an older version of Application Insights Java (prior to 3.2.5), you can manually determine the list of supported cipher suites in your JVM by compiling and running the following Java program:

import javax.net.ssl.SSLServerSocketFactory;

public class Ciphers {
    public static void main(String[] args) {
        SSLServerSocketFactory ssf = (SSLServerSocketFactory) SSLServerSocketFactory.getDefault();
        String[] defaultCiphers = ssf.getDefaultCipherSuites();
        System.out.println("Default\tCipher");
        for (int i = 0; i < defaultCiphers.length; ++i) {
            System.out.print('*');
            System.out.print('\t');
            System.out.println(defaultCiphers[i]);
        }
    }
}

This program prints a list of cipher suites that your current JVM is configured to support by default. You can then compare this list with the required cipher suites for Application Insights endpoints.

The Application Insights endpoints are designed to support a robust set of modern cipher suites to ensure secure communication. The commonly supported cipher suites include:
* TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
* TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
* TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
* TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
Ensure that your JVM’s list of supported ciphers includes at least one of these.

How to Determine Server-Side Cipher Suites¶

The server side, in this scenario, refers to the Application Insights ingestion endpoint or the Live Metrics endpoint. While the above list provides general guidance, you can use online tools to verify the exact cipher suites supported by specific endpoints. Tools like SSLLABS SSL Test allow you to input an endpoint URL and receive a detailed report on its SSL/TLS configuration, including its preferred cipher suites. This can be helpful for in-depth analysis.

How to Add the Missing Cipher Suites¶

If your JVM is missing the required cipher suites, the solution depends on your Java version and distribution:

• Java 9 or Later: If you are using Java 9 or any subsequent version, verify that the JVM installation includes the jdk.crypto.cryptoki module within its jmods folder. This module contains essential cryptographic providers. Furthermore, if you are building a custom Java runtime using jlink, ensure that you explicitly include this jdk.crypto.cryptoki module in your custom image.
• Java 8: For Java 8 and most modern Java 8+ distributions, these cipher suites should generally be available by default. If they are missing, it suggests a potential issue with your Java distribution’s security configuration. We recommend investigating the source of your installed Java distribution to understand why its java.security configuration file might deviate from standard Java distributions, which typically include these common cipher suites. You might need to update your Java installation or specifically enable these providers if they were disabled.

Slow Startup Time in Application Insights¶

Slow startup times for Java applications instrumented with Application Insights can significantly impact deployment cycles and overall system responsiveness. This issue often stems from the agent’s initialization process, which can be resource-intensive or interact poorly with certain JVM versions or application frameworks. Understanding the specific causes for different Java versions is key to applying the correct optimization.

Java 8¶

Java 8 has a known issue related to the JAR file signature verification process when Java agents are involved. This verification, while a security measure, can unfortunately increase the startup time for applications using Application Insights. The agent’s JAR files are signed, and the JVM’s intense verification process for these signatures during startup can introduce considerable latency.

To mitigate this issue when running on Java 8, consider one of the following options:

• Programmatically Attach the Application Insights Java Agent (Spring Boot): If your application is based on Spring Boot, you can programmatically attach the Application Insights Java agent to the JVM. This method often bypasses or optimizes some of the startup overhead associated with static agent attachment, as the agent is integrated differently into the application lifecycle. Consult the Spring Boot documentation for Application Insights for detailed instructions on programmatic attachment.
• Upgrade to Java Version 11 or Later: The signature verification overhead issue experienced in Java 8 was largely addressed and optimized in later Java versions. Upgrading your application’s JVM to Java 11 or a more recent version is often the most effective and straightforward solution to reduce startup times. Newer JVMs offer performance improvements and better handling of agent attachments.

Java Higher Than Version 8¶

Even with Java versions newer than 8, you might still encounter slow startup times, especially with complex applications or under resource-constrained environments. The instrumentation process itself, which involves byte-code modification and extensive monitoring setup, can be demanding.

To address slow startup times in Java versions higher than 8, try one of the following methods:

• Utilize an Azure Configuration with More CPU Power: In cloud environments, the computational resources allocated to your application directly impact startup performance. Scaling up your Azure configuration to include more CPU power can significantly reduce the time it takes for your application and the Application Insights agent to initialize. More powerful VMs can process the startup tasks faster.
• Disable Specific Auto-collected Telemetry: Application Insights auto-collects a wide array of telemetry by default. Some of this auto-collection might not be critical for your specific monitoring needs and can contribute to startup overhead. Review the Suppress specific autocollected telemetry documentation to identify and disable unnecessary instrumentation. This can include features like JMX metrics, specific HTTP request details, or other components you don’t actively use.
• Try the Experimental Startup Time Improvement Feature: The Application Insights Java team has developed an experimental feature specifically aimed at improving startup time for environments with a limited number of CPU cores. This feature attempts to optimize the agent’s initialization under resource constraints. You can find details on this in the Startup time improvement for a limited number of CPU cores (experimental) documentation. If you decide to use this feature, provide feedback to the developers to help refine it.

Alternatively, for JVM-based applications, you can explore the monitoring solutions available through OpenTelemetry, a vendor-neutral open-source project. Microsoft provides distributions and exporters tailored for Azure Monitor:

• With Spring Boot: Leverage the Microsoft distribution of the OpenTelemetry starter for Spring Boot applications. This offers a robust and flexible way to instrument your application using OpenTelemetry, with seamless integration into Azure Monitor.
• With Quarkus: Utilize the Quarkus OpenTelemetry Exporter for Microsoft Azure. This provides a native integration for Quarkus applications, which are known for their fast startup and low memory footprint, to send telemetry to Azure.

These OpenTelemetry-based solutions can offer different performance characteristics and flexibility, especially for modern cloud-native Java applications.

Understanding Duplicated Operation IDs¶

In distributed tracing, each operation (such as a request or a dependency call) is assigned a unique operation ID. Duplicated operation IDs occur when multiple telemetry items appear to share the same operation ID, which can make it challenging to correctly visualize and understand the flow of transactions. This issue can originate from either flawed application logic that reuses IDs or from incoming requests that improperly propagate tracing context.

An example of application logic leading to this is when a custom operation manually sets an operation_Id that clashes with another part of the application. To effectively identify the source of duplication, it’s crucial to examine the tracing context propagated through HTTP headers.

To diagnose duplicated operation IDs, perform the following operations:

1. Enable Header Capture in applicationinsights.json: Configure the Application Insights agent to capture specific HTTP headers that carry tracing context. Modify your applicationinsights.json file as follows to enable the capture of traceparent and request-id headers:

     {
       "preview": {
         "captureHttpServerHeaders": {
           "requestHeaders": [
             "traceparent",
             "request-id"
           ]
         }
       }
     }
   

   
   The traceparent header is central to W3C Trace Context specification, which defines how trace information is propagated across services. The request-id header is another common proprietary header used for similar purposes. Capturing these headers provides invaluable information about how tracing context is being passed into your application.

2. Enable Self-Diagnostics at DEBUG Level and Restart: Enable self-diagnostics at the DEBUG level in your Application Insights configuration and then restart your application. This will cause the agent to emit more verbose logs about its internal operations, including how it processes incoming trace contexts.

   In the debug logs, you can look for entries similar to this example:
   

   {"ver":1,"name":"Request",...,"ai.operation.id":"4e757357805f4eb18705abd24326b550)","ai.operation.parentId":"973487efc3db7d03"},"data": {"baseType":"RequestData","baseData":{...,"properties":{"http.request.header.traceparent":"00-4e757357805f4eb18705abd24326b550-973487efc3db7d03-01", ...}}}}
   

   
   In this log snippet, the ai.operation.id is 4e757357805f4eb18705abd24326b550, and it matches the traceparent header’s trace ID part 00-**4e757357805f4eb18705abd24326b550**-973487efc3db7d03-01. This indicates that the operation ID was inherited from an incoming request’s traceparent header, rather than being generated internally by Application Insights. If your application is receiving requests from an upstream service that already initiated a trace, the agent will honor that trace context. If this upstream service is inadvertently reusing trace IDs, then the duplication will propagate.

Understanding this distinction helps you determine if the issue lies within your application’s logic, where it might be generating or reusing operation IDs incorrectly, or if the duplication is originating from an external system sending requests to your application. Troubleshooting then shifts to either correcting your application’s tracing implementation or investigating the upstream service.

Third-Party Information Disclaimer

The third-party products and online tools mentioned in this article are developed and maintained by companies independent of Microsoft. Microsoft provides no warranty, either implied or explicit, regarding the performance, reliability, or security of these products or services. Users should exercise their own judgment and discretion when utilizing external tools.

---

We hope this comprehensive guide helps you troubleshoot common issues with Java applications and Application Insights on Azure. Your feedback is invaluable in improving our documentation and agent capabilities.

If you encountered a different issue, or if these steps didn’t resolve your problem, please share your experience in the comments section below. What specific challenges are you facing with Java app monitoring on Azure?