适用于 Java 应用程序的 Azure Monitor 基于 OpenTelemetry 的自动检测

本文介绍如何启用和配置基于 OpenTelemetry 的 Azure Monitor Java 产品/服务。 它可用于任何环境,包括本地。 按照本文说明执行操作后,你将能够使用 Azure Monitor Application Insights 来监视应用程序。

注意

对检测密钥引入的支持将于 2025 年 3 月 31 日结束。 检测密钥引入功能将会继续工作,但我们将不再为该功能提供更新或支持。 转换为连接字符串,以利用新功能

入门

通过配置更改启用 Java 自动检测;无需更改代码。

先决条件

启用 Azure Monitor Application Insights

本部分介绍如何下载自动检测 jar 文件。

下载 jar 文件

下载 applicationinsights-agent-3.4.2.jar 文件。

警告

如果是从较早的 3.x 版本升级,

从 3.4.0 开始:

  • 速率限制采样现在是默认设置(如果之前没有配置固定百分比)。 默认情况下,它将每秒最多捕获大约 5 个请求(以及其依赖项、跟踪和自定义事件)。 如果希望还原到以前捕获 100% 请求的行为,请参阅固定百分比采样

从 3.3.0 开始:

  • LoggingLevel 在默认情况下不会作为跟踪的自定义维度的组成部分被捕获,因为该数据已在 SeverityLevel 字段中被捕获。 若要详细了解在需要的情况下如何重新启用此功能,请参阅配置选项
  • 不再为失败的依赖项记录异常记录,仅为失败的请求记录它们。

从 3.2.0 开始:

  • 默认情况下,控制器“InProc”依赖项不再被捕获。 若要详细了解如何重新启用这些功能,请参阅配置选项
  • 数据库依赖项名称现在更简洁,data 字段中仍显示完整(净化)的查询。 HTTP 依赖项名称现在更具描述性。 如果自定义仪表板或警报依赖于以前的值,则这一更改可能会影响这些仪表板或警报。 有关详细信息,请参阅 3.2.0 发行说明

从 3.1.0 开始:

  • 操作名称和请求遥测名称现在以 http 方法为前缀,例如 GETPOST。 如果自定义仪表板或警报依赖于以前的值,则这一更改可能会影响这些仪表板或警报。 有关详细信息,请参阅 3.1.0 发行说明

将 JVM 指向 jar 文件

-javaagent:"path/to/applicationinsights-agent-3.4.2.jar" 添加到应用程序的 JVM 参数。

提示

有关配置应用程序的 JVM 参数的帮助,请参阅更新 JVM 参数的技巧

提示

如果开发 Spring Boot 应用程序,可以使用编程配置替换 JVM 参数。 在此处了解详细信息。

设置 Application Insights 连接字符串

  1. 可以通过两种方式将 jar 文件指向 Application Insights 资源:

    • 可以设置环境变量:

      APPLICATIONINSIGHTS_CONNECTION_STRING=<Copy connection string from Application Insights Resource Overview>
      
    • 也可以创建名为 applicationinsights.json 的配置文件。 将其放在具有以下内容 applicationinsights-agent-3.4.2.jar 所在的目录:

      {
        "connectionString": "Copy connection string from Application Insights Resource Overview"
      }
      
  2. 在 Application Insights 资源上查找连接字符串。

    显示 Application Insights 概述和连接字符串的屏幕截图。

确认有数据流

运行应用程序,然后打开 Azure 门户中的“Application Insights 资源”选项卡。 数据可能在数分钟后才会显示在门户中。

注意

如果无法运行应用程序或未如预期获取数据,请参阅故障排除一节。

屏幕截图显示了“Application Insights 概述”选项卡,其中突出显示服务器请求和服务器响应时间。

重要

如果有两个或多个服务向同一 Application Insights 资源发出遥测数据,则需要设置云角色名称以在应用程序映射中正确表示这些服务。

在使用 Application Insights 检测的过程中,我们会收集诊断数据并将其发送给 Microsoft。 这些数据可帮助我们运行和改进 Application Insights。 可以禁用非基本数据收集。 若要了解更多信息,请参阅 Azure Application Insights 中的 Statsbeat

配置选项

applicationinsights.json 文件中,还可以配置下列设置:

  • 云角色名称
  • 云角色实例
  • 采样
  • JMX 指标
  • 自定义维度
  • 遥测处理器(预览版)
  • 自动收集的日志记录
  • 自动收集的 Micrometer 指标(包括 Spring Boot Actuator 指标)
  • 检测信号
  • HTTP 代理
  • 自我诊断

有关详细信息,请参阅配置选项

自动检测

Java 3.x 包括以下自动检测。

自动收集的请求

  • JMS 使用者
  • Kafka 使用者
  • Netty/WebFlux
  • Quartz
  • Servlet
  • Spring 计划

自动收集的依赖项

