故障排除指南:适用于 Java 的 Azure Monitor Application InsightsTroubleshooting guide: Azure Monitor Application Insights for Java

本文介绍了使用 Application Insights 的 Java 代理来检测 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 是 Azure Monitor 平台服务的一项功能。Application Insights is a feature of the Azure Monitor platform service.

检查自诊断日志文件Check the self-diagnostic log file

默认情况下,Application Insights 的 Java 3.0 代理在 applicationinsights-agent-3.0.3.jar 文件所在的目录中生成名为 applicationinsights.log 的日志文件。By default, the Java 3.0 agent for Application Insights produces a log file named applicationinsights.log in the same directory that holds the applicationinsights-agent-3.0.3.jar file.

针对你可能遇到的问题查找线索时,此日志文件是要检查的第一个位置。This log file is the first place to check for hints to any issues you might be experiencing.

JVM 无法启动JVM fails to start

如果 JVM 无法启动并显示“打开 zip 文件时出错或缺少 JAR 清单”,请尝试重新下载代理 jar 文件,因为它在文件传输过程中可能已损坏。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.

从 Application Insights Java 2.x SDK 进行升级Upgrade from the Application Insights Java 2.x SDK

如果你已在应用程序中使用 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. Java 3.0 代理会检测到它。The Java 3.0 agent will detect it. 有关详细信息,请参阅从 Java 2.x SDK 进行升级For more information, see Upgrade from the Java 2.x SDK.

从 Application Insights Java 3.0 预览版进行升级Upgrade from Application Insights Java 3.0 Preview

如果要从 Java 3.0 预览版代理进行升级,请仔细检查所有配置选项If you're upgrading from the Java 3.0 Preview agent, review all of the configuration options carefully. JSON 结构在 3.0 正式发布版 (GA) 中已完全更改。The JSON structure has completely changed in the 3.0 general availability (GA) release.

这些更改包括:These changes include:

  • 配置文件名称已从 ApplicationInsights.json 更改为 applicationinsights.jsonThe configuration file name has changed from ApplicationInsights.json to applicationinsights.json.
  • instrumentationSettings 节点不再存在。The instrumentationSettings node is no longer present. instrumentationSettings 中的所有内容已移动到根级别。All content in instrumentationSettings is moved to the root level.
  • samplingjmxMetricsinstrumentationheartbeat 等配置节点已从 preview 移出到根级别。Configuration nodes like sampling, jmxMetrics, instrumentation, and heartbeat are moved out of preview to the root level.

某些日志记录不是自动收集的Some logging is not auto-collected

日志记录首先要符合为日志记录框架配置的级别,其次还要符合为 Application Insights 配置的级别,只有在这种情况下才会捕获日志记录。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.

例如,如果将日志记录框架配置为从包 com.example 记录 WARN(和更高版本),并将 Application Insights 配置为捕获 INFO(和更高版本),则 Application Insights 将只从包 com.example 捕获 WARN(和更高版本)。For example, if your logging framework is configured to log WARN (and above) from package com.example, and Application Insights is configured to capture INFO (and above), then Application Insights will only capture WARN (and above) from package com.example.

若要了解某个特定的日志记录语句是否满足日志记录框架的已配置阈值,最好的方法是确认它是否显示在正常的应用程序日志(例如文件或控制台)中。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).

另请注意,如果将异常对象传递到记录器,则日志消息(和异常对象详细信息)会显示在 Azure 门户中的 exceptions 表(而不是 traces 表)下。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 traces table.

有关更多详细信息,请参阅自动收集的日志记录配置See the auto-collected logging configuration for more details.

导入 SSL 证书Import SSL certificates

本部分帮助你在使用 Java 代理时进行故障排除,并可能会修复与 SSL 证书相关的异常。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:

  • 如果使用的是默认 Java 密钥存储If using a default Java keystore
  • 如果使用的是自定义 Java 密钥存储If using a custom Java keystore

