Konfigurationsoptionen: Azure Monitor Application Insights für Java

In diesem Artikel wird das Konfigurieren von Azure Monitor Application Insights für Java beschrieben.

Weitere Informationen finden Sie unter Erste Schritte mit OpenTelemetry, einschließlich Beispielanwendungen.

Verbindungszeichenfolge und Rollenname

Die Verbindungszeichenfolge und der Rollenname sind die gängigsten Einstellungen, die für den Einstieg erforderlich sind:

{
  "connectionString": "...",
  "role": {
    "name": "my cloud role name"
  }
}

Eine Verbindungszeichenfolge ist erforderlich. Der Rollenname ist immer dann relevant, wenn Sie Daten unterschiedlicher Anwendungen an dieselbe Application Insights-Ressource senden.

Weitere Informationen und Konfigurationsoptionen finden Sie in den folgenden Abschnitten.

JSON-Konfigurationssetup

Standardkonfiguration

Standardmäßig erwartet Application Insights Java 3, dass die Konfigurationsdatei applicationinsights.json benannt und sich im selben Verzeichnis wie applicationinsights-agent-3.7.1.jar befindet.

Alternative Konfigurationen

Benutzerdefinierte Konfigurationsdatei

Sie können wie folgt eine benutzerdefinierte Konfigurationsdatei angeben:

• Mit der Umgebungsvariable APPLICATIONINSIGHTS_CONFIGURATION_FILE oder
• Mit der Systemeigenschaft „applicationinsights.configuration.file“

Wenn Sie einen relativen Pfad angeben, wird er relativ zum Verzeichnis aufgelöst, in dem sich applicationinsights-agent-3.7.1.jar befindet.

JSON-Konfiguration

Anstatt eine Konfigurationsdatei zu verwenden, können Sie auch wie folgt die gesamte JSON-Konfiguration festlegen:

• Mit der Umgebungsvariable APPLICATIONINSIGHTS_CONFIGURATION_CONTENT oder
• Mit der Systemeigenschaft „applicationinsights.configuration.content“

Verbindungszeichenfolge

Eine Verbindungszeichenfolge ist erforderlich. Die Verbindungszeichenfolge finden Sie in der Application Insights-Ressource.

{
  "connectionString": "..."
}

Sie können die Verbindungszeichenfolge auch mit der Umgebungsvariable APPLICATIONINSIGHTS_CONNECTION_STRING festlegen. Diese hat dann Vorrang vor der in der JSON-Konfiguration angegebenen Verbindungszeichenfolge.

Sie können die Verbindungszeichenfolge auch mithilfe der Java-Systemeigenschaft applicationinsights.connection.string festlegen. Diese hat auch Vorrang vor der in der JSON-Konfiguration angegebenen Verbindungszeichenfolge.

Sie können die Verbindungszeichenfolge auch festlegen, indem Sie eine Datei angeben, aus der die Verbindungszeichenfolge geladen werden soll.

Wenn Sie einen relativen Pfad angeben, wird dieser relativ zum Verzeichnis von applicationinsights-agent-3.7.1.jar aufgelöst.

{
  "connectionString": "${file:connection-string-file.txt}"
}

Die Datei sollte nur die Verbindungszeichenfolge und sonst nichts enthalten.

Falls die Verbindungszeichenfolge nicht festgelegt wird, wird der Java-Agent deaktiviert.

Wenn Sie mehrere Anwendungen in derselben JVM-Instanz (Java Virtual Machine) bereitgestellt haben und diese Telemetriedaten an verschiedene Verbindungszeichenfolgen senden sollen, lesen Sie Überschreiben von Verbindungszeichenfolgen (Vorschau).

Cloudrollenname

Der Name der Cloudrolle wird verwendet, um die Komponente in der Anwendungsübersicht zu bezeichnen.

Wenn Sie den Cloudrollennamen festlegen möchten:

{
  "role": {   
    "name": "my cloud role name"
  }
}

Falls der Cloudrollenname nicht festgelegt ist, wird der Name der Application Insights-Ressource zur Bezeichnung der Komponente in der Anwendungsübersicht verwendet.

Sie können den Namen der Cloudrolle auch mithilfe der Umgebungsvariablen APPLICATIONINSIGHTS_ROLE_NAME festlegen. Dieser hat dann Vorrang vor dem in der JSON-Konfiguration angegebenen Cloudrollennamen.

Sie können den Namen der Cloudrolle auch mithilfe der Java-Systemeigenschaft applicationinsights.role.name festlegen. Auch diese hat Vorrang vor dem in der JSON-Konfiguration angegebenen Cloud-Rollenname.

Wenn Sie mehrere Anwendungen in derselben JVM bereitgestellt haben und Sie wollen, dass sie Telemetriedaten an verschiedene Cloudrollennamen senden, lesen Sie Überschreiben von Cloud-Rollennamen (Vorschau).

Cloud-Rolleninstanz

Der Name der Cloudrolleninstanz entspricht standardmäßig dem Computernamen.

Wenn Sie die Cloudrolleninstanz auf einen anderen Namen als den des Rechners festlegen möchten:

{
  "role": {
    "name": "my cloud role name",
    "instance": "my cloud role instance"
  }
}

Sie können die Cloudrolleninstanz auch mithilfe der Umgebungsvariable APPLICATIONINSIGHTS_ROLE_INSTANCE festlegen. Dieser hat dann Vorrang vor der in der JSON-Konfiguration angegebenen Cloudrolleninstanz.

Sie können die Cloud-Rolleninstanz auch mithilfe der Java-Systemeigenschaft applicationinsights.role.instance festlegen. Auch hat es Vorrang vor der Cloudrolleninstanz, die in der JSON-Konfiguration angegeben ist.

Stichproben

Hinweis

Das Sampling eignet sich u. U. sehr gut dazu, die Kosten von Application Insights zu reduzieren. Stellen Sie sicher, dass Sie Ihre Samplingkonfiguration Ihrem Anwendungsfall gemäß einrichten.

Das Sampling erfolgt anforderungsbasiert, d. h., wenn eine Anforderung erfasst (gesampelt) wird, werden auch ihre Abhängigkeiten, Protokolle und Ausnahmen erfasst.

Das Sampling basiert auch auf einer Trace-ID, um konsistente Samplingentscheidungen über verschiedene Dienste hinweg zu gewährleisten.

Die Stichprobenentnahme gilt nur für Protokolle innerhalb einer Anforderung. Protokolle, die sich nicht innerhalb einer Anforderung befinden (z. B. Startprotokolle), werden standardmäßig immer erfasst. Wenn Sie Stichproben für diese Protokolle entnehmen möchten, können Sie Stichprobenüberschreibungen verwenden.

Sampling mit Ratenbegrenzung

Ab Version 3.4.0 steht Sampling mit Ratenbegrenzung zur Verfügung und ist jetzt Standard.

Wenn kein Sampling konfiguriert wird, ist die Standardeinstellung jetzt ein ratenbegrenztes Sampling, das so konfiguriert ist, dass höchstens (ungefähr) fünf Anforderungen pro Sekunde erfasst werden, zusammen mit allen Abhängigkeiten und Protokollen zu diesen Anforderungen.

Durch diese Konfiguration wird die vorherige Standardeinstellung ersetzt, bei der alle Anforderungen erfasst wurden. Wenn Sie weiterhin alle Anforderungen erfassen möchten, verwenden Sie das Sampling mit festem Prozentsatz, und legen Sie den Samplingprozentsatz auf 100 fest.

Hinweis

Das Sampling mit Ratenbegrenzung ist eine ungefähre Einstellung, da intern ein „fester“ Samplingprozentsatz im Zeitverlauf angepasst werden muss, damit genaue Elementzahlen für jeden Telemetriedatensatz ausgegeben werden. Intern wird das Sampling mit Ratenbegrenzung so angepasst, dass schnell (0,1 Sekunden) auf neue Anwendungslasten reagiert werden kann. Aus diesem Grund sollte die konfigurierte Rate nicht wesentlich oder für längere Zeit überschritten werden.

Dieses Beispiel zeigt, wie Sie das Sampling so einstellen, dass höchstens (ungefähr) eine Anforderung pro Sekunde erfasst wird:

{
  "sampling": {
    "requestsPerSecond": 1.0
  }
}

requestsPerSecond kann eine Dezimalzahl sein, sodass Sie den Wert so konfigurieren können, dass bei Bedarf weniger als eine Anforderung pro Sekunde erfasst wird. Beispiel: Der Wert 0.5 bedeutet eine Erfassung von höchstens einer Anforderung alle zwei Sekunden.

Sie können den Samplingprozentsatz auch mithilfe der Umgebungsvariable APPLICATIONINSIGHTS_SAMPLING_REQUESTS_PER_SECOND festlegen. Dieser hat dann Vorrang vor dem in der JSON-Konfiguration angegebenen Ratenlimit.

Sampling mit festen Prozentsatz

Das folgende Beispiel veranschaulicht das Festlegen des Samplings, damit ungefähr ein Drittel aller Anforderungen erfasst werden:

{
  "sampling": {
    "percentage": 33.333
  }
}

Sie können den Samplingprozentsatz auch mithilfe der Umgebungsvariable APPLICATIONINSIGHTS_SAMPLING_PERCENTAGE festlegen. Dieser hat dann Vorrang vor dem in der JSON-Konfiguration angegebenen Samplingprozentsatz.

