Konfigurieren der Protokollierung im Azure SDK für Java

  • Artikel

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.

Aktivieren der Protokollierung von HTTP-Anforderungen/-Antworten

Die HTTP-Anforderungs- und Antwortprotokollierung ist standardmäßig deaktiviert. Sie können Clients konfigurieren, die mit Azure-Diensten über HTTP kommunizieren, um einen Protokolldatensatz für jede empfangene Anforderung und Antwort (oder Ausnahme) zu schreiben.

Wenn Sie OpenTelemetry verwenden, sollten Sie die verteilte Ablaufverfolgung anstelle der Protokollierung für HTTP-Anforderungen verwenden. Weitere Informationen finden Sie unter Konfigurieren der Ablaufverfolgung im Azure SDK für Java.

Konfigurieren der HTTP-Protokollierung mit einer Umgebungsvariable

Sie können die Umgebungsvariable AZURE_HTTP_LOG_DETAIL_LEVEL verwenden, um HTTP-Protokolle global zu aktivieren. Diese Variable unterstützt die folgenden Werte:

  • NONE: HTTP-Protokolle sind deaktiviert. Dies ist der Standardwert.
  • BASIC: HTTP-Protokolle enthalten Anforderungsmethode, sanitisierte Anforderungs-URL, Anzahl, Antwortcode und die Inhaltslänge für Anforderungs- und Antworttexte.
  • HEADERS: HTTP-Protokolle enthalten alle grundlegenden Details und enthalten auch Header, die für Protokollierungszwecke als sicher bekannt sind - d. h., sie enthalten keine geheimen oder vertraulichen Informationen. Die vollständige Liste der Headernamen ist in der HttpLogOptions-Klasse verfügbar.
  • BODY_AND_HEADERS: HTTP-Protokolle enthalten alle Details der HEADERS Ebene und enthalten auch Anforderungs- und Antworttexte, sofern sie kleiner als 16 KB sind und druckbar sind.

Hinweis

Die Anforderungs-URL wird sanitiert – d. h., alle Abfrageparameterwerte werden mit Ausnahme des api-version Werts redigiert. Einzelne Clientbibliotheken können weitere Abfrageparameter hinzufügen, die als sicher für die Zulassungsliste bekannt sind.

Die SAS-URL (Shared Access Signature) von Azure Blob Storage wird z. B. im folgenden Format protokolliert: https://myaccount.blob.core.windows.net/pictures/profile.jpg?sv=REDACTED&st=REDACTED&se=REDACTED&sr=REDACTED&sp=REDACTED&rscd=REDACTED&rsct=REDACTED&sig=REDACTED

Warnung

Die Protokollierung von Anforderungs- und Antworttexten wird in der Produktion nicht empfohlen, da sie möglicherweise vertrauliche Informationen enthalten, die Leistung erheblich beeinträchtigen, die Pufferung von Inhalten ändern und andere Nebenwirkungen haben.

Konfigurieren der HTTP-Protokollierung im Code

Azure-Client-Generatoren, die die HttpTrait<T-Schnittstelle> implementieren, unterstützen codebasierte HTTP-Protokollierungskonfiguration. Codebasierte Konfiguration gilt für einzelne Clientinstanzen und bietet mehr Optionen und Anpassungen im Vergleich zur Umgebungsvariablenkonfiguration.

Um Protokolle zu konfigurieren, übergeben Sie eine Instanz von HttpLogOptions an die httpLogOptions Methode für den entsprechenden Client-Generator. Der folgende Code zeigt ein Beispiel für den App-Konfigurationsdienst:

HttpLogOptions httpLogOptions = new HttpLogOptions()
        .setLogLevel(HttpLogDetailLevel.HEADERS)
        .addAllowedHeaderName("Accept-Ranges")
        .addAllowedQueryParamName("label");

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
        .httpLogOptions(httpLogOptions)
        ...
        .buildClient();

Dieser Code aktiviert HTTP-Protokolle mit Headern und fügt den Accept-Ranges Antwortheader und den label Abfrageparameter zu den entsprechenden Zulassungslisten hinzu. Nach dieser Änderung sollten diese Werte in den erstellten Protokollen angezeigt werden.

Die vollständige Liste der Konfigurationsoptionen finden Sie in der HttpLogOptions-Dokumentation .

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. Dieser Standardprotokollierer wird für Fälle bereitgestellt, in denen eine Anwendung bereitgestellt wird und die Protokollierung erforderlich ist, aber es ist nicht möglich, die Anwendung mit einem enthaltenen SLF4J-Logger erneut bereitzustellen. Um diesen Logger zu aktivieren, müssen Sie zunächst sicher sein, dass kein SLF4J-Logger vorhanden ist (da er Vorrang hat), und dann die AZURE_LOG_LEVEL Umgebungsvariable festlegen. Die folgende Tabelle enthält die zulässigen Werte für diese Umgebungsvariable:

Protokoll-Ebene Zulässige Werte für Umgebungsvariablen
VERBOSE verbose, debug
INFORMATIONAL info, informationinformational
WARNUNG warn, warning
FEHLER err, error

Nachdem die Umgebungsvariable festgelegt wurde, starten Sie die Anwendung neu, damit die Umgebungsvariable wirksam wird. Dieser Logger protokolliert die Konsole und bietet nicht die erweiterten Anpassungsfunktionen einer SLF4J-Implementierung, z. B. Rollover und Protokollierung in 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, konfigurieren, welche Klassen nicht protokollieren usw. funktionieren. Einige Beispiele werden über die Links in diesem Artikel bereitgestellt, aber weitere Informationen finden Sie in der Dokumentation zu Ihrem ausgewählten Protokollierungsframework.

Protokollformat

Protokollierungsframeworks unterstützen benutzerdefinierte Protokollnachrichtenformatierungen und Layouts. Es wird empfohlen, mindestens die folgenden Felder einzuschluss, um die Problembehandlung von Azure-Clientbibliotheken zu ermöglichen:

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

Beispiele finden Sie in der Dokumentation zum verwendeten Protokollierungsframework.

Strukturierte Protokollierung

Zusätzlich zur Protokollierung der allgemeinen Eigenschaften, die zuvor Erwähnung wurden, kommentieren Azure-Clientbibliotheken Protokollnachrichten mit zusätzlichem Kontext bei Bedarf. So können beispielsweise JSON-formatierte Protokolle mit az.sdk.message Kontext angezeigt werden, die 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 sie mithilfe der Kusto-Abfragesprache analysieren. Die folgende Abfrage stellt ein Beispiel bereit:

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 ad-hoc-Debugging vorgesehen. Es wird nicht empfohlen, auf das Protokollformat zu vertrauen, 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 wissen, wie die Protokollierung im Azure SDK für Java funktioniert, sollten Sie sich die folgenden Artikel ansehen. Diese Artikel enthalten Anleitungen zum Konfigurieren einiger der beliebtesten Java-Protokollierungsframeworks für die Arbeit mit SLF4J und den Java-Clientbibliotheken: