故障排除指南：适用于 Java 的 Azure Monitor Application Insights

项目
04/13/2024

本文提供故障排除信息，以解决使用适用于 Application Insights 的 Java 代理检测 Java 应用程序时可能出现的常见问题。 Application Insights 是 Azure Monitor 平台服务的一项功能。

检查自我诊断日志文件

默认情况下，Application Insights Java 3。x 在保存 applicationinsights-agent-3.2.11.jar 文件的同一目录中生成名为 applicationinsights.log 的 日志文件。

此日志文件是检查有关你可能遇到的任何问题的提示的第一个位置。

如果 Application Insights 未生成日志文件，检查以确保 Java 应用程序对保存applicationinsights-agent-3.2.11.jar文件的目录具有写入权限。

如果 Application Insights 仍无法生成日志文件，检查 Java 应用程序中的stdout日志以查找错误。 Application Insights Java 3。x 应记录任何会阻止其日志记录到日志中的常用位置的错误 stdout 。

排查连接问题

Application Insights SDK 和代理发送遥测数据，作为引入终结点的 REST 调用进行引入。若要测试从 Web 服务器或应用程序主机计算机到引入服务终结点的连接，请使用 PowerShell 中的原始 REST 客户端或运行 curl 命令。请参阅排查 Azure Monitor Application Insights 中缺少应用程序遥测的问题。

如果 Application Insights Java 代理导致连接问题，请考虑以下选项：

验证 Application Insights 配置的连接字符串。
使用 Application Insights Java 版本 3.4.6 或更高版本验证 Java 密钥存储是否包含所需的证书。为此，请在级别启用自诊断功能TRACE。在 Application Insights 日志中，是否看到以下条目？

TRACE c.m.applicationinsights.agent - Java 密钥存储中的 Application Insights 根证书：false

如果看到此条目，请参阅导入 SSL 证书以在 Java 密钥存储中导入根证书。
如果使用 -Djsse.enableSNIExtension=false 选项，请尝试在没有该选项的情况下运行代理。在 Application Insights Java 版本 3.4.5 中，如果指定 -Djsse.enableSNIExtension=false，日志中将显示以下错误条目：

WARN c.m.applicationinsights.agent - 检测到系统属性 -Djsse.enableSNIExtension=false。如果 Application Insights 存在连接问题，请将其删除。
如果上述选项都无济于事，则可以使用故障排除工具。

Java 虚拟机 (JVM) 无法启动

如果 Java 虚拟机 (JVM) 未启动，则可能会返回“打开 zip 文件或缺少 JAR 清单时出错”消息。若要解决此问题，请参阅下表。

问题	操作
找不到代理的 Java 存档 (JAR) 文件。	请确保在 JVM 参数中 `-javaagent` 指定有效的代理 JAR 路径。
代理 JAR 文件在文件传输过程中可能已损坏。	尝试再次下载代理 JAR 文件。

Tomcat Java 应用需要几分钟时间才能启动

如果启用了 Application Insights 来监视 Tomcat 应用程序，则启动应用程序所需的时间可能会延迟几分钟。之所以出现此延迟，是因为 Tomcat 尝试在应用程序启动期间扫描 Application Insights JAR 文件。若要加快应用程序启动时间，可以从扫描的文件列表中排除 Application Insights JAR 文件。不需要扫描这些 JAR 文件。

从 Application Insights Java 2 升级。x SDK

如果已在使用 Application Insights Java 2。应用程序中的 x SDK，可以继续使用它。 Application Insights Java 3。x 代理检测、捕获和关联通过 2 发送的任何自定义遥测数据。x SDK。它还通过取消 2 的任何自动收集来防止重复遥测。x SDK 可以。有关详细信息，请参阅从 Java 2 升级。x SDK。

从 Application Insights Java 3.0 预览版升级

如果要从 Java 3.0 预览版代理升级，请仔细查看所有配置选项。 JSON 结构在 3.0 正式发布版 (GA) 版本中已更改。

这些更改包括：

配置文件名称从 ApplicationInsights.json 更改为 applicationinsights.json。
节点 instrumentationSettings 不再存在。中 instrumentationSettings 的所有内容将移至根级别。
将、、 instrumentation和 heartbeat 等samplingjmxMetrics配置节点移出preview到根级别。

某些日志记录不会自动收集

仅当日志记录满足以下条件时，才会捕获日志记录：

它满足为日志记录框架配置的级别。
它满足为 Application Insights 配置的级别。

例如，如果将日志记录框架配置为记录WARNcom.example包中 (和更高) ，并且 Application Insights 配置为捕获 INFO (和更高) ，则 Application Insights 仅从com.example包捕获 WARN (和更高) 。

若要确保特定日志记录语句满足日志记录框架配置的阈值，请验证它是否出现在文件或控制台) 中的常用应用程序日志 (中。

另请注意，如果将异常对象传递给记录器，则日志消息 (和异常对象详细信息) 显示在表的Azure 门户exceptions而不是traces表中。若要查看和 exceptions 表中的日志消息traces，请运行以下日志 (Kusto) 查询：

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

有关详细信息，请参阅自动收集的日志记录配置。

导入 SSL 证书

本部分可帮助你在使用 Java 代理时排查并修复与安全套接字层 (SSL) 证书相关的异常。

可通过两种不同的路径来解决此问题：

如果使用默认的 Java 密钥存储
如果使用自定义 Java 密钥存储

如果不确定要遵循哪个路径，检查查看是否具有 JVM 参数 -Djavax.net.ssl.trustStore=...。如果没有此 JVM 参数，则可能使用的是默认 Java 密钥存储。如果确实具有此 JVM 参数，则可能使用的是自定义密钥存储，并且 JVM 参数会将你指向自定义密钥存储。

如果使用默认的 Java 密钥存储

默认 Java 密钥存储通常已具有所有 CA 根证书。但是，可能存在一些例外。例如，不同的根证书可能会对引入终结点证书进行签名。建议按照以下步骤来解决此问题：

检查用于对 Application Insights 终结点进行签名的 SSL 证书是否已存在于默认密钥存储中。默认情况下，受信任的 CA 证书存储在 $JAVA_HOME/jre/lib/security/cacerts 中。若要列出 Java 密钥存储中的证书，请使用以下命令：

keytool -list -v -keystore <path-to-keystore-file>

可以将输出重定向到临时文件，以便以后可以轻松搜索：

keytool -list -v -keystore $JAVA_HOME/jre/lib/security/cacerts > temp.txt
获得证书列表后，请按照以下步骤下载用于对 Application Insights 终结点进行签名的 SSL 证书。

下载证书后，使用以下命令在证书上生成 SHA-1 哈希：

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

复制 SHA-1 值，检查此值是否存在于之前保存的temp.txt 文件中。如果在临时文件中找不到 SHA-1 值，则默认 Java 密钥存储中缺少下载的 SSL 证书。
使用以下命令将 SSL 证书导入默认的 Java 密钥存储：

keytool -import -file "<certificate-file>" -alias "<some-meaningful-name>" -keystore "<path-to-cacerts-file>"

在此示例中，命令将如下所示：

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

如果使用自定义 Java 密钥存储

如果使用自定义 Java 密钥存储，可能需要将 Application Insights 终结点的 SSL 证书导入到该密钥存储中。建议执行以下两个步骤来解决此问题：

按照以下步骤从 Application Insights 终结点下载 SSL 证书。
运行以下命令，将 SSL 证书导入自定义 Java 密钥存储：

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

下载 SSL 证书的步骤

注意

已在以下浏览器上验证以下 SSL 证书下载说明：

Google Chrome
Microsoft Edge

在 https://westeurope-5.in.applicationinsights.azure.com/api/ping Web 浏览器中打开 URL 地址。
在浏览器的地址栏中，选择“ 查看网站信息 ”图标， (地址) 旁边的锁符号。
选择“ 连接是安全的”。
选择“ 显示证书 ”图标。
在“ 证书查看器 ”对话框中，选择“ 详细信息 ”选项卡。
在 “证书层次结构 ”列表中，选择要下载的证书。 (显示 CA 根证书、中间证书和叶 SSL 证书。)
选择“ 导出 ”按钮。
在“ 另存为 ”对话框中，浏览到要将证书 (.crt) 文件保存到的目录，然后选择“ 保存”。
若要退出“ 证书查看器 ”对话框，请选择“ 关闭 (X) 按钮。

警告

必须重复这些步骤才能在当前证书过期之前获取新证书。可以在“证书查看器”对话框的“详细信息”选项卡上找到过期信息。

在“证书层次结构”列表中选择证书后，在“证书字段”列表中找到“有效性”节点。在该节点中选择“ 不早于”，然后检查“ 字段值 ”框中显示的日期和时间。此时间戳指示新证书何时生效。同样，请在“有效期”节点中选择“不晚于”，了解新证书何时过期。

了解 UnknownHostException

如果在升级到 3.2.0 之后的 Java 代理版本后看到此异常，则可以通过升级网络来解决异常，以解析异常中显示的新终结点。 Application Insights 版本之间差异的原因是，与旧 v2/track版本相比，3.2.0 以下的版本指向新的引入终结点v2.1/track。新的引入终结点会自动将你重定向到引入终结点 (新终结点，该终结点显示在离 Application Insights 资源存储最近的异常) 中。

缺少密码套件

如果 Application Insights Java 代理检测到你没有它所连接到的终结点支持的任何密码套件，则代理会发出警报，并提供指向缺少的密码套件的链接。

密码套件的背景

在客户端应用程序和服务器通过 SSL 或传输层安全性 (TLS) 连接交换信息之前，密码套件将发挥作用。客户端应用程序启动 SSL 握手。该过程的一部分涉及通知服务器它支持哪些密码套件。服务器接收该信息，并将客户端应用程序支持的密码套件与其支持的算法进行比较。如果服务器找到匹配项，它会通知客户端应用程序，并建立安全连接。如果找不到匹配项，服务器将拒绝连接。

如何确定客户端密码套件

在这种情况下，客户端是运行已检测应用程序的 JVM。从版本 3.2.5 开始，如果缺少密码套件可能导致与其中一个服务终结点的连接失败，Application Insights Java 会记录一条警告消息。

如果使用早期版本的 Application Insights Java，请编译并运行以下 Java 程序，以获取 JVM 中受支持的密码套件列表：

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]);
        }
    }
}