Hinweis

Für den Stichprobenprozentsatz wählen Sie einen Wert aus, der nah bei 100/N liegt, wobei N eine ganze Zahl ist. Derzeit werden keine anderen Werte für die Stichprobenerstellung unterstützt.

Stichprobenüberschreibungen

Mithilfe von Stichprobenüberschreibungen können Sie den Standardprozentsatz für die Stichprobe überschreiben. Beispielsweise können Sie folgende Aktionen ausführen:

• Setzen Sie den Samplingprozentsatz für störanfällige Gesundheitsprüfungen auf 0 (oder einen kleinen Wert).
• Legen Sie den Samplingprozentsatz für überflüssige Abhängigkeitsaufrufe auf 0 (oder einen kleinen Wert) fest.
• Festlegen des Samplingprozentsatzes auf 100 für einen wichtigen Anforderungstyp. Sie können /login z. B. auch dann verwenden, wenn der Standardwert für das Sampling niedriger konfiguriert ist.

Weitere Informationen finden Sie in der Dokumentation zu Stichprobenüberschreibungen.

Java Management Extensions-Metriken

Wenn Sie einige weitere JMX-Metriken (Java Management Extensions) sammeln möchten:

{
  "jmxMetrics": [
    {
      "name": "JVM uptime (millis)",
      "objectName": "java.lang:type=Runtime",
      "attribute": "Uptime"
    },
    {
      "name": "MetaSpace Used",
      "objectName": "java.lang:type=MemoryPool,name=Metaspace",
      "attribute": "Usage.used"
    }
  ]
}

Im vorherigen Konfigurationsbeispiel gilt Folgendes:

• name entspricht dem Metriknamen, der dieser JMX-Metrik zugewiesen ist (ein beliebiger Name kann verwendet werden).
• objectName ist der Objektname des JMX MBean, das Sie erfassen möchten. Das Sternchen-Platzhalterzeichen (*) wird unterstützt.
• attribute entspricht dem Attributnamen innerhalb des JMX MBean, das Sie erfassen möchten.

Numerische und boolesche JMX-Metrikwerte werden unterstützt. Boolesche JMX-Metriken werden 0 für FALSE und 1 für TRUE zugeordnet.

Weitere Informationen finden Sie in der Dokumentation zu JMX-Metriken.

Benutzerdefinierte Dimensionen

Wenn Sie allen Ihren Telemetriedaten benutzerdefinierte Dimensionen hinzufügen möchten:

{
  "customDimensions": {
    "mytag": "my value",
    "anothertag": "${ANOTHER_VALUE}"
  }
}

${...} kann zum Lesen des Werts aus der angegebenen Umgebungsvariable beim Start verwendet werden.

Hinweis

Wenn Sie ab Version 3.0.2 eine benutzerdefinierte Dimension mit dem Namen service.version hinzufügen, wird der Wert in der Spalte application_Version in der Tabelle „Application Insights-Protokolle“ und nicht als benutzerdefinierte Dimension gespeichert.

Vererbtes Attribut (Vorschau)

Ab Version 3.2.0 können Sie eine benutzerdefinierte Dimension programmgesteuert für Ihre Anforderungstelemetrie festlegen. Sie stellt die Vererbung durch Abhängigkeits- und Protokolltelemetrie sicher. Alle werden im Kontext dieser Anforderung erfasst.

{
  "preview": {
    "inheritedAttributes": [
      {
        "key": "mycustomer",
        "type": "string"
      }
    ]
  }
}

Rufen Sie dann am Anfang jeder Anforderung Folgendes auf:

Span.current().setAttribute("mycustomer", "xyz");

Weitere Informationen finden Sie auch unter: Hinzufügen einer benutzerdefinierten Eigenschaft zu einer Spanne.

Überschreiben der Verbindungszeichenfolgen (Vorschau)

Dieses Feature befindet sich ab 3.4.0 in der Vorschauphase.

Durch die Überschreibung der Verbindungszeichenfolgen können Sie die Standardverbindungszeichenfolge außer Kraft setzen. Beispielsweise können Sie folgende Aktionen ausführen:

• Legen Sie eine Verbindungszeichenfolge für ein HTTP-Pfadpräfix /myapp1 fest.
• Legen Sie eine andere Verbindungszeichenfolge für ein weiteres HTTP-Pfadpräfix /myapp2/ fest.

{
  "preview": {
    "connectionStringOverrides": [
      {
        "httpPathPrefix": "/myapp1",
        "connectionString": "..."
      },
      {
        "httpPathPrefix": "/myapp2",
        "connectionString": "..."
      }
    ]
  }
}

