Logboekregistratie configureren in de Azure SDK voor Java

  • Artikel

Dit artikel bevat een overzicht van het inschakelen van logboekregistratie in toepassingen die gebruikmaken van de Azure SDK voor Java. De Azure-clientbibliotheken voor Java hebben twee opties voor logboekregistratie:

  • Een ingebouwd framework voor logboekregistratie voor tijdelijke foutopsporing.
  • Ondersteuning voor logboekregistratie met behulp van de SLF4J-interface .

U wordt aangeraden SLF4J te gebruiken, omdat deze bekend is in het Java-ecosysteem en goed is gedocumenteerd. Raadpleeg de SLF4J-gebruikershandleiding voor meer informatie.

Dit artikel bevat koppelingen naar andere artikelen die betrekking hebben op veel van de populaire Frameworks voor Java-logboekregistratie. Deze andere artikelen bevatten configuratievoorbeelden en beschrijven hoe de Azure-clientbibliotheken de frameworks voor logboekregistratie kunnen gebruiken.

Ongeacht de configuratie van logboekregistratie die u gebruikt, is dezelfde logboekuitvoer beschikbaar in beide gevallen, omdat alle uitvoer van logboekregistratie in de Azure-clientbibliotheken voor Java wordt gerouteerd via een abstractie van azure-core ClientLogger .

De rest van dit artikel bevat informatie over de configuratie van alle beschikbare logboekregistratieopties.

Logboekregistratie van HTTP-aanvragen/-antwoorden inschakelen

HTTP-aanvraag- en antwoordlogboekregistratie zijn standaard uitgeschakeld. U kunt clients configureren die via HTTP communiceren met Azure-services om een logboekrecord te schrijven voor elke aanvraag en reactie (of uitzondering) die ze ontvangen.

Als u OpenTelemetry gebruikt, kunt u overwegen gedistribueerde tracering te gebruiken in plaats van logboekregistratie voor HTTP-aanvragen. Zie Tracering configureren in de Azure SDK voor Java voor meer informatie.

HTTP-logboekregistratie configureren met een omgevingsvariabele

U kunt de AZURE_HTTP_LOG_DETAIL_LEVEL omgevingsvariabele gebruiken om WERELDWIJD HTTP-logboeken in te schakelen. Deze variabele ondersteunt de volgende waarden:

  • NONE: HTTP-logboeken zijn uitgeschakeld. Dit is de standaardwaarde.
  • BASIC: HTTP-logboeken bevatten aanvraagmethode, opgeschoonde aanvraag-URL, aantal pogingen, antwoordcode en de inhoudslengte voor aanvraag- en antwoordteksten.
  • HEADERS: HTTP-logboeken bevatten alle basisgegevens en bevatten ook headers die veilig zijn voor logboekregistratiedoeleinden. Dat wil gezegd, ze bevatten geen geheimen of gevoelige informatie. De volledige lijst met headernamen is beschikbaar in de klasse HttpLogOptions .
  • BODY_AND_HEADERS: HTTP-logboeken bevatten alle details van het HEADERS niveau en bevatten ook aanvraag- en antwoordteksten zolang ze kleiner zijn dan 16 kB en kunnen worden afgedrukt.

Notitie

De aanvraag-URL is opgeschoond. Dat wil gezegd: alle queryparameterwaarden worden redacted, met uitzondering van de api-version waarde. Afzonderlijke clientbibliotheken kunnen andere queryparameters toevoegen die bekend zijn als veilig voor de acceptatielijst.

De SAS-URL (Shared Access Signature) van Azure Blob Storage wordt bijvoorbeeld vastgelegd in de volgende indeling: 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

Waarschuwing

Aanvraag- en antwoordteksten voor logboekregistratie worden niet aanbevolen in productie omdat ze mogelijk gevoelige informatie bevatten, de prestaties aanzienlijk beïnvloeden, wijzigen hoe inhoud wordt gebufferd en andere bijwerkingen hebben.

HTTP-logboekregistratie in code configureren

Azure-clientbouwers die de HttpTrait<T-interface> implementeren, bieden ondersteuning voor configuratie van HTTP-logboekregistratie op basis van code. Configuratie op basis van code is van toepassing op afzonderlijke clientinstanties en biedt meer opties en aanpassingen in vergelijking met de configuratie van omgevingsvariabelen.

Als u logboeken wilt configureren, geeft u een exemplaar van HttpLogOptions door aan de httpLogOptions methode in de bijbehorende clientbouwer. De volgende code toont een voorbeeld voor de App Configuration-service:

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

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

