用于 Java 的 Application Insights 的故障排除与常见问题解答Troubleshooting and Q and A for Application Insights for Java

使用 Java 中的 Azure Application Insights 时有疑问或遇到问题?Questions or problems with Azure Application Insights in Java? 请参考下面的提示。Here are some tips.

生成错误Build errors

在 Eclipse 或 Intellij Idea 中,通过 Maven 或 Gradle 添加 Application Insights SDK 时,收到生成或校验和验证错误。In Eclipse or Intellij Idea, when adding the Application Insights SDK via Maven or Gradle, I get build or checksum validation errors.

  • 如果依赖项 <version> 元素使用包含通配符字符的模式(例如(Maven) <version>[2.0,)</version> 或 (Gradle) version:'2.0.+'),则尝试改为指定特定版本,如 2.0.1If the dependency <version> element is using a pattern with wildcard characters (e.g. (Maven) <version>[2.0,)</version> or (Gradle) version:'2.0.+'), try specifying a specific version instead like 2.0.1. 请参阅最新版本的发行说明See the release notes for the latest version.

无数据No data

我已成功添加 Application Insights 并运行应用,但在门户中从未看到数据。I added Application Insights successfully and ran my app, but I've never seen data in the portal.

  • 请稍等片刻,并单击“刷新”。Wait a minute and click Refresh. 图表会定期自行刷新,但你也可以手动刷新。The charts refresh themselves periodically, but you can also refresh manually. 刷新间隔取决于图表的时间范围。The refresh interval depends on the time range of the chart.
  • 检查是否已在 ApplicationInsights.xml 文件(位于项目的 resources 文件夹)中定义检测密钥或将检测密钥配置为环境变量。Check that you have an instrumentation key defined in the ApplicationInsights.xml file (in the resources folder in your project) or configured as Environment variable.
  • 确认 xml 文件中没有 <DisableTelemetry>true</DisableTelemetry> 节点。Verify that there is no <DisableTelemetry>true</DisableTelemetry> node in the xml file.
  • 在防火墙中,可能需要打开 TCP 端口 80 和 443 才能将传出流量发送到 dc.services.visualstudio.com。In your firewall, you might have to open TCP ports 80 and 443 for outgoing traffic to dc.services.visualstudio.com. 请参阅 full list of firewall exceptions(防火墙例外的完整列表)See the full list of firewall exceptions
  • 在 Azure 开始面板中查看服务状态映射。In the Azure start board, look at the service status map. 如果看到警报指示,请等待它们恢复“正常”,关闭再重新打开 Application Insights 应用程序边栏选项卡。If there are some alert indications, wait until they have returned to OK and then close and re-open your Application Insights application blade.
  • 在 ApplicationInsights.xml 文件(位于项目的 resources 文件夹)中的根节点下添加 <SDKLogger /> 元素,打开记录功能,并检查条目的前面是否带有 AI:INFO/WARN/ERROR 以发现任何可疑日志。Turn on logging by adding an <SDKLogger /> element under the root node in the ApplicationInsights.xml file (in the resources folder in your project), and check for entries prefaced with AI: INFO/WARN/ERROR for any suspicious logs.
  • 查看控制台输出消息中是否包含“已成功找到配置文件”语句,确保 Java SDK 成功加载正确的 ApplicationInsights.xml 文件。Make sure that the correct ApplicationInsights.xml file has been successfully loaded by the Java SDK, by looking at the console's output messages for a "Configuration file has been successfully found" statement.
  • 如果找不到配置文件,请检查输出消息来确定在何处搜索配置文件,并确保 ApplicationInsights.xml 位在这些搜索位置之一。If the config file is not found, check the output messages to see where the config file is being searched for, and make sure that the ApplicationInsights.xml is located in one of those search locations. 根据经验法则,可以将配置文件放置在 Application Insights SDK JAR 的附近。As a rule of thumb, you can place the config file near the Application Insights SDK JARs. 例如:在 Tomcat 中,这可能是 WEB-INF/classes 文件夹。For example: in Tomcat, this would mean the WEB-INF/classes folder. 在开发期间,可以将 ApplicationInsights.xml 放在 Web 项目的 resources 文件夹中。During development you can place ApplicationInsights.xml in resources folder of your web project.
  • 另请查看 GitHub 问题页,了解 SDK 的已知问题。Please also look at GitHub issues page for known issues with the SDK.
  • 请确保使用相同版本的 Application Insights Core、Web、代理和日志记录追加器以避免任何版本冲突问题。Please ensure to use same version of Application Insights core, web, agent and logging appenders to avoid any version conflict issues.