Überschreiben des Cloud-Rollennamens (Vorschau)

Dieses Feature befindet sich ab 3.3.0 in der Vorschauphase.

Durch die Außerkraftsetzung des Cloudrollennamens können Sie den Standardnamen der Cloudrolle überschreiben. Beispielsweise können Sie folgende Aktionen ausführen:

• Legen Sie einen Cloud-Rollennamen für ein HTTP-Pfadpräfix /myapp1 fest.
• Legen Sie einen weiteren Cloudrollennamen für ein anderes HTTP-Pfadpräfix /myapp2/ fest.

{
  "preview": {
    "roleNameOverrides": [
      {
        "httpPathPrefix": "/myapp1",
        "roleName": "Role A"
      },
      {
        "httpPathPrefix": "/myapp2",
        "roleName": "Role B"
      }
    ]
  }
}

Zur Laufzeit konfigurierte Verbindungszeichenfolge

Wenn es möglich sein muss, die Verbindungszeichenfolge zur Laufzeit zu konfigurieren, fügen Sie ab Version 3.4.8 die folgende Eigenschaft zu Ihrer JSON-Konfiguration hinzu:

{
  "connectionStringConfiguredAtRuntime": true
}

Fügen Sie applicationinsights-core zu Ihrer Anwendung hinzu:

<dependency>
  <groupId>com.microsoft.azure</groupId>
  <artifactId>applicationinsights-core</artifactId>
  <version>3.7.1</version>
</dependency>

Verwenden Sie die statische Methode configure(String) in der Klasse com.microsoft.applicationinsights.connectionstring.ConnectionString.

Hinweis

Alle Telemetriedaten, die vor dem Konfigurieren der Verbindungszeichenfolge erfasst werden, werden gelöscht, daher empfiehlt es sich, sie so früh wie möglich beim Start der Anwendung zu konfigurieren.

Automatische Sammlung von InProc-Abhängigkeiten (Vorschau)

Wenn Sie ab Version 3.2.0 InProc-Controllerabhängigkeiten erfassen möchten, verwenden Sie die folgende Konfiguration:

{
  "preview": {
    "captureControllerSpans": true
  }
}

Browser-SDK-Ladeprogramm (Vorschau)

Dieses Feature fügt das Browser-SDK-Ladeprogramm automatisch in die HTML-Seiten Ihrer Anwendung ein, einschließlich der Konfiguration der entsprechenden Verbindungszeichenfolge.

Wenn Ihre Java-Anwendung beispielsweise eine Antwort wie diese zurückgibt:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Title</title>
  </head>
  <body>
  </body>
</html>

Sie ändert sich automatisch so, dass folgendes zurückgegeben wird:

<!DOCTYPE html>
<html lang="en">
  <head>
    <script type="text/javascript">
    !function(v,y,T){var S=v.location,k="script"
    <!-- Removed for brevity -->
    connectionString: "YOUR_CONNECTION_STRING"
    <!-- Removed for brevity --> }});
    </script>
    <title>Title</title>
  </head>
  <body>
  </body>
</html>

Das Skript soll Kunden helfen, die Webbenutzerdaten nachzuverfolgen, und sendet die sammelnden serverseitigen Telemetriedaten zurück an das Azure-Portal der Benutzer. Details finden Sie unter ApplicationInsights-JS.

Wenn Sie dieses Feature aktivieren möchten, fügen Sie die folgende Konfigurationsoption hinzu:

{
  "preview": {
    "browserSdkLoader": {
      "enabled": true
    }
  }
}

Telemetrieprozessoren (Vorschauversion)

Sie können Telemetrieprozessoren verwenden, um Regeln zu konfigurieren, die auf Anforderungs-, Abhängigkeits- und Überwachungstelemetrie angewendet werden. Beispielsweise können Sie folgende Aktionen ausführen:

• Maskieren vertraulicher Daten
• Bedingtes Hinzufügen benutzerdefinierter Dimensionen
• Aktualisieren des Namens des span-Elements, das zum Aggregieren ähnlicher Telemetriedaten im Azure-Portal verwendet wird
• Verwerfen bestimmter span-Attribute zur Senkung von Erfassungskosten

Weitere Informationen finden Sie in der Dokumentation zu Telemetrieprozessoren.

Hinweis

Wenn Sie bestimmte (ganze) Span-Elemente zur Senkung von Erfassungskosten verwerfen möchten, lesen Sie unter Stichprobenüberschreibungen nach.

Benutzerdefinierte Instrumentierung (Vorschau)

Ab Version 3.3.1 können Sie Spannen für eine Methode in Ihrer Anwendung erfassen.

{
  "preview": {
    "customInstrumentation": [
      {
        "className": "my.package.MyClass",
        "methodName": "myMethod"
      }
    ]
  }
}