Application Insights 终结点支持以下密码套件：

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

如何确定服务器端密码套件

在这种情况下，服务器端是 Application Insights 引入终结点或 Application Insights Live 指标终结点。可以使用联机工具（如 SSLLABS ）来确定基于终结点 URL 的预期密码套件。

如何添加缺少的密码套件

如果使用的是 Java 9 或更高版本，检查，以确保 JVM 在 jmods 文件夹中包含 jdk.crypto.cryptoki 模块。此外，如果使用生成自定义 Java 运行时 jlink，请确保包含相同的模块。

否则，这些密码套件应已是新式 Java 8+ 分发版的一部分。建议检查已安装的 Java 分发版的源，以调查该 Java 分发版的 java.security 配置文件中的安全提供程序为何不同于标准 Java 分发版。

Application Insights 和 Java 8 中的启动时间较慢

Java 8 存在与 Java 代理的 JAR 文件签名验证相关的已知问题。此问题可能会增加 Application Insights 中的启动时间。若要解决此问题，可以应用以下选项之一：

如果应用程序基于 Spring Boot，请以编程方式将 Application Insights Java 代理附加到 JVM。
使用 Java 版本 11 或更高版本。

或者，可以尝试以下实验性功能：针对有限数量的 CPU 核心的启动时间改进。如果在使用此功能时遇到任何问题，请向我们发送反馈。

第三方信息免责声明

本文中提到的第三方产品由 Microsoft 以外的其他公司提供。 Microsoft 不对这些产品的性能或可靠性提供任何明示或暗示性担保。

联系我们寻求帮助

如果你有任何疑问或需要帮助，请创建支持请求或联系 Azure 社区支持。还可以向 Azure 反馈社区提交产品反馈。