快速入门:Java Web 项目中的 Application Insights 入门

注意

自 2020 年 11 月起,对于监视 Java 应用程序,我们建议使用 Azure Monitor Application Insights Java 3.0 代理进行自动检测。 有关如何入门的详细信息,请参阅 Application Insights Java 3.0 代理

在本快速入门中,你将使用 Application Insights SDK 检测请求、跟踪依赖项、收集性能计数器、诊断性能问题和异常,并编写代码以跟踪用户对应用执行的操作。

Application Insights 是面向 Web 开发人员的可扩展分析服务,可帮助你了解实时应用程序的性能和使用情况。 Application Insights 支持 Linux、Unix 或 Windows 上运行的 Java 应用。

先决条件

  • 具有活动订阅的 Azure 帐户。 创建试用帐户
  • 正常运行的 Java 应用程序。

获取 Application Insights 检测密钥

重要

新的 Azure 区域要求使用连接字符串而不是检测密钥。 连接字符串用于标识要与遥测数据关联的资源。 它还允许你修改可供你的资源将其用作遥测目标的终结点。 你需要复制连接字符串,并将其添加到应用程序的代码或环境变量中。

  1. 登录到 Azure 门户

  2. 在 Azure 门户中,创建 Application Insights 资源。 将应用程序类型设置为 Java Web 应用程序。

  3. 查找新资源的检测密钥。 稍后需要将此密钥粘贴到代码项目中。

    在新资源概述中,单击“属性”,并复制检测密钥

将用于 Java 的 Application Insights SDK 添加到项目

选择项目类型。

如果项目已设置为使用 Maven 生成,请将以下代码合并到 pom.xml 文件。

然后刷新项目依赖项,以下载库。

    <dependencies>
      <dependency>
        <groupId>com.microsoft.azure</groupId>
        <artifactId>applicationinsights-web-auto</artifactId>
        <!-- or applicationinsights-web for manual web filter registration -->
        <!-- or applicationinsights-core for bare API -->
        <version>2.6.2</version>
      </dependency>
    </dependencies>

问题

  • -web-auto-web-core 组件之间有怎样的关系?

    • applicationinsights-web-auto 通过在运行时自动注册 Application Insights servlet 筛选器,为你提供跟踪 HTTP servlet 请求计数和响应时间的指标。
    • applicationinsights-web 也为你提供跟踪 HTTP servlet 请求计数和响应时间的指标,但需要在应用程序中手动注册 Application Insights servlet 筛选器。
    • 例如,如果应用程序不是基于 servlet 的应用程序,则 applicationinsights-core 仅提供单纯的 API。
  • 应怎样将 SDK 更新到最新版本?

    • 自 2020 年 11 月起,对于监视 Java 应用程序,我们建议使用 Azure Monitor Application Insights Java 3.0 代理进行自动检测。 有关如何入门的详细信息,请参阅 Application Insights Java 3.0 代理

添加 ApplicationInsights.xml 文件

在项目的 resources 文件夹中添加 ApplicationInsights.xml,或确保将其添加到项目的部署类路径。 将以下 XML 复制到其中。

将检测密钥替换为从 Azure 门户获得的密钥。

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings" schemaVersion="2014-05-30">

   <!-- The key from the portal: -->
   <InstrumentationKey>** Your instrumentation key **</InstrumentationKey>

   <!-- HTTP request component (not required for bare API) -->
   <TelemetryModules>
      <Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebRequestTrackingTelemetryModule"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebSessionTrackingTelemetryModule"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebUserTrackingTelemetryModule"/>
   </TelemetryModules>

   <!-- Events correlation (not required for bare API) -->
   <!-- These initializers add context data to each event -->
   <TelemetryInitializers>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebOperationIdTelemetryInitializer"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebOperationNameTelemetryInitializer"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebSessionTelemetryInitializer"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebUserTelemetryInitializer"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebUserAgentTelemetryInitializer"/>
   </TelemetryInitializers>

</ApplicationInsights>

或者,配置文件可以位于应用程序可访问的任何位置。 系统属性 -Dapplicationinsights.configurationDirectory 指定 ApplicationInsights.xml 所在的目录。 例如,位于 E:\myconfigs\appinsights\ApplicationInsights.xml 的配置文件可以通过属性 -Dapplicationinsights.configurationDirectory="E:\myconfigs\appinsights" 进行配置。

  • 检测密钥随遥测的每个项一起发送,并告知 Application Insights 在资源中显示它。
  • HTTP 请求组件是可选的。 它自动将请求和响应时间的遥测数据发送到门户。
  • 事件关联是对 HTTP 请求组件的补充。 它将标识符分配给服务器收到的每个请求。 然后将此标识符作为属性添加到每个遥测项,作为属性“Operation.Id”。 使用它可以通过在诊断搜索中设置筛选器,来关联与每个请求关联的遥测。

设置检测密钥的替代方法

Application Insights SDK 按以下顺序查找密钥:

  1. 系统属性:-DAPPINSIGHTS_INSTRUMENTATIONKEY=your_ikey
  2. 环境变量:APPINSIGHTS_INSTRUMENTATIONKEY
  3. 配置文件:ApplicationInsights.xml