Lokales Deaktivieren der Erfassungs-Stichprobenerstellung (Vorschau)

Wenn der effektive Stichprobenanteil im Java-Agenten standardmäßig 100 % beträgt und der Erfassungs-Stichprobenanteil für Ihre Application Insights-Ressource konfiguriert wurde, dann wird der Erfassungs-Stichprobenanteil angewendet.

Beachten Sie, dass dieses Verhalten sowohl für die Stichprobenentnahme mit festem Prozentsatz von 100 % als auch die Stichprobenentnahme mit Ratenbegrenzung gilt, wenn die Anforderungsrate nicht die Ratenbegrenzung überschreitet (effektive Erfassung von 100 % während des kontinuierlich gleitenden Zeitfensters).

Ab Version 3.5.3 können Sie dieses Verhalten deaktivieren (und in diesen Fällen auch dann 100 % der Telemetriedaten beibehalten, wenn die Erfassungs-Stichprobenerstellung für Ihre Application Insights-Ressource konfiguriert wurde):

{
  "preview": {
    "sampling": {
      "ingestionSamplingEnabled": false
    }
  }
}

Automatisch gesammelte Protokollierung

Log4j, Logback, JBoss Logging und java.util.logging sind automatisch instrumentiert. Die über diese Protokollierungsframeworks durchgeführte Protokollierung wird automatisch erfasst.

Die Protokollierung wird nur erfasst, wenn Folgendes gilt:

• Erfüllt die konfigurierte Stufe für das Protokollierungsframework.
• Sie erfüllt auch die konfigurierte Ebene für Application Insights.

Wenn Ihr Protokollierungsframework beispielsweise für die Protokollierung von WARN aus dem Paket com.example (und ansonsten wie oben beschrieben) konfiguriert ist und Application Insights für die Erfassung von INFO (und ansonsten wie beschrieben) konfiguriert ist, erfasst Application Insights nur WARN (und Schwerwiegenderes) aus dem Paket com.example.

Die für Application Insights konfigurierte Standardebene ist INFO. Wenn Sie diesen Wert ändern möchten, ist das folgendermaßen möglich:

{
  "instrumentation": {
    "logging": {
      "level": "WARN"
    }
  }
}

Sie können den Schwellenwert auch mithilfe der Umgebungsvariable APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL festlegen. Dieser hat dann Vorrang vor dem in der JSON-Konfiguration angegebenen Wert.

Sie können diese gültigen level-Werte verwenden, um sie in der Datei applicationinsights.json anzugeben. In der Tabelle wird gezeigt, wie sie den Protokollierungsebenen in verschiedenen Protokollierungsframeworks entsprechen.

Ebene	Log4j	Logback	JBoss	JULI
OFF	OFF	OFF	OFF	OFF
TÖDLICH	TÖDLICH	FEHLER	TÖDLICH	Schwerwiegend
ERROR (oder SEVERE)	FEHLER	FEHLER	FEHLER	Schwerwiegend
WARN (oder WARNING)	WARNUNG	WARNUNG	WARNUNG	WARNUNG
INFO	INFO	INFO	INFO	INFO
CONFIG	DEBUG	DEBUG	DEBUG	CONFIG
DEBUG (oder FINE)	DEBUG	DEBUG	DEBUG	In Ordnung
FINER	DEBUG	DEBUG	DEBUG	FINER
TRACE (oder FINEST)	TRACE	TRACE	TRACE	FINEST
ALL	ALL	ALL	ALL	ALL

Hinweis

Wenn ein Ausnahmeobjekt an die Protokollierung übergeben wird, wird die Protokollmeldung (zusammen mit Details zum Ausnahmeobjekt) im Azure-Portal in der Tabelle exceptions und nicht in der Tabelle traces angezeigt. Wenn Sie die Protokollnachrichten sowohl für die Tabelle traces als auch für die Tabelle exceptions anzeigen möchten, können Sie eine beide vereinigende Protokollabfrage (Kusto) schreiben. Beispiel:

union traces, (exceptions | extend message = outerMessage)
| project timestamp, message, itemType

Protokollmarker (Vorschau)

Ab Version 3.4.2 können Sie die Protokollmarker für Logback und Log4j 2 erfassen:

{
  "preview": {
    "captureLogbackMarker":  true,
    "captureLog4jMarker":  true
  }
}

Zusätzliche Protokollattribute für Logback (Vorschau)

Ab Version 3.4.3 können Sie FileName, ClassName, MethodName und LineNumber für Logback erfassen:

{
  "preview": {
    "captureLogbackCodeAttributes": true
  }
}

Warnung

