从 Application Insights Java 2.x SDK 升级

2025-04-30

升级到 3.x 时，通常没有任何代码更改。 3.x SDK 依赖项是 2.x SDK 依赖项的无操作 API 版本。但是，与 3.x Java 代理一起使用时，3.x Java 代理会为其提供实现。因此，自定义检测将与 3.x Java 代理提供的所有新自动检测相关联。

步骤 1：更新依赖项

2.x 依赖项	操作	注解
`applicationinsights-core`	将版本更新到 `3.4.3` 或更高版本
`applicationinsights-web`	将版本更新到 `3.4.3` 或更高版本，并从 `web.xml` 文件中删除 Application Insights Web 筛选器。
`applicationinsights-web-auto`	将其替换为 `3.4.3` 的 `applicationinsights-web` 或更高版本
`applicationinsights-logging-log4j1_2`	删除依赖项，并从 Log4j 配置中删除 Application Insights 追加器。	不再需要，因为会在 3.x Java 代理中自动检测 Log4j 1.2。
`applicationinsights-logging-log4j2`	删除依赖项，并从 Log4j 配置中删除 Application Insights 追加器。	不再需要，因为会在 3.x Java 代理中自动检测 Log4j 2。
`applicationinsights-logging-logback`	删除依赖项，并从 Logback 配置中删除 Application Insights 追加器。	不再需要，因为会在 3.x Java 代理中自动检测 Logback。
`applicationinsights-spring-boot-starter`	将其替换为 `3.4.3` 的 `applicationinsights-web` 或更高版本	云角色名称不再默认为 `spring.application.name`。若要了解如何配置云角色名称，请参阅 3.x 配置文档。

步骤 2：添加 3.x Java 代理

将 3.x Java 代理添加到 Java 虚拟机 (JVM) 命令行参数，例如：

-javaagent:path/to/applicationinsights-agent-3.7.1.jar

如果使用 Application Insights 2.x Java 代理，只需将现有 -javaagent:... 替换为上述示例即可。

注意

如果使用 spring-boot-starter，可以使用替代方法来代替使用 Java 代理（如果你愿意）。请参阅 3.x Spring Boot。

步骤 3：配置 Application Insights 连接字符串

请参阅配置连接字符串。

其他说明

本文档的其余部分介绍了从 2.x 升级到 3.x 时可能遇到的限制和更改，以及可能有帮助的一些解决方法。

TelemetryInitializers

使用 3.x 代理时，2.x SDK TelemetryInitializer 未运行。许多以前需要编写 A TelemetryInitializer 的用例可以通过配置自定义维度在 Application Insights Java 3.x 中解决。或使用继承的属性。

遥测处理器

使用 3.x 代理时，2.x SDK TelemetryProcessor 未运行。许多以前需要编写 a TelemetryProcessor 的用例可以通过配置采样替代在 Application Insights Java 3.x 中解决。

单个 JVM 中的多个应用程序

Application Insights Java 3.x 使用云角色名称替代（预览版）和/或连接字符串替代（预览版）支持此用例。

操作名称

在 Application Insights Java 2.x SDK 中，某些情况下操作名称包含完整路径，例如：

显示具有完整路径的操作名称的屏幕截图

Application Insights Java 3.x 中的操作名称已更改，从而在 Application Insights 门户 U/X 中普遍提供更好的聚合视图，例如：

显示操作名称参数化的屏幕截图

但是，对于某些应用程序，你可能仍然更喜欢以前的操作名称提供的用户体验中的聚合视图。在这种情况下，可以使用 3.x 中的遥测处理器（预览）功能复制以前的行为。

以下代码片段配置了 3 个遥测处理器，它们组合在一起来复制以前的行为。遥测处理器会（按顺序）执行以下操作：

第一个遥测处理器是属性处理器（其类型为 attribute），这意味着它适用于所有具有属性（当前是 requests、dependencies，但不久后还包括 traces）的遥测。

它将匹配具有属性 http.request.method 和 url.path 的任何遥测。

然后它将 url.path 属性提取到名为 tempName 的新属性中。
第二个遥测处理器是范围处理器（具有类型 span），这意味着它适用于 requests 和 dependencies。

它将匹配具有属性 tempPath 的任何范围。

然后，它将更新属性 tempPath 中的范围名称。
最后一个遥测处理器是属性处理器，其类型与第一个遥测处理器相同。

它将匹配具有属性 tempPath 的任何遥测。

然后，它会删除名为 tempPath 的属性，该属性显示为自定义维度。

{
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "http.request.method" },
            { "key": "url.path" }
          ]
        },
        "actions": [
          {
            "key": "url.path",
            "pattern": "https?://[^/]+(?<tempPath>/[^?]*)",
            "action": "extract"
          }
        ]
      },
      {
        "type": "span",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "tempPath" }
          ]
        },
        "name": {
          "fromAttributes": [ "http.request.method", "tempPath" ],
          "separator": " "
        }
      },
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "tempPath" }
          ]
        },
        "actions": [
          { "key": "tempPath", "action": "delete" }
        ]
      }
    ]
  }
}

采样和缺少日志

默认情况下，从 3.4 代理开始启用速率限制采样，这可能会导致意外丢失的日志。

项目示例

此 Java 2.x SDK 项目使用 3.x Java 代理迁移到新项目。

通过