Mise à niveau à partir du SDK Application Insights pour Java 2.x

Article
10/15/2024

Il n’existe généralement aucune modification du code lors de la mise à niveau vers la version 3.x. Les dépendances du KIT de développement logiciel (SDK) 3.x sont des versions d’API sans opération des dépendances du SDK 2.x. Toutefois, lorsqu’il est utilisé avec l’agent Java 3.x, l’agent Java 3.x fournit l’implémentation pour eux. Par conséquent, votre instrumentation personnalisée est corrélée avec toutes les nouvelles autoinstrumentations fournies par l’agent Java 3.x.

Étape 1 : Mettre à jour les dépendances

Dépendance 2.x	Action	Remarques
`applicationinsights-core`	Mettre à jour la version vers `3.4.3` ou une version ultérieure
`applicationinsights-web`	Mettez à jour la version vers `3.4.3` ou une version ultérieure, puis supprimez le filtre web Application Insights de votre fichier `web.xml`.
`applicationinsights-web-auto`	Remplacez par `3.4.3` ou version ultérieure de `applicationinsights-web`
`applicationinsights-logging-log4j1_2`	Supprimez la dépendance et supprimez l’appender Application Insights de votre configuration Log4j.	Il n’est plus nécessaire, car Log4j 1.2 est instrumenté automatiquement dans l’agent Java 3.x.
`applicationinsights-logging-log4j2`	Supprimez la dépendance et supprimez l’appender Application Insights de votre configuration Log4j.	Il n’est plus nécessaire, car Log4j 2 est instrumenté automatiquement dans l’agent Java 3.x.
`applicationinsights-logging-logback`	Supprimez la dépendance et supprimez l’appender Application Insights de votre configuration Logback.	Il n’est plus nécessaire, car Logback est instrumenté automatiquement dans l’agent Java 3.x.
`applicationinsights-spring-boot-starter`	Remplacez par `3.4.3` ou version ultérieure de `applicationinsights-web`	Le nom du rôle cloud n’est plus défini par défaut sur `spring.application.name`. Pour savoir comment configurer le nom du rôle cloud, consultez la documentation de configuration 3.x.

Étape 2 : Ajouter l’agent Java 3.x

Ajoutez l’agent Java 3.x à vos arguments de ligne de commande JVM (Java Virtual Machine), par exemple :

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

Si vous utilisez l’agent Java Application Insights 2.x, remplacez simplement votre -javaagent:... existante par l’exemple précédent.

Remarque

Si vous utilisiez spring-boot-starter et si vous préférez cela, il existe une alternative à l’utilisation de l’agent Java. Voir 3.x Spring Boot.

Étape 3 : Configurer votre chaîne de connexion Application Insights

Consultez Configuration de la chaîne de connexion.

Autres remarques

Le reste de ce document décrit les limitations et les modifications que vous pouvez rencontrer lors de la mise à niveau de 2.x vers 3.x, et certaines solutions de contournement que vous pouvez trouver utiles.

TelemetryInitializers

La fonction TelemetryInitializer du Kit de développement logiciel (SDK) 2.x ne s’exécute pas lors de l’utilisation de l’agent 3.x. La plupart des cas d’usage, demandant précédemment la rédaction d’un TelemetryInitializer, peuvent être résolus dans Application Insights Java 3.x en configurant les dimensions personnalisées. Ou au moyen des attributs hérités.

TelemetryProcessors

La fonction TelemetryProcessor du Kit de développement logiciel (SDK) 2.x ne s’exécute pas lors de l’utilisation de l’agent 3.x. La plupart des cas d’usage, demandant précédemment la rédaction d’un TelemetryProcessor, peuvent être résolus dans Application Insights Java 3.x en configurant la substitution de l’échantillonnage.

Plusieurs applications dans une seule Machine virtuelle Java

Ce cas d’usage est pris en charge dans Application Insights Java 3.x à l’aide des remplacements de nom de rôle cloud (préversion) et/ou des remplacements de chaîne de connexion (préversion).

Noms des opérations

Dans le SDK Application Insights Java 2.x, les noms d’opérations contenaient parfois le chemin complet, par exemple :

Capture d’écran montrant les noms d’opération avec le chemin d’accès complet

Dans Application Insights Java 3.x, le nom des opérations a été modifié de manière à offrir une meilleure vue de synthèse dans le portail Application Insights, par exemple :

Capture d’écran montrant les noms d’opérations paramétrables

Cependant, pour certaines applications, il est possible que vous préfériez encore la vue agrégée dans l'U/X qui était fournie par les noms d'opération précédents. Dans ce cas, vous pouvez utiliser la fonctionnalité processeurs de télémétrie (préversion) dans 3.x pour répliquer le comportement précédent.

L’extrait de code suivant configure trois processeurs de télémétrie qui s’associent pour répliquer le comportement précédent. Les processeurs de télémétrie effectuent les actions suivantes (dans l’ordre indiqué) :

Le premier processeur de télémétrie est un processeur d’attribut (de type attribute), ce qui signifie qu’il s’applique à toutes les données de télémétrie qui ont des attributs (requests, dependencies mais bientôt traces aussi).

Il correspond à n’importe quelles données de télémétrie comprenant des attributs nommés http.request.method et url.path.

Il extrait ensuite l’attribut url.path dans un nouvel attribut nommé tempName.
Le deuxième processeur de télémétrie est un processeur d’étendue (de type span), ce qui signifie qu’il s’applique à requests et dependencies.

Il correspond à n’importe quelle étendue comprenant un attribut nommé tempPath.

Ensuite, il met à jour le nom de l’étendue à partir de l’attribut tempPath.
Le dernier processeur de télémétrie est un processeur d’attributs, du même type que le premier.

Il correspond à n’importe quelles données de télémétrie comprenant un attribut nommé tempPath.

Ensuite, il supprime l’attribut nommé tempPath, et l’attribut apparaît sous la forme d’une dimension personnalisée.

{
  "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" }
        ]
      }
    ]
  }
}

Exemple de projet

Ce projet de Kit de développement logiciel (SDK) Java 2.x est migré vers un nouveau projet utilisant l’agent Java 3.x.

Partager via