Freigeben über

Konfigurieren der Protokollierung im Azure SDK für Java

Dieser Artikel enthält eine Übersicht über das Aktivieren der Protokollierung in Anwendungen, die das Azure SDK für Java verwenden. Die Azure-Clientbibliotheken für Java besitzen zwei Protokollierungsoptionen:

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

Es wird empfohlen, SLF4J zu verwenden, da es im Java-Ökosystem bekannt ist und gut dokumentiert ist. Weitere Informationen finden Sie im SLF4J-Benutzerhandbuch.

Dieser Artikel enthält Links zu anderen Artikeln, die viele der beliebten Java-Protokollierungsframeworks abdecken. Diese anderen Artikel enthalten Konfigurationsbeispiele und beschreiben, wie die Azure-Clientbibliotheken die Protokollierungsframeworks verwenden können.

Unabhängig davon, welche Protokollierungskonfiguration Sie verwenden, ist die gleiche Protokollausgabe in beiden Fällen verfügbar, da alle Protokollierungsausgabe in den Azure-Clientbibliotheken für Java über eine Azure-Core-Abstraktion ClientLogger weitergeleitet wird.

Im restlichen Artikel wird die Konfiguration aller verfügbaren Protokollierungsoptionen 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 Distributed Tracing statt der Protokollierung für HTTP-Anforderungen verwenden. Weitere Informationen finden Sie unter Konfigurieren der Ablaufverfolgung im Azure SDK für Java.

Konfigurieren Sie die 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. Dieser Wert ist der Standardwert.
  • BASIC: HTTP-Protokolle enthalten die Anforderungsmethode, die bereinigte Anforderungs-URL, die Versuchsanzahl, den Antwortcode und die Inhaltslänge für Anforderungs- und Antwortinhalte.
  • 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 für die Zulassungsliste bekannterweise sicher 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 .

Standardprotokollierer (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. In der folgenden Tabelle sind die werte aufgeführt, die für diese Umgebungsvariable zulässig sind:

Protokoll-Ebene Zulässige Umgebungsvariablenwerte
WEITSCHWEIFIG verbose, debug
MITTEILSAM info, informationinformational
WARNUNG warn, warning
FEHLER err, error

Nachdem die Umgebungsvariable festgelegt wurde, starten Sie die Anwendung neu, um die Umgebungsvariable wirksam zu machen. 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 erneut zu deaktivieren, entfernen Sie einfach die Umgebungsvariable, und starten Sie die Anwendung neu.

SLF4J-Protokollierung

Standardmäßig sollten Sie die Protokollierung mit einem vom SLF4J unterstützten Protokollierungsframework 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 er in Ihrer Umgebung funktioniert, indem Sie beispielsweise Protokollebenen festlegen und bestimmen, welche Klassen protokollieren und welche nicht. 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
  • Schweregrad des Protokolls
  • Loggername
  • Thread Name
  • Nachricht

Beispiele finden Sie in der Dokumentation zum verwendeten Protokollierungsframework.

Strukturierte Protokollierung

Zusätzlich zur Protokollierung der oben erwähnten allgemeinen Eigenschaften kommentieren Azure-Clientbibliotheken Protokollnachrichten mit zusätzlichem Kontext, wenn zutreffend. Beispielsweise könnten Sie Protokolle im JSON-Format sehen, die az.sdk.message enthalten, wobei der Kontext als andere Stammeigenschaften geschrieben ist, 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 wird die Verwendung der verteilten Ablaufverfolgung empfohlen. 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: