從 Application Insights Java 2.x SDK 升級

發行項
10/15/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 網路篩選條件。
`applicationinsights-web-auto`	取代為 `3.4.3` 或更新版本的 `applicationinsights-web`
`applicationinsights-logging-log4j1_2`	移除相依性，並從 Log4j 設定中移除 Application Insights 附加器。	由於 Log4j 1.2 版本會在 3.x 版本的 JAVA 代理程式中自動檢測，因此不再需要。
`applicationinsights-logging-log4j2`	移除相依性，並從 Log4j 設定中移除 Application Insights 附加器。	由於 Log4j 2 版本會在 3.x 版本的 JAVA 代理程式中自動檢測，因此不再需要。
`applicationinsights-logging-logback`	移除相依性，並從您的 Logback 設定中移除 Application Insights 附加器。	由於 Logback 版本會在 3.x 版本的 JAVA 代理程式中自動檢測，因此不再需要。
`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.6.2.jar

如果您正在使用 Application Insights 2.x 版本的 JAVA 代理程式，只要將現有的 -javaagent:... 取代為上述範例即可。

注意

如果您正在且偏好使用 spring-boot-starter 的話，還能使用 JAVA 代理程式的替代方案。請參閱 3.x 版本的 Spring Boot。

步驟 3：設定 Application Insights 連接字串

請參閱設定連接字串。

訂單備註

本文件的其餘部分說明從 2.x 升級至 3.x 時可能會遇到的限制和變更，以及一些您可能覺得有用的因應措施。

TelemetryInitializers

2.x SDK TelemetryInitializers 在使用 3.x 代理程式時不會執行。許多先前需要撰寫 TelemetryInitializer 的使用案例都可以設定自訂維度在 Application Insights Java 3.x 中解決。也可以使用繼承的屬性。

TelemetryProcessors

2.x SDK TelemetryProcessors 在使用 3.x 代理程式時不會執行。許多先前需要撰寫 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 Portal U/X 中提供更佳的彙總檢視，例如:

顯示參數化作業名稱的螢幕擷取畫面

不過，針對某些應用程式，您可能仍然偏好使用 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 代理程式移轉至新專案。

共用方式為