Application Insights Java 2.x SDK からのアップグレード

[アーティクル]
10/15/2024

通常、3.x にアップグレードするときにコードの変更はありません。 3.x SDK の依存関係は、2.x SDK 依存関係の no-op API バージョンです。ただし、3.x Java エージェントと共に使用すると、3.x Java エージェントがそれらの実装を提供します。その結果、カスタムインストルメンテーションが、3.x Java エージェントによって提供されるすべての新しい自動インストラメンテーションと相関します。

ステップ 1: 依存関係を更新する

2.x の依存関係	アクション	解説
`applicationinsights-core`	バージョンを `3.4.3` 以降に更新します
`applicationinsights-web`	バージョンを `3.4.3` 以降に更新し、Application Insights Web フィルターを `web.xml` ファイルから削除します。
`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:... を前の例に置き換えるだけです。

Note

spring-boot-starter を使っていて、それがよい場合は、Java エージェントを使用する代わりの方法があります。 3.x Spring Boot に関する記事をご覧ください。

ステップ 3: Application Insights の接続文字列を構成する

接続文字列の構成に関する記事をご覧ください。

他の注意事項

このドキュメントの残りの部分では、2.x から 3.x にアップグレードするときに発生する可能性のある制限事項と変更点、役立つと思われる回避策について説明します。

TelemetryInitializers

3.x エージェントを使用している場合、2.x SDK TelemetryInitializers は実行されません。以前に TelemetryInitializer を記述する必要があったユースケースの多くは、Application Insights Java 3.x でカスタムディメンションを構成することで解決できます。または、継承された属性を使います。

TelemetryProcessors

3.x エージェントを使用している場合、2.x SDK TelemetryProcessors は実行されません。以前に TelemetryProcessor を記述する必要があったユースケースの多くは、Application Insights Java 3.x でサンプリングオーバーライドを構成することで解決できます。

1 つの 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 という名前の新しい属性に抽出します。
2 番目のテレメトリプロセッサは、スパンプロセッサ (種類は 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 エージェントを使用して新しいプロジェクトに移行されます。

次の方法で共有