Upgrade des Application Insights Java 2.x SDK

Artikel
10/15/2024

Bei einem Upgrade auf 3.x gibt es in der Regel keine Codeänderungen. Die 3.x SDK-Abhängigkeiten sind nicht operative API-Versionen der 2.x SDK-Abhängigkeiten. Bei Verwendung mit dem 3.x-Java-Agent stellt der 3.x-Java-Agent jedoch die Implementierung für sie bereit. Daher korreliert Ihre benutzerdefinierte Instrumentierung mit der gesamten neuen automatischen Instrumentierung, die vom 3.x-Java-Agent bereitgestellt wird.

Schritt 1: Aktualisieren der Abhängigkeiten

2.x-Abhängigkeit	Aktion	Bemerkungen
`applicationinsights-core`	Aktualisieren der Version auf `3.4.3` oder höher
`applicationinsights-web`	Aktualisieren Sie die Version auf `3.4.3` oder höher, und entfernen Sie den Application Insights-Webfilter Ihrer `web.xml`-Datei.
`applicationinsights-web-auto`	Ersetzen durch `3.4.3` oder einer höheren Version von `applicationinsights-web`
`applicationinsights-logging-log4j1_2`	Entfernen Sie die Abhängigkeit und den Application Insights-Appender aus Ihrer Log4j-Konfiguration.	Wird nicht mehr benötigt, da Log4j 1.2 automatisch in den 3.x-Java-Agent integriert ist.
`applicationinsights-logging-log4j2`	Entfernen Sie die Abhängigkeit und den Application Insights-Appender aus Ihrer Log4j-Konfiguration.	Wird nicht mehr benötigt, da Log4j 2 automatisch in den 3.x-Java-Agent integriert ist.
`applicationinsights-logging-logback`	Entfernen Sie die Abhängigkeit und den Application Insights-Appender aus Ihrer Logback-Konfiguration.	Wird nicht mehr benötigt, da Logback automatisch in den 3.x-Java-Agent integriert ist.
`applicationinsights-spring-boot-starter`	Ersetzen durch `3.4.3` oder einer höheren Version von `applicationinsights-web`	Der Name der Cloudrolle lautet nicht mehr standardmäßig `spring.application.name`. Informationen zum Konfigurieren des Cloudrollennamens finden Sie in der Dokumentation zur 3.x-Konfiguration.

Schritt 2: Hinzufügen des 3.x-Java-Agents

Fügen Sie Ihren JVM-Befehlszeilenargumenten (Java Virtual Machine) den 3.x-Java-Agent hinzu, z. B.:

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

Wenn Sie den 2.x-Java-Agent von Application Insights verwenden, ersetzen Sie einfach Ihren vorhandenen -javaagent:... durch das vorherige Beispiel.

Hinweis

Wenn Sie den Spring Boot Starter verwendet haben, gibt es eine Alternative zur Verwendung des Java-Agents. Siehe 3.x-Spring Boot.

Schritt 3: Konfigurieren der Application Insights-Verbindungszeichenfolge

Siehe Konfigurieren der Verbindungszeichenfolge.

Sonstige Hinweise

Im restlichen Dokument werden die Einschränkungen und Änderungen beschrieben, die beim Upgrade von 2.x auf 3.x auftreten können, sowie einige Problemumgehungen, die für Sie nützlich sein können.

TelemetryInitializers

TelemetryInitializers des 2.x SDK werden bei Verwendung des 3.x-Agents nicht ausgeführt. Viele der Anwendungsfälle, in denen das Schreiben eines TelemetryInitializer erforderlich war, können in Application Insights Java 3.x gelöst werden, indem benutzerdefinierte Dimensionen konfiguriert werden. Oder mithilfe von geerbten Attributen.

TelemetryProcessors

TelemetryProcessors des 2.x SDK werden bei Verwendung des 3.x-Agents nicht ausgeführt. Viele der Anwendungsfälle, in denen das Schreiben eines TelemetryProcessor erforderlich war, können in Application Insights Java 3.x gelöst werden, indem Stichprobenüberschreibungen konfiguriert werden.

Mehrere Anwendungen in einer einzelnen JVM

Dieser Anwendungsfall wird in Application Insights Java 3.x mithilfe von Cloudrollennamen-Überschreibungen (Vorschau) und/oder Verbindungszeichenfolgen-Überschreibungen (Vorschau) unterstützt.

Vorgangsnamen

Im Java 2.x SDK von Application Insights enthielten die Vorgangsnamen in einigen Fällen den vollständigen Pfad, z. B.:

Screenshot: Vorgangsnamen mit vollständigem Pfad

Die Vorgangsnamen in Java 3.x für Application Insights wurden geändert, um allgemein eine bessere aggregierte Ansicht auf der Benutzeroberfläche des Application Insights-Portals zu bieten. Beispiel:

Screenshot mit parametrisierten Vorgangsnamen

Bei einigen Anwendungen ziehen Sie aber möglicherweise die aggregierte Ansicht auf der Benutzeroberfläche vor, die von den vorherigen Vorgangsnamen bereitgestellt wurde. In diesem Fall können Sie das Feature Telemetrieprozessoren (Vorschau) in 3.x verwenden, um das vorherige Verhalten zu replizieren.

Mit dem folgenden Codeausschnitt werden drei Telemetrieprozessoren konfiguriert, die zum Replizieren des vorherigen Verhaltens kombiniert werden. Die Telemetrieprozessoren führen die folgenden Aktionen aus (in der angegebenen Reihenfolge):

Der erste Telemetrieprozessor ist ein Attributprozessor (Typ attribute). Das bedeutet, dass er für alle Telemetrien zutrifft, die über Attribute verfügen (derzeit requests und dependencies, bald aber auch traces).

Er sucht nach Telemetrien, die über Attribute mit dem Namen http.request.method und url.path verfügen.

Anschließend extrahiert es das url.path-Attribut in ein neues Attribut mit dem Namen tempName.
Der zweite Telemetrieprozessor ist ein Span-Prozessor (Typ span). Das bedeutet, dass er für requests und dependencies zutrifft.

Dies stimmt mit allen Spans überein, die über ein Attribut mit dem Namen tempPath verfügen.

Anschließend wird der Span-Name aus dem Attribut tempPath aktualisiert.
Der letzte Telemetrieprozessor ist ein Attributprozessor, der dem ersten Telemetrieprozessor entspricht.

Er sucht nach Telemetrien, die über ein Attribut mit dem Namen tempPath verfügen.

Anschließend wird das Attribut tempPath gelöscht, und das Attribut wird als benutzerdefinierte Dimension angezeigt.

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

Beispielprojekt

Dieses Java 2.x SDK-Projekt wird mithilfe des 3.x Java-Agenten zu einem neuen Projekt migriert.

Freigeben über