Met deze code worden HTTP-logboeken met headers ingeschakeld en worden de Accept-Ranges antwoordheader en de label queryparameter toegevoegd aan de bijbehorende acceptatielijsten. Na deze wijziging moeten deze waarden worden weergegeven in de geproduceerde logboeken.

Zie de httpLogOptions-documentatie voor de volledige lijst met configuratieopties.

Standaardlogger (voor tijdelijke foutopsporing)

Zoals vermeld, gebruiken alle Azure-clientbibliotheken SLF4J voor logboekregistratie, maar er is een terugval, standaardlogger ingebouwd in Azure-clientbibliotheken voor Java. Deze standaardlogger wordt verstrekt voor gevallen waarin een toepassing wordt geïmplementeerd en logboekregistratie is vereist, maar het is niet mogelijk om de toepassing opnieuw te implementeren met een SLF4J-logboekregistratie. Als u deze logboekregistratie wilt inschakelen, moet u eerst zeker zijn dat er geen SLF4J-logboekregistratie bestaat (omdat deze prioriteit heeft) en vervolgens de AZURE_LOG_LEVEL omgevingsvariabele instelt. In de volgende tabel ziet u de waarden die zijn toegestaan voor deze omgevingsvariabele:

Logboekniveau Toegestane waarde voor omgevingsvariabele
VERBOSE verbose, debug
INFORMATIONAL info, , informationinformational
WARNING warn, warning
FOUT err, error

Nadat de omgevingsvariabele is ingesteld, start u de toepassing opnieuw om de omgevingsvariabele in te schakelen. Deze logboekregistratie registreert zich bij de console en biedt geen geavanceerde aanpassingsmogelijkheden van een SLF4J-implementatie, zoals rollover en logboekregistratie naar bestand. Als u de logboekregistratie opnieuw wilt uitschakelen, verwijdert u de omgevingsvariabele en start u de toepassing opnieuw.

SLF4J-logboekregistratie

Standaard moet u logboekregistratie configureren met behulp van een door SLF4J ondersteund logboekregistratieframework. Neem eerst een relevante implementatie van SLF4J-logboekregistratie op als een afhankelijkheid van uw project. Zie Projectafhankelijkheden declareren voor logboekregistratie in de gebruikershandleiding van SLF4J voor meer informatie. Configureer vervolgens uw logboekregistratie zo nodig in uw omgeving, zoals het instellen van logboekniveaus, het configureren van welke klassen wel en niet registreren, enzovoort. Enkele voorbeelden vindt u via de koppelingen in dit artikel, maar zie de documentatie voor het gekozen logboekregistratieframework voor meer informatie.

Logboekindeling

Frameworks voor logboekregistratie ondersteunen aangepaste opmaak en indelingen van logboekberichten. We raden u aan ten minste de volgende velden op te geven om problemen met Azure-clientbibliotheken op te lossen:

  • Datum en tijd met precisie van milliseconden
  • Ernst van logboek
  • Naam van logboekregistratie
  • Threadnaam
  • Bericht

Zie de documentatie voor het logboekregistratieframework dat u gebruikt voor voorbeelden.

Gestructureerde logboekregistratie

Naast het vastleggen van de eerder genoemde algemene eigenschappen, maken Azure-clientbibliotheken aantekeningen bij logboekberichten met extra context, indien van toepassing. U ziet bijvoorbeeld logboeken met JSON-indeling met az.sdk.message context die zijn geschreven als andere hoofdeigenschappen, zoals wordt weergegeven in het volgende voorbeeld:

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}

Wanneer u logboeken naar Azure Monitor verzendt, kunt u de Kusto-querytaal gebruiken om deze te parseren. De volgende query bevat een voorbeeld:

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)

Notitie

Azure-clientbibliotheeklogboeken zijn bedoeld voor ad-hoc foutopsporing. Het wordt afgeraden om te vertrouwen op de logboekindeling om uw toepassing te waarschuwen of te bewaken. Azure-clientbibliotheken garanderen niet de stabiliteit van logboekberichten of contextsleutels. Voor dergelijke doeleinden raden we u aan gedistribueerde tracering te gebruiken. De Java-agent van Application Insights biedt stabiliteitsgaranties voor aanvraag- en afhankelijkheidstelemetrie. Zie Tracering configureren in de Azure SDK voor Java voor meer informatie.

Volgende stappen

Nu u weet hoe logboekregistratie werkt in de Azure SDK voor Java, kunt u de volgende artikelen bekijken. Deze artikelen bevatten richtlijnen voor het configureren van enkele van de populairste Java-frameworks voor logboekregistratie voor gebruik met SLF4J en de Java-clientbibliotheken: