监视 Java Web 应用中的依赖项、捕获的异常和方法执行时间Monitor dependencies, caught exceptions and method execution times in Java web apps

如果已使用 Application Insights 检测了 Java Web 应用,则无需更改任何代码,就能使用 Java 代理来获取更深入的见解:If you have instrumented your Java web app with Application Insights, you can use the Java Agent to get deeper insights, without any code changes:

  • 依赖项: 有关应用程序对其他组件的调用数据,包括:Dependencies: Data about calls that your application makes to other components, including:

    • 捕获通过 Apache HttpClient、OkHttp 和 java.net.HttpURLConnection 进行的传出 HTTP 调用Outgoing HTTP calls made via Apache HttpClient, OkHttp, and java.net.HttpURLConnection are captured.
    • 捕获通过 Jedis 客户端进行的 Redis 调用Redis calls made via the Jedis client are captured.
    • JDBC 查询 - 对于 MySQL 和 PostgreSQL,如果调用花费的时间长于 10 秒,代理将报告查询计划。JDBC queries - For MySQL and PostgreSQL, if the call takes longer than 10 seconds, the agent reports the query plan.
  • 应用程序日志记录: 捕获应用程序日志并将其与 HTTP 请求和其他遥测数据相关联Application logging: Capture and correlate your application logs with HTTP requests and other telemetry

    • Log4j 1.2Log4j 1.2
    • Log4j2Log4j2
    • LogbackLogback
  • 更好的操作命名: (用于在门户中对请求进行聚合)Better operation naming: (used for aggregation of requests in the portal)

    • Spring - 基于 @RequestMappingSpring - based on @RequestMapping.
    • JAX-RS - 基于 @PathJAX-RS - based on @Path.

若要使用 Java 代理,请在服务器上安装该代理。To use the Java agent, you install it on your server. 必须使用 Application Insights Java SDK 检测 Web 应用。Your web apps must be instrumented with the Application Insights Java SDK.

安装适用于 Java 的 Application Insights 代理Install the Application Insights agent for Java

  1. 在运行 Java 服务器的计算机上下载该代理On the machine running your Java server, download the agent. 请确保下载与 Application Insights Java SDK 核心和 Web 程序包版本相同的 Java 代理版本。Please ensure to download the same version of Java Agent as Application Insights Java SDK core and web packages.

  2. 编辑应用程序服务器启动脚本,并添加以下 JVM 参数:Edit the application server startup script, and add the following JVM argument:

    -javaagent:<full path to the agent JAR file>

    例如,在 Linux 计算机上的 Tomcat 中:For example, in Tomcat on a Linux machine:

    export JAVA_OPTS="$JAVA_OPTS -javaagent:<full path to agent JAR file>"

  3. 重新启动应用程序服务器。Restart your application server.

配置代理Configure the agent

创建名为 AI-Agent.xml 的文件,并将它放在代理 JAR 文件所在的同一个文件夹中。Create a file named AI-Agent.xml and place it in the same folder as the agent JAR file.

设置 xml 文件的内容。Set the content of the xml file. 编辑以下示例,根据需要包含或省略功能。Edit the following example to include or omit the features you want.

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsightsAgent>
   <Instrumentation>
      <BuiltIn enabled="true">

         <!-- capture logging via Log4j 1.2, Log4j2, and Logback, default is true -->
         <Logging enabled="true" />

         <!-- capture outgoing HTTP calls performed through Apache HttpClient, OkHttp,
              and java.net.HttpURLConnection, default is true -->
         <HTTP enabled="true" />

         <!-- capture JDBC queries, default is true -->
         <JDBC enabled="true" />

         <!-- capture Redis calls, default is true -->
         <Jedis enabled="true" />

         <!-- capture query plans for JDBC queries that exceed this value (MySQL, PostgreSQL),
              default is 10000 milliseconds -->
         <MaxStatementQueryLimitInMS>1000</MaxStatementQueryLimitInMS>

      </BuiltIn>
   </Instrumentation>
</ApplicationInsightsAgent>

其他配置 (Spring Boot)Additional config (Spring Boot)

java -javaagent:/path/to/agent.jar -jar path/to/TestApp.jar

对于 Azure 应用服务,请执行以下操作:For Azure App Services do the following:

  • 选择“设置”>“应用程序设置”Select Settings > Application Settings
  • 在“应用设置”下添加新的键/值对:Under App Settings, add a new key value pair:

注册表项:JAVA_OPTS 值:-javaagent:D:/home/site/wwwroot/applicationinsights-agent-2.5.0.jarKey: JAVA_OPTS Value: -javaagent:D:/home/site/wwwroot/applicationinsights-agent-2.5.0.jar

有关 Java 代理的最新版本,请在此处查看版本。For the latest version of the Java agent check the releases here.

代理必须打包为项目中的资源,以便它最终位于 D:/home/site/wwwroot/ 目录中。The agent must be packaged as a resource in your project such that it ends up in the D:/home/site/wwwroot/ directory. 可以通过转到“开发工具” > “高级工具” > “调试控制台” 并查看站点目录的内容,确认你的代理处于正确的应用服务目录中。You can confirm that your agent is in the correct App Service directory by going to Development Tools > Advanced Tools > Debug Console and examining the contents of the site directory.

  • 保存设置并重启应用。Save the settings and Restart your app. (这些步骤仅适用于 Windows 上运行的应用程序服务。)(These steps only apply to App Services running on Windows.)

备注

AI-Agent.xml 和代理 jar 文件应位于同一文件夹中。AI-Agent.xml and the agent jar file should be in the same folder. 它们通常一起放在该项目的 /resources 文件夹中。They are often placed together in the /resources folder of the project.

启用 W3C 分布式跟踪Enable W3C distributed tracing

将以下代码添加到 AI-Agent.xml:Add the following to AI-Agent.xml:

<Instrumentation>
   <BuiltIn enabled="true">
      <HTTP enabled="true" W3C="true" enableW3CBackCompat="true"/>
   </BuiltIn>
</Instrumentation>

备注

默认情况下启用向后兼容性模式,并且 enableW3CBackCompat 参数是可选的,且仅在要将其关闭时使用。Backward compatibility mode is enabled by default and the enableW3CBackCompat parameter is optional and should be used only when you want to turn it off.

理想情况下,所有服务都已更新为支持 W3C 协议的较新版 SDK 时,就会出现这种情况。Ideally this would be the case when all your services have been updated to newer version of SDKs supporting W3C protocol. 强烈建议尽快迁移到提供 W3C 支持的新版 SDK。It is highly recommended to move to newer version of SDKs with W3C support as soon as possible.

请确保传入和传出(代理)配置完全相同 。Make sure that both incoming and outgoing (agent) configurations are exactly same.

查看数据View the data

在 Application Insights 资源中,聚合的远程依赖项和方法执行时间显示在“性能”磁贴下In the Application Insights resource, aggregated remote dependency and method execution times appears under the Performance tile.

若要搜索依赖项、异常和方法报告的单个实例,请打开搜索To search for individual instances of dependency, exception, and method reports, open Search.

诊断依赖项问题 - 了解详细信息Diagnosing dependency issues - learn more.

存在疑问?Questions? 遇到问题?Problems?