从 Application Insights Java 2.x SDK 升级

项目
08/08/2024

升级到 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`	将其替换为 `applicationinsights-web` 的 `3.4.3` 或更高版本
`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`	将其替换为 `applicationinsights-web` 的 `3.4.3` 或更高版本	云角色名称不再默认为 `spring.application.name`。若要了解如何配置云角色名称，请参阅 3.x 配置文档。

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

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

-javaagent:path/to/applicationinsights-agent-3.5.4.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 未运行。许多以前需要写入 TelemetryInitializer 的用例可以在 Application Insights Java 3.x 中通过配置自定义维度来解决。或使用继承的属性。

TelemetryProcessors

使用 3.x 代理时，2.x SDK TelemetryProcessor 未运行。许多以前需要写入 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" }
        ]
      }
    ]
  }
}

项目示例

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

通过