Das Erfassen von Codeattributen kann einen zusätzlichen Leistungsaufwand bedeuten.

Protokolliergrad als benutzerdefinierte Dimension

Ab Version 3.3.0 wird LoggingLevel nicht standardmäßig als Teil der benutzerdefinierten Dimension für Traces erfasst, da diese Daten bereits im Feld SeverityLevel aufgezeichnet werden.

Bei Bedarf können Sie das vorherige Verhalten temporär wieder aktivieren:

{
  "preview": {
    "captureLoggingLevelAsCustomDimension": true
  }
}

Automatisch erfasste Micrometer-Metriken (einschließlich Spring Boot Actuator-Metriken)

Wenn Ihre Anwendung Micrometer verwendet, werden Metriken, die an die globale Micrometer-Registrierung gesendet werden, automatisch erfasst.

Wenn Ihre Anwendung auch Spring Boot Actuator verwendet, werden mit Spring Boot Actuator konfigurierte Metriken ebenfalls automatisch erfasst.

So senden Sie benutzerdefinierte Metriken mithilfe von Micrometer

1. Fügen Sie Ihrer Webanwendung Micrometer hinzu. Dies ist im folgenden Beispiel dargestellt:

   <dependency>
     <groupId>io.micrometer</groupId>
     <artifactId>micrometer-core</artifactId>
     <version>1.6.1</version>
   </dependency>
   

2. Verwenden Sie die globale Registry von Micrometer, um ein Meter zu erstellen, wie im folgenden Beispiel gezeigt.

   static final Counter counter = Metrics.counter("test.counter");
   

3. Verwenden Sie den Zähler, um mithilfe des folgenden Befehls Metriken zu erfassen:

   counter.increment();
   

4. Die Metriken werden in der Tabelle customMetrics erfasst und Tags werden in der Spalte customDimensions erfasst. Sie können die Metriken auch im Metrik-Explorer im Metriknamespace Log-based metrics anzeigen.

   Hinweis

   Application Insights Java ersetzt alle nichtalphanumerischen Zeichen (mit Ausnahme von Strichen) im Mikrometer-Metriknamen durch Unterstriche. Daher wird die obige test.counter-Metrik als test_counter angezeigt.

So deaktivieren Sie die automatische Erfassung von Micrometer-Metriken und Spring Boot Actuator-Metriken:

Hinweis

Benutzerdefinierte Metriken werden separat in Rechnung gestellt und können Zusatzkosten verursachen. Es wird dringend empfohlen, die Preisinformationen zu überprüfen. Fügen Sie die folgende Konfiguration in Ihrer Konfigurationsdatei hinzu, um die Micrometer- und Spring Boot Actuator-Metriken zu deaktivieren.

{
  "instrumentation": {
    "micrometer": {
      "enabled": false
    }
  }
}

JDBC-Abfragemaskierung (Java Database Connectivity)

Literalwerte in JDBC-Abfragen (Java Database Connectivity) werden standardmäßig maskiert, um zu vermeiden, dass versehentlich vertrauliche Daten erfasst werden.

Ab Version 3.4.0 kann dieses Verhalten deaktiviert werden. Beispiel:

{
  "instrumentation": {
    "jdbc": {
      "masking": {
        "enabled": false
      }
    }
  }
}

Maskieren der Mongo-Abfrage

Literalwerte in Mongo-Abfragen werden standardmäßig maskiert, um zu vermeiden, dass versehentlich vertrauliche Daten erfasst werden.

Ab Version 3.4.0 kann dieses Verhalten deaktiviert werden. Beispiel:

{
  "instrumentation": {
    "mongo": {
      "masking": {
        "enabled": false
      }
    }
  }
}

HTTP-Header

Ab Version 3.3.0 können Sie Anforderungs- und Antwort-Header in Servertelemetriedaten (Anforderung) erfassen:

{
  "preview": {
    "captureHttpServerHeaders": {
      "requestHeaders": [
        "My-Header-A"
      ],
      "responseHeaders": [
        "My-Header-B"
      ]
    }
  }
}

Die Groß-/Kleinschreibung wird bei Headernamen nicht beachtet.

Die obigen Beispiele werden unter den Eigenschaftennamen http.request.header.my_header_a und http.response.header.my_header_b erfasst.

Auf ähnliche Weise können Sie Anforderungs- und Antwortheader in Ihren Client(Abhängigkeits-)telemetriedaten erfassen:

{
  "preview": {
    "captureHttpClientHeaders": {
      "requestHeaders": [
        "My-Header-C"
      ],
      "responseHeaders": [
        "My-Header-D"
      ]
    }
  }
}

Auch hier wird die Groß-/Kleinschreibung bei Headernamen nicht beachtet. Die obigen Beispiele werden unter den Eigenschaftennamen http.request.header.my_header_c und http.response.header.my_header_d erfasst.

4xx-Antwortcodes von HTTP-Servern

Standardmäßig werden HTTP-Serveranforderungen, die 4xx-Antwortcodes zurückgeben, als Fehler erfasst.

Ab Version 3.3.0 können Sie dieses Verhalten ändern, um sie als erfolgreich zu erfassen:

{
  "preview": {
    "captureHttpServer4xxAsError": false
  }
}

Unterdrücken bestimmter automatisch erfasster Telemetriedaten

Ab Version 3.0.3 können bestimmte automatisch erfasste Telemetriedaten mithilfe der folgenden Konfigurationsoptionen unterdrückt werden:

{
  "instrumentation": {
    "azureSdk": {
      "enabled": false
    },
    "cassandra": {
      "enabled": false
    },
    "jdbc": {
      "enabled": false
    },
    "jms": {
      "enabled": false
    },
    "kafka": {
      "enabled": false
    },
    "logging": {
      "enabled": false
    },
    "micrometer": {
      "enabled": false
    },
    "mongo": {
      "enabled": false
    },
    "quartz": {
      "enabled": false
    },
    "rabbitmq": {
      "enabled": false
    },
    "redis": {
      "enabled": false
    },
    "springScheduling": {
      "enabled": false
    }
  }
}

Sie können diese Instrumentierungen auch unterdrücken, indem Sie folgende Umgebungsvariablen auf false festlegen:

• APPLICATIONINSIGHTS_INSTRUMENTATION_AZURE_SDK_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_CASSANDRA_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_JDBC_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_JMS_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_KAFKA_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_MICROMETER_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_MONGO_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_RABBITMQ_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_REDIS_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_SPRING_SCHEDULING_ENABLED

Diese Variablen haben dann Vorrang vor den aktivierten Variablen, die in der JSON-Konfiguration angegeben sind.

Hinweis

Wenn Sie eine präzisere Steuerung benötigen, z. B. um einige, aber nicht alle Redis-Aufrufe zu unterdrücken, lesen Sie unter Stichprobenüberschreibungen nach.

Instrumentenvorschau

Ab Version 3.2.0 können Sie die folgenden Vorschauinstrumente aktivieren:

{
  "preview": {
    "instrumentation": {
      "akka": {
        "enabled": true
      },
      "apacheCamel": {
        "enabled": true
      },
      "grizzly": {
        "enabled": true
      },
      "ktor": {
        "enabled": true
      },
      "play": {
        "enabled": true
      },
      "r2dbc": {
        "enabled": true
      },
      "springIntegration": {
        "enabled": true
      },
      "vertx": {
        "enabled": true
      }
    }
  }
}

Hinweis

Die Akka-Instrumentierung ist ab Version 3.2.2 verfügbar. Die Vertx HTTP Library-Instrumentierung ist ab Version 3.3.0 verfügbar.

Metrikintervall

Standardmäßig werden Metriken alle 60 Sekunden aufgezeichnet.

Ab Version 3.0.3 können Sie dieses Intervall ändern:

{
  "metricIntervalSeconds": 300
}

Ab 3.4.9 GA können Sie metricIntervalSeconds auch mithilfe der Umgebungsvariablen APPLICATIONINSIGHTS_METRIC_INTERVAL_SECONDS festlegen. Dieser hat dann Vorrang vor dem in der JSON-Konfiguration angegebenen metricIntervalSeconds.

Die Einstellung gilt für die folgenden Metriken:

• Standardleistungsindikatoren: z. B. CPU und Arbeitsspeicher
• Standardmäßige benutzerdefinierte Metriken: z. B. die zeitliche Steuerung der Garbage Collection
• Konfigurierte JMX-Metriken:siehe Abschnitt zu JMX-Metriken
• Micrometer-Metriken:siehe Abschnitt zu automatisch erfassten Micrometer-Metriken

Herzschlag

Application Insights Java 3.x sendet standardmäßig alle 15 Minuten eine Heartbeatmetrik. Wenn Sie die Heartbeat-Metrik zum Auslösen von Warnungen verwenden, können Sie die Frequenz dieses Heartbeats erhöhen.

{
  "heartbeat": {
    "intervalSeconds": 60
  }
}

Hinweis

Sie können das Intervall nicht auf mehr als 15 Minuten erhöhen, da die Taktdaten auch zur Nachverfolgung der Application Insights-Nutzung verwendet werden.

Authentifizierung

Hinweis

Die Authentifizierungsfunktion ist seit Version 3.4.17 GA.

Mit der Authentifizierung können Sie den Agent so konfigurieren, dass Tokenanmeldeinformationen generiert werden, die für die Microsoft Entra-Authentifizierung erforderlich sind. Weitere Informationen finden Sie in der Dokumentation zur Authentifizierung.