也可以 在代码中设置方法

    String instrumentationKey = "00000000-0000-0000-0000-000000000000";

    if (instrumentationKey != null)
    {
        TelemetryConfiguration.getActive().setInstrumentationKey(instrumentationKey);
    }

添加代理

安装 Java 代理以捕获传出的 HTTP 调用、JDBC 查询、应用程序日志记录和更好的操作命名。

运行应用程序

在开发计算机上以调试模式运行应用程序,或将其发布到服务器。

在 Application Insights 中查看遥测数据

返回到 Azure 门户中的 Application Insights 资源。

“概述”边栏选项卡中显示了 HTTP 请求数据。 (如果未显示,请稍候片刻,并单击“刷新”。)

概述示例数据的屏幕截图

了解有关指标的详细信息。

单击任一图表可查看详细聚合指标。

带有图表的“Application Insights 故障”窗格

实例数据

单击特定的请求类型可查看各个实例。

钻取到特定示例视图

分析:功能强大的查询语言

随着累积的数据越来越多,可以运行查询来聚合数据以及查找单个实例。 分析 是一个强大的工具,既可用于了解性能和使用情况,也可用于诊断。

分析示例

在服务器上安装应用

现在,将应用程序发布到服务器供用户使用,然后查看门户上显示的遥测数据。

  • 请确保防火墙允许应用程序将遥测数据发送到以下端口:

    • dc.services.visualstudio.com:443
    • f5.services.visualstudio.com:443
  • 如果必须通过防火墙路由传出流量,需定义系统属性 http.proxyHosthttp.proxyPort

  • 在 Windows 服务器上,安装:

Azure 应用服务、AKS、VM 配置

若要监视在任何 Azure 资源提供程序上运行的应用程序,最佳、最简单的方法是通过 Java 3.0 代理使用 Application Insights 自动检测。

异常和请求失败

Application Insights Web 筛选器会自动收集未经处理的异常和请求失败。

若要收集有关其他异常的数据,可以在代码中插入对 trackException() 的调用

监视方法调用和外部依赖项

安装 Java 代理 ,记录指定的内部方法、通过 JDBC 发出的调用以及计时数据。

该代理还可用于自动操作命名。

W3C 分布式跟踪

Application Insights Java SDK 现支持 W3C 分布式跟踪

有关关联的文章中进一步解释了传入的 SDK 配置。

AI-Agent.xml 文件中定义了传出 SDK 配置。

性能计数器

打开“调查”、“指标”,查看一系列性能计数器 。

已选中进程专用字节的指标窗格的屏幕截图

自定义性能计数器收集

若要禁用收集标准性能计数器集,请将以下代码添加到 ApplicationInsights.xml 文件的根节点下:

    <PerformanceCounters>
       <UseBuiltIn>False</UseBuiltIn>
    </PerformanceCounters>

收集其他性能计数器

可以指定要收集的其他性能计数器。

JMX 计数器(由 Java 虚拟机公开)

    <PerformanceCounters>
      <Jmx>
        <Add objectName="java.lang:type=ClassLoading" attribute="TotalLoadedClassCount" displayName="Loaded Class Count"/>
        <Add objectName="java.lang:type=Memory" attribute="HeapMemoryUsage.used" displayName="Heap Memory Usage-used" type="composite"/>
      </Jmx>
    </PerformanceCounters>
  • displayName - Application Insights 门户中显示的名称。
  • objectName - JMX 对象名称。
  • attribute - 要提取的 JMX 对象名称属性
  • type(可选)- JMX 对象的属性类型:
    • 默认值:简单类型,例如 int 或 long。
    • composite:性能计数器数据采用“Attribute.Data”格式
    • tabular:性能计数器数据采用表行格式

Windows 性能计数器

每个 Windows 性能计数器 是类别的成员(就好比字段是类的成员)。 类别可以是全局的,也可以是带编号的实例或命名实例。

    <PerformanceCounters>
      <Windows>
        <Add displayName="Process User Time" categoryName="Process" counterName="%User Time" instanceName="__SELF__" />
        <Add displayName="Bytes Printed per Second" categoryName="Print Queue" counterName="Bytes Printed/sec" instanceName="Fax" />
      </Windows>
    </PerformanceCounters>
  • displayName - Application Insights 门户中显示的名称。
  • categoryName - 与此性能计数器关联的性能计数器类别(性能对象)。
  • counterName - 性能计数器的名称。
  • instanceName - 性能计数器类别实例的名称,如果类别包含单个实例,则为空字符串 ("")。 如果 categoryName 为 Process,而要收集的性能计数器来自应用运行所在的当前 JVM 进程,请指定 "__SELF__"

Unix 性能计数器

获取用户和会话数据

好了,现在正在从 Web 服务发送遥测数据。 若要获取应用程序的 360 度全方位视图,可以添加更多监视:

发送自己的遥测数据

安装 SDK 后,可以使用 API 发送自己的遥测数据。

存在疑问? 遇到问题?

Java 故障排除

后续步骤