你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

项目
01/06/2023

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

注意

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

入门

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

先决条件

使用 Java 8+ 的 Java 应用程序
Azure 订阅：免费创建 Azure 订阅
Application Insights 资源：创建 Application Insights 资源

启用 Azure Monitor Application Insights

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

下载 jar 文件

下载 applicationinsights-agent-3.4.7.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 方法为前缀，例如 GET 和 POST。如果自定义仪表板或警报依赖于以前的值，则这一更改可能会影响这些仪表板或警报。有关详细信息，请参阅 3.1.0 发行说明。

将 JVM 指向 jar 文件

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

提示

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

提示

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

设置 Application Insights 连接字符串

可以通过两种方式将 jar 文件指向 Application Insights 资源：
- 可以设置环境变量：
```
APPLICATIONINSIGHTS_CONNECTION_STRING=<Copy connection string from Application Insights Resource Overview>
```
- 也可以创建名为 applicationinsights.json 的配置文件。将其放在具有以下内容 applicationinsights-agent-3.4.7.jar 所在的目录：
```
{
  "connectionString": "Copy connection string from Application Insights Resource Overview"
}
```
在 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
Quartz
Servlet
Spring 计划

注意

Servlet 和 Netty 自动检测涵盖大多数 Java HTTP 服务，包括 Java EE、Jakarta EE、Spring Boot、Quarkus 和 Micronaut。

自动收集的依赖项

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

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）

自动收集的日志记录

Logback（包含 MDC 属性）
Log4j（包含 MDC/线程上下文属性）
JBoss Logging（包含 MDC 属性）
java.util.logging

自动收集的指标

Micrometer（包括 Spring Boot Actuator 指标）
JMX 指标

Azure SDK

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

修改遥测

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

使用 OpenTelemetry 注释添加范围

添加自己的范围的最简单方法是使用 OpenTelemetry 的 @WithSpan 注释。

范围会填充 Application Insights 中的 requests 和 dependencies 表。

注意

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

将 opentelemetry-instrumentation-annotations-1.21.0.jar（或更高版本）添加到应用程序：

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-instrumentation-annotations</artifactId>
  <version>1.21.0</version>
</dependency>

每次执行你的方法时，使用 @WithSpan 注释发出一个跨度：

 import io.opentelemetry.instrumentation.annotations.WithSpan;

 @WithSpan(value = "your span name")
 public void yourMethod() {
 }

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

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

使用 OpenTelemetry API 添加范围

如果上述 OpenTelemetry @WithSpan 注释不能满足你的需求，可使用 OpenTelemetry API 添加范围。

注意

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

将 opentelemetry-api-1.0.0.jar（或更高版本）添加到应用程序：

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

使用 GlobalOpenTelemetry 类创建 Tracer

 import io.opentelemetry.api.GlobalOpenTelemetry;
 import io.opentelemetry.api.trace.Tracer;

 static final Tracer tracer = GlobalOpenTelemetry.getTracer("com.example");

创建一个范围，使其成为当前范围，然后结束该范围：

 Span span = tracer.spanBuilder("my first span").startSpan();
 try (Scope ignored = span.makeCurrent()) {
     // do stuff within the context of this 
 } catch (Throwable t) {
     span.recordException(t);
 } finally {
     span.end();
 }

添加跨度事件

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

注意

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

将 opentelemetry-api-1.0.0.jar（或更高版本）添加到应用程序：

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

在代码中添加跨度事件：

 import io.opentelemetry.api.trace.Span;

 Span.current().addEvent("eventName");

添加范围属性

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

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

注意

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

将 opentelemetry-api-1.0.0.jar（或更高版本）添加到应用程序：

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

在代码中添加自定义维度：

 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 及更高版本中提供。

将 opentelemetry-api-1.0.0.jar（或更高版本）添加到应用程序：

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

将状态设置为错误，并记录代码中的异常：

 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 及更高版本中提供。