HTTP-Proxy

Wenn Sich Ihre Anwendung hinter einer Firewall befindet und keine direkte Verbindung mit Application Insights herstellen kann, lesen Sie die Azure Monitor-Endpunktzugriffs- und Firewallkonfiguration.

Um dieses Problem zu umgehen, können Sie Application Insights Java 3.x für die Verwendung eines HTTP-Proxys konfigurieren.

{
  "proxy": {
    "host": "myproxy",
    "port": 8080
  }
}

Ferner können Sie den HTTP-Proxy mithilfe der Umgebungsvariable APPLICATIONINSIGHTS_PROXY festlegen, die das Format https://<host>:<port> annimmt. Dieser hat dann Vorrang vor dem in der JSON-Konfiguration angegebenen Proxy.

Sie können mit der Umgebungsvariable APPLICATIONINSIGHTS_PROXY einen Benutzer und ein Kennwort für Ihren Proxy bereitstellen: https://<user>:<password>@<host>:<port>.

Application Insights Java 3.x respektiert auch die globalen Systemeigenschaften https.proxyHost und https.proxyPort, wenn diese festgelegt sind (sowie http.nonProxyHosts, falls erforderlich).

Wiederherstellung nach Erfassungsfehlern

Wenn das Senden von Telemetriedaten an den Application Insights-Dienst zu Fehlern führt, speichert Application Insights Java 3.x die Telemetriedaten auf dem Datenträger und unternimmt weitere Versuche vom Datenträger.

Der Standardgrenzwert für die Datenträgerpersistenz beträgt 50 MB. Wenn Sie über ein hohes Telemetriedatenvolumen verfügen oder in der Lage sein müssen, nach längeren Netzwerk- oder Erfassungsdienstausfällen wiederherzustellen, können Sie diesen Grenzwert ab Version 3.3.0 erhöhen:

{
  "preview": {
    "diskPersistenceMaxSizeMb": 50
  }
}

Selbstdiagnose

„Selbstdiagnose“ bezeichnet die interne Protokollierung von Application Insights Java 3.x. Diese Funktionalität kann hilfreich sein, um Probleme mit Application Insights selbst zu identifizieren und zu diagnostizieren.

Application Insights Java 3.x protokolliert standardmäßig auf Ebene INFO sowohl in der Datei applicationinsights.log als auch auf der Konsole gemäß dieser Konfiguration:

{
  "selfDiagnostics": {
    "destination": "file+console",
    "level": "INFO",
    "file": {
      "path": "applicationinsights.log",
      "maxSizeMb": 5,
      "maxHistory": 1
    }
  }
}

Im vorherigen Konfigurationsbeispiel gilt Folgendes:

• level kann OFF, ERROR, WARN, INFO, DEBUG oder TRACE sein.
• path kann ein absoluter oder ein relativer Pfad sein. Relative Pfade werden anhand des Verzeichnisses aufgelöst, in dem sich applicationinsights-agent-3.7.1.jar befindet.

Ab Version 3.0.2 können Sie auch die Selbstdiagnose level mithilfe der Umgebungsvariable APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_LEVEL festlegen. Diese hat dann Vorrang vor der in der JSON-Konfiguration angegebenen Selbstdiagnoseebene.

Ab Version 3.0.3 können Sie auch den Speicherort der Selbstdiagnosedatei über die Umgebungsvariable APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_FILE_PATH festlegen. Dieser hat dann Vorrang vor dem in der JSON-Konfiguration angegebenen Dateipfad für die Selbstdiagnose.

Telemetriekorrelation

Die Telemetriekorrelation ist standardmäßig aktiviert, sie kann jedoch in der Konfiguration deaktiviert werden.

{
  "preview": {
    "disablePropagation": true
  }
}

Beispiel

Dieses Beispiel veranschaulicht eine Konfigurationsdatei mit mehreren Komponenten. Konfigurieren Sie spezifische Optionen basierend auf Ihren Anforderungen.

{
  "connectionString": "...",
  "role": {
    "name": "my cloud role name"
  },
  "sampling": {
    "percentage": 100
  },
  "jmxMetrics": [
  ],
  "customDimensions": {
  },
  "instrumentation": {
    "logging": {
      "level": "INFO"
    },
    "micrometer": {
      "enabled": true
    }
  },
  "proxy": {
  },
  "preview": {
    "processors": [
    ]
  },
  "selfDiagnostics": {
    "destination": "file+console",
    "level": "INFO",
    "file": {
      "path": "applicationinsights.log",
      "maxSizeMb": 5,
      "maxHistory": 1
    }
  }
}