如果不确定要使用哪种方法,请检查是否有 JVM 参数 -Djavax.net.ssl.trustStore=...If you aren't sure which path to follow, check to see if you have a JVM arg -Djavax.net.ssl.trustStore=.... 如果没有这样的 JVM 参数,则可能使用的是默认 Java 密钥存储。If you don't have such a JVM arg, then you are probably using the default Java keystore. 如果确实有这样的 JVM 参数,则可能使用的是自定义密钥存储,JVM 参数会将你指向自定义密钥存储。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.

如果使用的是默认 Java 密钥存储:If using the default Java keystore:

通常情况下,默认的 Java 密钥存储已具有所有 CA 根证书。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:

  1. 检查用于对 Application Insights 终结点进行签名的根证书是否已存在于默认密钥存储中。Check if the root certificate that was used to sign the Application Insights endpoint is already present in the default keystore. 默认情况下,受信任的 CA 证书存储在 $JAVA_HOME/jre/lib/security/cacerts 中。The trusted CA certificates, by default, are stored in $JAVA_HOME/jre/lib/security/cacerts. 若要列出 Java 密钥存储中的证书,请使用以下命令: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

  2. 获得证书列表后,按照以下步骤下载用于对 Application Insights 终结点进行签名的根证书。Once you have the list of certificates, follow these steps to download the root certificate that was used to sign the Application Insights endpoint.

    下载证书后,使用以下命令基于证书生成 SHA-1 哈希: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"

    复制 SHA-1 值并检查此值是否存在于你之前保存的“temp.txt”文件中。Copy the SHA-1 value and check if this value is present in "temp.txt" file you saved previously. 如果在临时文件中找不到 SHA-1 值,则表示默认 Java 密钥存储中缺少下载的根证书。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.

  3. 使用以下命令将根证书导入到默认 Java 密钥存储: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

如果使用的是自定义 Java 密钥存储:If using a custom Java keystore:

如果使用的是自定义 Java 密钥存储,则你可能需要将 Application Insights 终结点根 SSL 证书导入其中。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:

  1. 按照以下步骤从 Application Insights 终结点下载根证书。Follow these steps to download the root certificate from the Application Insights endpoint.
  2. 使用以下命令将根 SSL 证书导入到自定义 Java 密钥存储: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

下载 SSL 证书的步骤Steps to download SSL certificate

  1. 打开你习惯使用的浏览器,然后转到用于检测应用程序的连接字符串中存在的 IngestionEndpoint URL。Open your favorite browser and go to the IngestionEndpoint URL present in the connection string that's used to instrument your application.

    屏幕截图显示了 Application Insights 连接字符串。

  2. 选择浏览器中的“查看站点信息”(锁)图标,然后选择“证书”选项。Select the View site information (lock) icon in the browser, and then select the Certificate option.

    屏幕截图显示了站点信息中的“证书”选项。

  3. 你应当下载“根”证书,而不是下载“叶”证书,如下所示。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.

    屏幕截图显示了如何选择根证书。

  4. 转到“详细信息”选项卡,然后选择“复制到文件”。Go to the Details tab and select Copy to file.

  5. 选择“下一步”按钮,选择“Base-64 编码的 X.509 (.CER)”格式,然后再次选择“下一步”。Select the Next button, select Base-64 encoded X.509 (.CER) format, and then select Next again.

    证书导出向导的屏幕截图,其中选择了一种格式。

  6. 指定要在其中保存 SSL 证书的文件。Specify the file where you want to save the SSL certificate. 然后,选择“下一步” > “完成”。 Then select Next > Finish. 应该会看到“导出成功”消息。You should see a "The export was successful" message.

警告

在当前证书到期之前,你需要重复这些步骤以获取新证书。You'll need to repeat these steps to get the new certificate before the current certificate expires. 可以在“证书”对话框的“详细信息”选项卡上找到到期信息。You can find the expiration information on the Details tab of the Certificate dialog box.

屏幕截图显示了 SSL 证书详细信息。