Troubleshooting guide: Azure Monitor Application Insights for Java
In this article, we cover some of the common issues that you might face while instrumenting a Java application by using the Java agent for Application Insights. We also cover the steps to resolve these issues. Application Insights is a feature of the Azure Monitor platform service.
Check the self-diagnostic log file
By default, Application Insights Java 3.x produces a log file named
applicationinsights.log in the same directory that holds the
This log file is the first place to check for hints to any issues you might be experiencing.
JVM fails to start
If the JVM fails to start with "Error opening zip file or JAR manifest missing", try re-downloading the agent jar file because it may have been corrupted during file transfer.
Upgrade from the Application Insights Java 2.x SDK
If you're already using the Application Insights Java 2.x SDK in your application, you can keep using it. The Application Insights Java 3.x agent will detect it, and capture and correlate any custom telemetry you're sending via the 2.x SDK, while suppressing any auto-collection performed by the 2.x SDK to prevent duplicate telemetry. For more information, see Upgrade from the Java 2.x SDK.
Upgrade from Application Insights Java 3.0 Preview
If you're upgrading from the Java 3.0 Preview agent, review all of the configuration options carefully. The JSON structure has completely changed in the 3.0 general availability (GA) release.
These changes include:
- The configuration file name has changed from
instrumentationSettingsnode is no longer present. All content in
instrumentationSettingsis moved to the root level.
- Configuration nodes like
heartbeatare moved out of
previewto the root level.
Some logging is not auto-collected
Logging is only captured if it first meets the level that is configured for the logging framework, and second, also meets the level that is configured for Application Insights.
For example, if your logging framework is configured to log
WARN (and above) from package
and Application Insights is configured to capture
INFO (and above),
then Application Insights will only capture
WARN (and above) from package
The best way to know if a particular logging statement meets the logging frameworks' configured threshold is to confirm that it is showing up in your normal application log (e.g. file or console).
Also note that if an exception object is passed to the logger, then the log message (and exception object details)
will show up in the Azure portal under the
exceptions table instead of the
See the auto-collected logging configuration for more details.
Import SSL certificates
This section helps you to troubleshoot and possibly fix the exceptions related to SSL certificates when using the Java agent.
There are two different paths below for resolving this issue:
- If using a default Java keystore
- If using a custom Java keystore
If you aren't sure which path to follow, check to see if you have a JVM arg
If you don't have such a JVM arg, then you are probably using the default Java keystore.
If you do have such a JVM arg, then you are probably using a custom keystore,
and the JVM arg will point you to your custom keystore.
If using the default Java keystore:
Typically the default Java keystore will already have all of the CA root certificates. However there might be some exceptions, such as the ingestion endpoint certificate might be signed by a different root certificate. So we recommend the following three steps to resolve this issue:
Check if the root certificate that was used to sign the Application Insights endpoint is already present in the default keystore. The trusted CA certificates, by default, are stored in
$JAVA_HOME/jre/lib/security/cacerts. To list certificates in a Java keystore use the following command:
keytool -list -v -keystore $PATH_TO_KEYSTORE_FILE
You can redirect the output to a temp file like this (will be easy to search later)
keytool -list -v -keystore $JAVA_HOME/jre/lib/security/cacerts > temp.txt
Once you have the list of certificates, follow these steps to download the root certificate that was used to sign the Application Insights endpoint.
Once you have the certificate downloaded, generate a SHA-1 hash on the certificate using the below command:
keytool -printcert -v -file "your_downloaded_root_certificate.cer"
Copy the SHA-1 value and check if this value is present in "temp.txt" file you saved previously. If you are not able to find the SHA-1 value in the temp file, it indicates that the downloaded root cert is missing in default Java keystore.
Import the root certificate to the default Java keystore using the following command:
keytool -import -file "the cert file" -alias "some meaningful name" -keystore "path to cacerts file"
In this case it will be
keytool -import -file "your downloaded root cert file" -alias "some meaningful name" $JAVA_HOME/jre/lib/security/cacerts
If using a custom Java keystore:
If you are using a custom Java keystore, you may need to import the Application Insights endpoint(s) root SSL certificate(s) into it. We recommend the following two steps to resolve this issue:
- Follow these steps to download the root certificate from the Application Insights endpoint.
- Use the following command to import the root SSL certificate to the custom Java keystore:
keytool -importcert -alias your_ssl_certificate -file "your downloaded SSL certificate name.cer" -keystore "Your KeyStore name" -storepass "Your keystore password" -noprompt
Steps to download SSL certificate
Open your favorite browser and go to the
IngestionEndpointURL present in the connection string that's used to instrument your application.
Select the View site information (lock) icon in the browser, and then select the Certificate option.
Instead of downloading the 'leaf' certificate you should download the 'root' certificate as shown below. Later, you have to click on the "Certificate Path" -> Select the Root Certificate -> Click on 'View Certificate'. This will pop up a new certificate menu and you can download the certificate, from the new menu.
Go to the Details tab and select Copy to file.
Select the Next button, select Base-64 encoded X.509 (.CER) format, and then select Next again.
Specify the file where you want to save the SSL certificate. Then select Next > Finish. You should see a "The export was successful" message.