将 opentelemetry-api-1.0.0.jar（或更高版本）添加到应用程序：

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

在代码中设置 user_Id：

import io.opentelemetry.api.trace.Span;

Span.current().setAttribute("enduser.id", "myuser");

获取跟踪 ID 或范围 ID

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

注意

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

将 opentelemetry-api-1.0.0.jar（或更高版本）添加到应用程序：

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

在代码中获取请求跟踪 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 经典 SDK。 Application Insights Java 3.x 会自动捕获通过这些 API 发送的遥测，并将其与自动收集的遥测相关联。

支持的自定义遥测

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

Micrometer 支持自定义指标。
日志记录框架支持自定义异常和跟踪。
OpenTelemetry API 支持自定义请求、依赖项、指标和异常。
Application Insights 经典 SDK 支持其他遥测类型。

自定义遥测类型	Micrometer	Logback、Log4j、JUL	OpenTelemetry API	经典 SDK
自定义事件				是
自定义指标	是		是	是
依赖项			是	是
异常		是	是	是
页面视图				是
请求			是	是
跟踪		是		是

使用 Micrometer 发送自定义指标

将 Micrometer 添加到应用程序：

<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-core</artifactId>
  <version>1.6.1</version>
</dependency>

使用 Micrometer 全局注册表来创建计量：

static final Counter counter = Metrics.counter("test.counter");

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

注意

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

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

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

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

可通过以下方式实现结构化日志记录（将自定义维度附加到日志）：

Logback MDC
Log4j 2 MapMessage（"message" 的 MapMessage 键将捕获为日志消息）
Log4j 2 线程上下文
Log4j 1.2 MDC

使用 Application Insights 经典 SDK 发送自定义遥测数据

向应用程序添加 applicationinsights-core：

<dependency>
  <groupId>com.microsoft.azure</groupId>
  <artifactId>applicationinsights-core</artifactId>
  <version>3.4.7</version>
</dependency>

创建 TelemetryClient：

static final TelemetryClient telemetryClient = new TelemetryClient();

使用客户端发送自定义遥测数据：

事件

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 上查看发行说明。

支持

若要获取支持，请查看以下内容：

有关疑难解答的帮助，请参阅疑难解答步骤。
有关 Azure 支持问题，可打开 Azure 支持票证。
有关 OpenTelemetry 问题，请直接与 OpenTelemetry 社区联系。

OpenTelemetry 反馈

若要提供反馈，请查看以下内容：

填写 OpenTelemetry 社区的客户反馈调查。
加入 OpenTelemetry 早期采用者社区，告诉 Microsoft 有关你本人的信息。
在 Microsoft 技术社区与其他 Azure Monitor 用户联系。
在 Azure 反馈论坛中发出功能请求。

后续步骤

查看 Java 自动检测配置选项。
若要查看源代码，请参阅 Azure Monitor Java 自动检测 GitHub 存储库。
若要详细了解 OpenTelemetry 及其社区，请参阅 OpenTelemetry Java GitHub 存储库。
若要开启使用体验，请参阅启用 Web/浏览器用户监视。

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

入门

先决条件

启用 Azure Monitor Application Insights

下载 jar 文件

将 JVM 指向 jar 文件

设置 Application Insights 连接字符串

确认有数据流

配置选项

自动检测

自动收集的请求

自动收集的依赖项

自动收集的日志记录

自动收集的指标

Azure SDK

修改遥测

使用 OpenTelemetry 注释添加范围

使用 OpenTelemetry API 添加范围

添加跨度事件

添加范围属性

更新跨度状态和记录异常

设置用户 ID

获取跟踪 ID 或范围 ID

自定义遥测

支持的自定义遥测

使用 Micrometer 发送自定义指标

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

使用 Application Insights 经典 SDK 发送自定义遥测数据

事件

指标

依赖项

日志

异常

故障排除

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

发行说明

支持

OpenTelemetry 反馈

后续步骤

其他资源

其他资源