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

项目
11/19/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 ，请尝试在没有该选项的情况下运行代理。如果指定 -Djsse.enableSNIExtension=false了 Application Insights Java 版本 3.4.5，日志中会显示以下错误条目：

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 预览版代理升级，请仔细查看所有配置选项。 3.0 正式版（正式版）中更改了 JSON 结构。

这些更改包括：

配置文件名称从 ApplicationInsights.json 更改为 applicationinsights.json。
instrumentationSettings 节点不再存在。 instrumentationSettings 中的所有内容已移动到根级别。
配置节点（例如sampling，jmxMetricsinstrumentation）已heartbeat移出preview根级别。

未自动收集某些日志记录

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

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

例如，如果日志记录框架配置为从com.example包中记录WARN（及更高版本），并且 Application Insights 配置为捕获INFO（及更高），则 Application Insights 仅从com.example包中捕获WARN（及更高）。

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

另请注意，如果将异常对象传递给记录器，日志消息（和异常对象详细信息）将显示在表中traces的Azure 门户而不是exceptions表中。若要查看这两个表的tracesexceptions日志消息，请运行以下日志（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 实时指标终结点。可以使用 SSLLABS 等联机工具来确定基于终结点 URL 的预期密码套件。

如何添加缺少的密码套件

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

否则，这些密码套件应已是现代 Java 8+ 发行版的一部分。建议检查安装的 Java 分发的源，以调查该 Java 分发中 该 Java 分发中的安全提供程序与标准 Java 分发版的不同的原因。

Application Insights 中的启动时间缓慢

Java 8

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

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

Java 高于版本 8

若要修复 Application Insights Java 代理的此问题，请尝试以下方法之一：

使用具有更多 CPU 功率的 Azure 配置。
禁用“禁止特定自动收集的遥测”中所述的某些检测。
试用此实验性功能：有限数量的 CPU 核心的启动时间改进。如果在使用此功能时遇到任何问题，请向我们发送反馈。

还可以尝试适用于基于 JVM 的应用程序的 Java 本机监视解决方案：

使用 Spring Boot，OpenTelemetry 初学者Microsoft分发。
使用 Quarkus，适用于 Microsoft Azure 的 Quarkus Opentelemetry 导出程序。

第三方信息免责声明

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

联系我们寻求帮助

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

通过