我以前看到了数据,但现在看不到I used to see data, but it has stopped

  • 是否达到了数据点的每月配额?Have you hit your monthly quota of data points? 打开“设置/配额和定价”即可检查。如果达到了配额,可以升级计划,或付费购买更多的容量。Open Settings/Quota and Pricing to find out. If so, you can upgrade your plan, or pay for additional capacity. 请参阅定价方案See the pricing scheme.
  • 最近是否升级了 SDK?Have you recently upgraded your SDK? 请确保项目目录内仅存在唯一 SDK jar。Please ensure that only Unique SDK jars are present inside the project directory. 不应存在两个不同版本的 SDK。There should not be two different versions of SDK present.
  • 是否正在查看正确的 AI 资源?Are you looking at the correct AI resource? 请将应用程序的 iKey 与预期遥测的资源的 iKey 相匹配。Please match the iKey of your application to the resource where you are expecting telemetry. 它们应相同。They should be the same.

未按预期看到所有数据I don't see all the data I'm expecting

  • 打开“使用情况和预估成本”页面并检查采样是否正在进行。Open the Usage and estimated cost page and check whether sampling is in operation. (如果传输百分比为 100%,表示当前未执行采样。)可将 Application Insights 服务设置为只接受来自应用的一部分遥测数据。(100% transmission means that sampling isn't in operation.) The Application Insights service can be set to accept only a fraction of the telemetry that arrives from your app. 这有助于保持在每月的遥测配额范围内。This helps you keep within your monthly quota of telemetry.
  • 是否已启用 SDK 采样?Do you have SDK Sampling turned on? 如果是,将按为所有适用类型指定的速率对数据进行采样。If yes, data would be sampled at the rate specified for all the applicable types.
  • 是否正在运行较旧版本的 Java SDK?Are you running an older version of Java SDK? 从版本 2.0.1 开始,我们引入了容错机制以处理间歇性网络和后端故障,以及本地驱动器上的数据持久性。Starting with version 2.0.1, we have introduced fault tolerance mechanism to handle intermittent network and backend failures as well as data persistence on local drives.
  • 是否由于过度遥测而受到限制?Are you getting throttled due to excessive telemetry? 如果启用“信息日志记录”,会看到日志消息“应用受到限制”。If you turn on INFO logging, you will see a log message "App is throttled". 当前的限制为 32000 个遥测项/秒。Our current limit is 32k telemetry items/second.

Java 代理无法捕获依赖项数据Java Agent cannot capture dependency data

  • 是否已按照配置 Java 代理配置 Java 代理?Have you configured Java agent by following Configure Java Agent ?
  • 请确保 java 代理 jar 和 AI-Agent.xml 文件放置在同一文件夹中。Make sure both the java agent jar and the AI-Agent.xml file are placed in the same folder.
  • 请确保自动收集功能支持你尝试自动收集的依赖项。Make sure that the dependency you are trying to auto-collect is supported for auto collection. 目前我们仅支持 MySQL、MsSQL、Oracle DB 和 用于 Redis 的 Azure 缓存依赖项收集。Currently we only support MySQL, MsSQL, Oracle DB and Azure Cache for Redis dependency collection.

无使用情况数据No usage data

我看到了请求和响应时间的相关数据,但没有看到页面视图、浏览器或用户数据。I see data about requests and response times, but no page view, browser, or user data.

已成功将应用设置为从服务器发送遥测数据。You successfully set up your app to send telemetry from the server. 现在,下一步是将网页设置为从 Web 浏览器发送遥测数据Now your next step is to set up your web pages to send telemetry from the web browser.

或者,如果客户端是手机或其他设备中的应用,可以从该处发送遥测数据。Alternatively, if your client is an app in a phone or other device, you can send telemetry from there.

使用相同的检测密钥来设置客户端和服务器遥测。Use the same instrumentation key to set up both your client and server telemetry. 数据将出现在相同的 Application Insights 资源中,可以将来自客户端和服务器的事件相关联。The data will appear in the same Application Insights resource, and you'll be able to correlate events from client and server.

禁用遥测Disabling telemetry

如何禁用遥测数据收集?How can I disable telemetry collection?

在代码中:In code:

    TelemetryConfiguration config = TelemetryConfiguration.getActive();


更新 ApplicationInsights.xml(位于项目的 resources 文件夹中)。Update ApplicationInsights.xml (in the resources folder in your project). 在根节点下添加以下代码:Add the following under the root node:


如果使用 XML 方法,则必须在更改值后重新启动应用程序。Using the XML method, you have to restart the application when you change the value.

更改目标Changing the target

如何更改项目要将数据发送到的 Azure 资源?How can I change which Azure resource my project sends data to?

  • 获取新资源的检测密钥。Get the instrumentation key of the new resource.
  • 如果使用用于 Eclipse 的 Azure 工具包将 Application Insights 添加到项目,请右键单击 Web 项目,选择“Azure”、“配置 Application Insights”,然后更改密钥。 If you added Application Insights to your project using the Azure Toolkit for Eclipse, right click your web project, select Azure, Configure Application Insights, and change the key.
  • 如果已将检测密钥配置为环境变量,请使用新 iKey 更新环境变量的值。If you had configured the Instrumentation Key as environment variable please update the value of the environment variable with new iKey.
  • 否则,请更新项目的 resources 文件夹中 ApplicationInsights.xml 内的密钥。Otherwise, update the key in ApplicationInsights.xml in the resources folder in your project.

通过 SDK 调试数据Debug data from the SDK

如何知道 SDK 正在执行什么操作?How can I find out what the SDK is doing?

若要获取有关 API 中的具体操作的详细信息,请在 ApplicationInsights.xml 配置文件的根节点下添加 <SDKLogger/>To get more information about what's happening in the API, add <SDKLogger/> under the root node of the ApplicationInsights.xml configuration file.


也可以指示记录器将信息输出到某个文件:You can also instruct the logger to output to a file:

  <SDKLogger type="FILE"><!-- or "CONSOLE" to print to stderr -->

Spring Boot StarterSpring Boot Starter

若要使用 Application Insight Spring Boot Starter 启用 Spring Boot 应用的 SDK 日志记录,请将以下内容添加到 application.properties 文件中:To enable SDK logging with Spring Boot Apps using the Application Insights Spring Boot Starter, add the following to the application.properties file:


或者输出到标准错误:or to print to standard error:


Java 代理Java Agent

若要启用 JVM 代理日志记录,请更新 AI-Agent.xml 文件To enable JVM Agent Logging update the AI-Agent.xml file:

<AgentLogger type="FILE"><!-- or "CONSOLE" to print to stderr -->

Java 命令行属性Java Command Line Properties

自版本 2.4.0Since version 2.4.0

若要使用命令行选项启用日志记录,而不更改配置文件,请执行以下操作:To enable logging using command line options, without changing configuration files:

java -Dapplicationinsights.logger.file.level=trace -Dapplicationinsights.logger.file.uniquePrefix=AI -Dapplicationinsights.logger.baseFolderPath="C:/my/log/dir" -jar MyApp.jar

或者输出到标准错误:or to print to standard error:

java -Dapplicationinsights.logger.console.level=trace -jar MyApp.jar

Azure 开始屏幕The Azure start screen

我正在查看 Azure 门户。地图是否告知有关应用的信息?I'm looking at the Azure portal. Does the map tell me something about my app?

不会,它只显示世界各地的 Azure 服务器的运行状况。No, it shows the health of Azure servers around the world.

如何从 Azure 开始面板(主屏幕)找到有关应用的数据?From the Azure start board (home screen), how do I find data about my app?

假设要为 Application Insights 设置应用,请单击“浏览”,选择“Application Insights”,并选择为应用创建的应用资源。Assuming you set up your app for Application Insights, click Browse, select Application Insights, and select the app resource you created for your app. 今后要快速转到该位置,可将应用固定到开始面板。To get there faster in future, you can pin your app to the start board.

Intranet 服务器Intranet servers

是否可以在 Intranet 上监视服务器?Can I monitor a server on my intranet?

可以,前提是该服务器可以通过公共 Internet 将遥测数据发送到 Application Insights 门户。Yes, provided your server can send telemetry to the Application Insights portal through the public internet.

在防火墙中,可能需要打开 TCP 端口 80 和 443 才能将传出流量发送到 dc.services.visualstudio.com 和 f5.services.visualstudio.com。In your firewall, you might have to open TCP ports 80 and 443 for outgoing traffic to dc.services.visualstudio.com and f5.services.visualstudio.com.

数据保留Data retention

数据在门户中保留多长时间?是否安全?How long is data retained in the portal? Is it secure?

请参阅数据保留和隐私See Data retention and privacy.

调试日志记录Debug logging

Application Insights 使用 org.apache.httpApplication Insights uses org.apache.http. 这将在命名空间 com.microsoft.applicationinsights.core.dependencies.http 下的 Application Insights 核心 jar 中重定位。This is relocated within Application Insights core jars under the namespace com.microsoft.applicationinsights.core.dependencies.http. 这将允许 Application Insights 处理一段基本代码中存在不同版本的同一 org.apache.http 的方案。This enables Application Insights to handle scenarios where different versions of the same org.apache.http exist in one code base.


如果为应用中的所有命名空间启用了调试级别日志记录,则所有执行中模块(包括重命名为 com.microsoft.applicationinsights.core.dependencies.httporg.apache.http)都将遵循它。If you enable DEBUG level logging for all namespaces in the app, it will be honored by all executing modules including org.apache.http renamed as com.microsoft.applicationinsights.core.dependencies.http. Application Insights 将无法为这些调用应用筛选,因为进行日志调用的是 Apache 库。Application Insights will not be able to apply filtering for these calls because the log call is being made by the Apache library. 调试级别日志记录将生成大量日志数据,因此不建议在实时生产实例中使用。DEBUG level logging produce a considerable amount of log data and is not recommended for live production instances.

后续步骤Next steps

我为 Java 服务器应用设置了 Application Insights。接下来还可以做些什么?I set up Application Insights for my Java server app. What else can I do?

获取帮助Get help