從 Application Insights Java 2.x SDK 升級

發行項
04/22/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.5.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 入口網站 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" }
        ]
      }
    ]
  }
}