Konfigurationsoptionen: Azure Monitor Application Insights für Java

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

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.

Pfad der Konfigurationsdatei

Standardmäßig erwartet Application Insights Java 3.x eine Konfigurationsdatei mit dem Namen applicationinsights.json, die sich im gleichen Verzeichnis wie applicationinsights-agent-3.5.2.jar befindet.

Sie können einen eigenen Konfigurationsdateipfad angeben, indem Sie eine der folgenden beiden Optionen verwenden:

• Umgebungsvariable APPLICATIONINSIGHTS_CONFIGURATION_FILE
• Java-Systemeigenschaft applicationinsights.configuration.file

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

Alternativ können Sie anstelle einer Konfigurationsdatei den gesamten Inhalt der JSON-Konfiguration über die Umgebungsvariable APPLICATIONINSIGHTS_CONFIGURATION_CONTENT angeben.

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.5.2.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 dann Vorrang vor dem in der JSON-Konfiguration angegebenen Cloudrollennamen.

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

Cloudrolleninstanz

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

Wenn Sie für die Cloudrolleninstanz einen anderen Namen festlegen möchten:

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

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

Sie können den die Cloudrolleninstanz auch mithilfe der Java-Systemeigenschaft applicationinsights.role.instance festlegen. Dieser hat dann ebenfalls Vorrang vor der in der JSON-Konfiguration angegebenen Cloudrolleninstanz.

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.

Darüber hinaus basiert das Sampling auf einer Überwachungs-ID, um für konsistente Samplingentscheidungen über verschiedene Dienste hinweg zu sorgen.

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 sollten Sie die konfigurierte Rate nicht sehr stark oder sehr lange ü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 Samplingprozentsatz wählen Sie einen Wert aus, der sich als Bruch darstellen lässt (100/N, wobei N eine ganze Zahl ist). Andere Werte werden für die Stichprobenerstellung derzeit nicht unterstützt.

Stichprobenüberschreibungen

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

• Legen Sie den Samplingprozentsatz für überflüssige Integritätsprüfungen auf 0 (oder einen kleinen Wert) fest.
• 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 entspricht dem Objektnamen des verwalteten 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

Verwenden Sie den folgenden JSON-Code, wenn Sie Ihren gesamten 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 Cloudrollennamen 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.5.2</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 ist es am besten, sie so früh wie möglich beim Start Ihrer 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"
      }
    ]
  }
}

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:

• Sie erfüllt die konfigurierte Ebene 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	JUL
OFF	OFF	OFF	OFF	OFF
FATAL	FATAL	ERROR	FATAL	SEVERE
ERROR (oder SEVERE)	ERROR	ERROR	ERROR	SEVERE
WARN (oder WARNING)	WARN	WARN	WARN	WARNING
INFO	INFO	INFO	INFO	INFO
CONFIG	DEBUG	DEBUG	DEBUG	CONFIG
DEBUG (oder FINE)	DEBUG	DEBUG	DEBUG	FINE
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 Ablaufverfolgungen erfasst, da diese Daten bereits im Feld SeverityLevel erfasst 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 Registrierung von Micrometer, um wie folgt eine Verbrauchseinheit zu erstellen:

   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 nicht alphanumerischen Zeichen (mit Ausnahme von Bindestrichen) im Micrometer-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
    },
    "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_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.

Vorschau-Instrumentierungen

Ab Version 3.2.0 können die folgenden Vorschauminstrumentierungen aktiviert werden:

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

Heartbeat

Application Insights Java 3.x sendet standardmäßig alle 15 Minuten eine Heartbeatmetrik. Wenn Sie die Taktmetrik (Heartbeat) zum Auslösen von Warnungen verwenden, können Sie die Frequenz für den Takt 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 allgemein verfügbar.

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 zu Application Insights herstellen kann, sehen Sie sich die von Application Insights verwendeten IP-Adressen an.

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.

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 in der Datei applicationinsights.log und der Konsole entsprechend der folgenden 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.5.2.jar befindet.

Ab Version 3.0.2 können Sie auch das level der Selbstdiagnose 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.

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