Konfigurieren der Protokollierung im Azure SDK für Java

Dieser Artikel bietet eine Übersicht, wie Sie die Protokollierung in Anwendungen aktivieren, die das Azure SDK für Java verwenden. Die Azure-Clientbibliotheken für Java besitzen zwei Protokollierungsoptionen:

  • Ein integriertes Protokollierungsframework für temporäres Debuggen.
  • Unterstützung für die Protokollierung mithilfe der SLF4J-Schnittstelle.

Wir empfehlen, dass Sie SLF4J verwenden, da es im Java-Ökosystem gut etabliert und solide dokumentiert ist. Weitere Informationen finden Sie im SLF4J-Benutzerhandbuch.

Dieser Artikel verlinkt mit anderen Artikeln, die viele der beliebten Java-Protokollierungsframeworks abdecken. Diese anderen Artikel stellen Konfigurationsbeispiele bereit und beschreiben, wie die Azure-Clientbibliotheken die Protokollierungsframeworks verwenden können.

Je nachdem, welche Protokollierungskonfiguration Sie verwenden, ist dieselbe Protokollausgabe in beiden Fällen verfügbar, da die gesamte Protokollierungsausgabe in den Azure-Clientbibliotheken für Java durch eine azure-core ClientLogger-Abstraktion weitergeleitet wird.

Im weiteren Verlauf dieses Artikels wird die Konfiguration aller verfügbaren Protokollierungsoptionen ausführlich erläutert.

Standardprotokollierung (für temporäres Debuggen)

Wie bereits erwähnt, verwenden alle Azure-Clientbibliotheken SLF4J für die Protokollierung, aber es gibt eine als Fallback in die Azure-Clientbibliotheken für Java integrierte Standardprotokollierung. Diese Standardprotokollierung wird für Fälle bereitgestellt, in denen eine Anwendung bereitgestellt wurde und die Protokollierung erforderlich ist, es aber nicht möglich ist, die Anwendung mit einer enthaltenen SLF4J-Protokollierung erneut bereitzustellen. Zum Aktivieren dieser Protokollierung müssen Sie sich zunächst sicher sein, dass keine SLF4J-Protokollierung vorhanden ist (da diese sonst Vorrang hat), und dann die Umgebungsvariable AZURE_LOG_LEVEL festlegen. Die folgende Tabelle enthält die zulässigen Werte für diese Umgebungsvariable:

Protokollebene Zulässige Werte für Umgebungsvariablen
VERBOSE "verbose", "debug"
INFORMATION "info", "information", "informational"
WARNING "warn", "warning"
ERROR "err", "error"

Nachdem die Umgebungsvariable festgelegt wurde, starten Sie die Anwendung neu, damit die Umgebungsvariable wirksam wird. Diese Protokollierung protokolliert in die Konsole und bietet nicht die erweiterten Anpassungsfunktionen einer SLF4J-Implementierung, z. B. Rollover und Protokollierung in eine Datei. Um die Protokollierung wieder zu deaktivieren, entfernen Sie einfach die Umgebungsvariable, und starten Sie die Anwendung neu.

SLF4J-Protokollierung

Standardmäßig sollten Sie die Protokollierung mithilfe eines SLF4J-unterstützten Protokollierungsframeworks konfigurieren. Schließen Sie zunächst eine relevante SLF4J-Protokollierungsimplementierung als Abhängigkeit von Ihrem Projekt ein. Weitere Informationen finden Sie unter Deklarieren von Projektabhängigkeiten für die Protokollierung im SLF4J-Benutzerhandbuch. Konfigurieren Sie als Nächstes Ihren Logger so, dass sie in Ihrer Umgebung wie das Festlegen von Protokollebenen, das Konfigurieren der Klassen und nicht protokollieren und so weiter funktionieren. Einige Beispiele werden über die folgenden Links bereitgestellt, doch weitere Informationen finden Sie in der Dokumentation zu Ihrem ausgewählten Protokollierungsframework.

Protokollformat

Protokollierungsframeworks unterstützen benutzerdefinierte Protokollnachrichtenformatierung und Layouts. Es wird empfohlen, mindestens folgende Felder zu einschließen, um die Problembehandlung von Azure-Clientbibliotheken zu ermöglichen:

  • Datum und Uhrzeit mit Millisekundengenauigkeit
  • Protokollschwere
  • Loggername
  • Threadname
  • `Message`

Beispiele finden Sie in der Dokumentation für das von Ihnen verwendete Protokollierungsframework.

Strukturierte Protokollierung

Zusätzlich zur Protokollierung der zuvor erwähnten allgemeinen Eigenschaften können Azure-Clientbibliotheken Protokollnachrichten mit zusätzlichem Kontext bei Bedarf kommentieren. Beispielsweise werden JSON-formatierte Protokolle angezeigt, die az.sdk.message mit Kontext als andere Stammeigenschaften geschrieben wurden, wie im folgenden Beispiel gezeigt:

16:58:51.038 INFO  c.a.c.c.i.C.getManifestProperties - {"az.sdk.message":"HTTP request","method":"GET","url":"<>","tryCount":"1","contentLength":0}
16:58:51.141 INFO  c.a.c.c.i.C.getManifestProperties - {"az.sdk.message":"HTTP response","contentLength":"558","statusCode":200,"url":"<>","durationMs":102}

Wenn Sie Protokolle an Azure Monitor senden, können Sie die Kusto-Abfragesprache verwenden, um sie zu analysieren. Die folgende Abfrage bietet ein Beispiel:

traces 
| where message startswith "{\"az.sdk.message"
| project timestamp, logger=customDimensions["LoggerName"], level=customDimensions["LoggingLevel"], thread=customDimensions["ThreadName"], azSdkContext=parse_json(message)
| evaluate bag_unpack(azSdkContext)

Hinweis

Azure-Clientbibliotheksprotokolle sind für das Ad-hoc-Debuggen vorgesehen. Es wird nicht empfohlen, auf das Protokollformat zu verlassen, um Ihre Anwendung zu benachrichtigen oder zu überwachen. Azure-Clientbibliotheken garantieren nicht die Stabilität von Protokollnachrichten oder Kontextschlüsseln. Für solche Zwecke empfehlen wir die Verwendung der verteilten Ablaufverfolgung. Der Application Insights-Java-Agent bietet Stabilitätsgarantien für Anforderungs- und Abhängigkeits-Telemetrie. Weitere Informationen finden Sie unter Konfigurieren der Ablaufverfolgung im Azure SDK für Java.

Nächste Schritte

Nachdem Sie nun gesehen haben, wie die Protokollierung im Azure SDK für Java funktioniert, sollten Sie die folgenden Links überprüfen, um eine Anleitung zu erhalten, wie Sie einige der beliebteren Frameworks für die Java-Protokollierung für die Zusammenarbeit mit SLF4J und den Java-Clientbibliotheken konfigurieren: