Upgrade des Application Insights Java 2.x SDK

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

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

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

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

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

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.

Telemetrieprozessoren

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.

Operationsnamen

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

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:

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):

1. 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).

   Es entspricht jeder Telemetrie, die Attribute mit dem Namen http.request.method und url.path aufweist.

   Anschließend extrahiert es das url.path-Attribut in ein neues Attribut mit dem Namen tempName.

2. 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 Bereichsname basierend auf dem Attribut tempPath aktualisiert.

3. Der letzte Telemetrieprozessor ist ein Attributprozessor, der dem ersten Telemetrieprozessor entspricht.

   Es entspricht jeder Telemetrie, die über ein Attribut mit dem Namen tempPath verfügt.

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

Stichproben und fehlende Protokolldaten

Stichprobenentnahme mit Ratenbegrenzung ist standardmäßig aktiviert, beginnend mit dem 3.4-Agent, was zu unerwarteten fehlenden Protokollen führen kann.

Beispielprojekt

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