自动收集的依赖项和下游分布式跟踪传播:

  • Apache HttpClient
  • Apache HttpAsyncClient
  • AsyncHttpClient
  • Google HttpClient
  • gRPC
  • java.net.HttpURLConnection
  • Java 11 HttpClient
  • JAX-RS client
  • Jetty HttpClient
  • JMS
  • Kafka
  • Netty 客户端
  • OkHttp

自动收集的依赖项(无下游分布式跟踪传播):

  • Cassandra
  • JDBC
  • MongoDB(异步和同步)
  • Redis(Lettuce 和 Jedis)

自动收集的日志记录

  • Log4j(包含 MDC/线程上下文属性)
  • Logback(包含 MDC 属性)
  • JBoss Logging(包含 MDC 属性)
  • java.util.logging

自动收集的指标

  • Micrometer(包括 Spring Boot Actuator 指标)
  • JMX 指标

Azure SDK

默认情况下,自动收集以下 Azure SDK 发出的遥测数据:

修改遥测

本部分介绍如何修改遥测。

添加跨度

添加你自己的跨度的最简单方法是使用 OpenTelemetry 的 @WithSpan 注释。

范围会填充 Application Insights 中的 requestsdependencies 表。

注意

此功能仅在 3.2.0 及更高版本中提供。

  1. 向应用程序添加 opentelemetry-extension-annotations-1.16.0.jar

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-extension-annotations</artifactId>
      <version>1.16.0</version>
    </dependency>
    
  2. 每次执行你的方法时,使用 @WithSpan 注释发出一个跨度:

     import io.opentelemetry.extension.annotations.WithSpan;
    
     @WithSpan(value = "your span name")
     public void yourMethod() {
     }
    

默认情况下,该跨度将在依赖项表中以依赖项类型 InProc 结束。

如果你的方法代表一个尚未被自动检测捕获的后台作业,则建议将属性 kind = SpanKind.SERVER 应用到 @WithSpan 注释,以便它最终出现在 Application Insights requests 表中。

添加跨度事件

可以使用 opentelemetry-api 来创建跨度事件,这些事件会填充 Application Insights 中的跟踪表。 传入到 addEvent() 的字符串会保存到跟踪中的消息字段。

注意

此功能仅在 3.2.0 及更高版本中提供。

  1. 向应用程序添加 opentelemetry-api-1.6.0.jar

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. 在代码中添加跨度事件:

     import io.opentelemetry.api.trace.Span;
    
     Span.current().addEvent("eventName");
    

添加范围属性

可以使用 opentelemetry-api 向范围中添加属性。 这些属性可能包括向遥测添加自定义业务维度。 还可以使用属性来设置 Application Insights 架构中的可选字段,如用户 ID 或客户端 IP。

添加一个或多个范围属性将填充请求、依赖项、跟踪或异常表中的 customDimensions 字段。

注意

此功能仅在 3.2.0 及更高版本中提供。

  1. 向应用程序添加 opentelemetry-api-1.6.0.jar

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. 在代码中添加自定义维度:

     import io.opentelemetry.api.trace.Span;
     import io.opentelemetry.api.common.AttributeKey;
    
     AttributeKey attributeKey = AttributeKey.stringKey("mycustomdimension");
     Span.current().setAttribute(attributeKey, "myvalue1");
    

更新跨度状态和记录异常

可以使用 opentelemetry-api 来更新跨度的状态并记录异常。

注意

此功能仅在 3.2.0 及更高版本中提供。

  1. 向应用程序添加 opentelemetry-api-1.6.0.jar

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. 将状态设置为错误,并记录代码中的异常:

     import io.opentelemetry.api.trace.Span;
     import io.opentelemetry.api.trace.StatusCode;
    
     Span span = Span.current();
     span.setStatus(StatusCode.ERROR, "errorMessage");
     span.recordException(e);
    

设置用户 ID

填充请求、依赖项或异常表中的用户 ID 字段。

重要

在设置经过身份验证的用户 ID 之前,请参考适用的隐私法律。

注意

此功能仅在 3.2.0 及更高版本中提供。

  1. 向应用程序添加 opentelemetry-api-1.6.0.jar

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. 在代码中设置 user_Id

    import io.opentelemetry.api.trace.Span;
    
    Span.current().setAttribute("enduser.id", "myuser");
    

获取跟踪 ID 或范围 ID

可以使用 opentelemetry-api 获取跟踪 ID 或范围 ID。 执行此操作的目的是将这些标识符添加到现有日志记录遥测中,以便在调试和诊断问题时改善关联性。

注意

此功能仅在 3.2.0 及更高版本中提供。

  1. 向应用程序添加 opentelemetry-api-1.6.0.jar

    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.6.0</version>
    </dependency>
    
  2. 在代码中获取请求跟踪 ID 和范围 ID:

    import io.opentelemetry.api.trace.Span;
    
    Span span = Span.current();
    String traceId = span.getSpanContext().getTraceId();
    String spanId = span.getSpanContext().getSpanId();
    

自定义遥测

我们在 Application Insights Java 3.x 版本中的目标是让你能够使用标准 API 发送自定义遥测。

我们目前支持 Micrometer、常用日志记录框架和 Application Insights Java 2.x SDK。 Application Insights Java 3.x 会自动捕获通过这些 API 发送的遥测,并将其与自动收集的遥测相关联。

支持的自定义遥测

下表显示了当前支持的自定义遥测类型,你可以使用它们来对 Java 3.x 代理进行补充。 总结:

  • Micrometer 支持自定义指标。
  • 日志记录框架支持自定义异常和跟踪。
  • opentelemetry-api 支持自定义请求、依赖项、指标和异常。
  • Application Insights Java 2.x SDK 支持所有类型的自定义遥测。
自定义遥测类型 Micrometer Log4j、logback、JUL 2.x SDK opentelemetry-api
自定义事件
自定义指标
依赖项
异常
页面视图
请求
跟踪

我们目前不打算发布带有 Application Insights 3.x 的 SDK。

Application Insights Java 3.x 已在侦听发送到 Application Insights Java 2.x SDK 的遥测。 对于现有的 2.x 用户来说,此功能是升级案例的重要组成部分。 在所有自定义遥测类型都能通过 OpenTelemetry API 获得支持之前,它填补了我们在自定义遥测支持方面的一个重要空白。

使用 Micrometer 发送自定义指标

  1. 将 Micrometer 添加到应用程序:

    <dependency>
      <groupId>io.micrometer</groupId>
      <artifactId>micrometer-core</artifactId>
      <version>1.6.1</version>
    </dependency>
    
  2. 使用 Micrometer 全局注册表来创建计量:

    static final Counter counter = Metrics.counter("test.counter");
    
  3. 使用计数器记录指标:

    counter.increment();
    
  4. 这些指标将被引入到 customMetrics 表中,带有在 列中捕获的标记。 你也可在“基于日志的指标”指标命名空间下的指标资源管理器中查看指标。

    注意

    Application Insights Java 将 Micrometer 指标名称中的所有非字母数字字符(破折号除外)替换为下划线,因此上面的 test.counter 指标将显示为 test_counter

使用你喜爱的日志记录框架发送自定义跟踪和异常

自动检测 Log4j、Logback 和 java.util.logging。 自动将通过这些日志记录框架执行的日志记录收集为跟踪和异常遥测。

默认情况下,仅当在 INFO 级别或更高级别执行日志记录时,才收集该日志记录。 若要更改此级别,请参阅配置选项

如果要将自定义维度附加到日志,可以使用 Log4j 1.2 mdcLog4j 2 MDCLogback MDC。 Application Insights Java 3.x 会自动将这些 MDC 属性捕获为跟踪和异常遥测中的自定义维度。

使用 2.x SDK 发送自定义遥测

  1. 向应用程序添加 applicationinsights-core-2.6.4.jar。 Application Insights Java 3.x 支持所有 2.x 版本。 如果可以,最好使用最新版本:

    <dependency>
      <groupId>com.microsoft.azure</groupId>
      <artifactId>applicationinsights-core</artifactId>
      <version>2.6.4</version>
    </dependency>
    
  2. 创建 TelemetryClient:

    static final TelemetryClient telemetryClient = new TelemetryClient();
    
  3. 使用客户端发送自定义遥测数据:

    事件
    telemetryClient.trackEvent("WinGame");
    
    指标
    telemetryClient.trackMetric("queueLength", 42.0);
    
    依赖项
    boolean success = false;
    long startTime = System.currentTimeMillis();
    try {
        success = dependency.call();
    } finally {
        long endTime = System.currentTimeMillis();
        RemoteDependencyTelemetry telemetry = new RemoteDependencyTelemetry();
        telemetry.setSuccess(success);
        telemetry.setTimestamp(new Date(startTime));
        telemetry.setDuration(new Duration(endTime - startTime));
        telemetryClient.trackDependency(telemetry);
    }
    
    日志
    telemetryClient.trackTrace(message, SeverityLevel.Warning, properties);
    
    异常
    try {
        ...
    } catch (Exception e) {
        telemetryClient.trackException(e);
    }
    

故障排除

请参阅专用疑难解答文章

测试应用程序主机与引入服务之间的连接性

Application Insights SDK 和代理发送遥测,将其作为 REST 调用引入到引入终结点。 可以使用原始 REST 客户端通过 PowerShell 或使用 curl 命令,测试从 Web 服务器或应用程序主机计算机到引入服务终结点的连接。 请参阅排查 Azure Monitor Application Insights 中缺失应用程序遥测的问题

发行说明

在 GitHub 上查看发行说明

支持

若要获取支持,请查看以下内容:

OpenTelemetry 反馈

若要提供反馈,请查看以下内容:

后续步骤