Nastavení protokolování v sadě Azure SDK pro Javu

Tento článek obsahuje přehled povolení protokolování v aplikacích, které používají Azure SDK pro Java. Klientské knihovny Azure pro Java nabízejí dvě možnosti protokolování:

• Integrovaný framework pro logování určený pro dočasné účely ladění.
• Podpora protokolování pomocí rozhraní SLF4J .

Používejte SLF4J, protože je dobře známý v ekosystému Java a je dobře zdokumentovaný. Další informace naleznete v uživatelské příručce SLF4J .

Tento článek odkazuje na další články, které se týkají mnoha oblíbených architektur protokolování Java. Tyto další články obsahují příklady konfigurace a popisují, jak můžou klientské knihovny Azure používat architektury protokolování.

Ať už použijete jakoukoli konfiguraci protokolování, získáte stejný výstup protokolování, protože veškerý výstup protokolování v klientských knihovnách Azure pro Javu prochází přes abstrakci azure-core ClientLogger.

Zbytek tohoto článku podrobně popisuje konfiguraci všech dostupných možností protokolování.

Povolení protokolování požadavků HTTP a odpovědí

Protokolování požadavků HTTP a odpovědí je ve výchozím nastavení vypnuté. Klienty, kteří komunikují se službami Azure přes PROTOKOL HTTP, můžete nakonfigurovat tak, aby zapisovali záznam protokolu pro každý požadavek a odpověď (nebo výjimku), které obdrží.

Pokud používáte OpenTelemetry, zvažte použití distribuovaného trasování místo protokolování pro požadavky HTTP. Další informace najdete v tématu Konfigurace trasování v sadě Azure SDK pro Javu.

Konfigurace protokolování HTTP pomocí proměnné prostředí

Pomocí proměnné prostředí AZURE_HTTP_LOG_DETAIL_LEVEL zapněte protokolování HTTP pro všechny klienty. Nastavte tuto proměnnou na jednu z následujících hodnot:

• NONE: Protokolování HTTP je vypnuté. Tato hodnota je výchozí.
• BASIC: Protokoly HTTP obsahují metodu požadavku, sanitizovanou adresu URL požadavku, počet pokusů, kód odpovědi a délku obsahu těl požadavku a odpovědi.
• HEADERS: Protokoly HTTP obsahují všechny základní podrobnosti a také hlavičky, které jsou známé jako bezpečné pro účely protokolování – to znamená, že neobsahují tajné kódy ani citlivé informace. Úplný seznam názvů hlaviček je k dispozici ve třídě HttpLogOptions .
• BODY_AND_HEADERS: Protokoly HTTP obsahují všechny podrobnosti poskytované úrovní HEADERS a také těla požadavků a odpovědí, pokud jsou menší než 16 kB a tisknutelné.

Například adresa URL sdíleného přístupového podpisu (SAS) služby Azure Blob Storage se protokoluje v následujícím formátu: 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

Konfigurace protokolování HTTP v kódu

Tvůrci klientů Azure, kteří implementují rozhraní HttpTrait<T> , podporují konfiguraci protokolování HTTP na základě kódu. Konfigurace založená na kódu se vztahuje na jednotlivé instance klienta a poskytuje více možností a přizpůsobení v porovnání s konfigurací proměnných prostředí.

Pokud chcete nakonfigurovat logovací protokoly, je třeba předat instanci HttpLogOptions metodě httpLogOptions v odpovídajícím tvůrci klienta. Následující kód ukazuje příklad služby App Configuration:

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

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

Tento kód aktivuje protokolování HTTP se záhlavími a přidává hlavičku Accept-Ranges odpovědi a parametr dotazu label do odpovídajících seznamů povolení. Po této změně se tyto hodnoty zobrazí v vytvořených protokolech.

Úplný seznam možností konfigurace najdete v dokumentaci HttpLogOptions .

Výchozí zapisovač (pro dočasné ladění)

Jak je uvedeno, všechny klientské knihovny Azure používají pro protokolování SLF4J, ale existuje záložní výchozí protokolovací nástroj integrovaný do klientských knihoven Azure pro Javu. Tento výchozí protokolovací nástroj je určený pro případy, kdy nasazujete aplikaci a potřebujete protokolování, ale nemůžete ji znovu nasadit s zahrnutým protokolovacím nástrojem SLF4J. Pokud chcete tento protokolovací nástroj povolit, nejprve se ujistěte, že neexistuje žádný protokolovací nástroj SLF4J (protože má přednost) a pak nastavte proměnnou AZURE_LOG_LEVEL prostředí. Následující tabulka uvádí hodnoty povolené pro tuto proměnnou prostředí:

Po nastavení proměnné prostředí restartujte aplikaci, aby se povolila proměnná prostředí. Tento protokolovací nástroj se do konzoly zaprotokoluje a neposkytuje pokročilé možnosti přizpůsobení implementace SLF4J, jako je například rollover a protokolování do souboru. Pokud chcete protokolování vypnout, odeberte proměnnou prostředí a restartujte aplikaci.

Protokolování SLF4J

Ve výchozím nastavení nakonfigurujte protokolování pomocí architektury protokolování s podporou SLF4J. Nejprve zahrňte příslušnou implementaci protokolování SLF4J jako závislost z vašeho projektu. Další informace naleznete v tématu Deklarování závislostí projektu pro protokolování v uživatelské příručce SLF4J. Dále nakonfigurujte protokolovací nástroj tak, aby fungoval podle potřeby ve vašem prostředí, jako je například nastavení úrovní protokolu, konfigurace tříd, které třídy dělají, a tak dále. Některé příklady jsou k dispozici prostřednictvím odkazů v tomto článku, ale další informace najdete v dokumentaci pro vámi zvolenou architekturu protokolování.

Formát protokolu

Rozhraní protokolování podporují vlastní formátování a rozložení zpráv protokolu. Zahrňte aspoň následující pole, abyste mohli řešit potíže s Azure klientskými knihovnami:

• Datum a čas s přesností milisekund
• Závažnost protokolu
• Název protokolovacího nástroje
• Název vlákna
• Zpráva

Příklady najdete v dokumentaci k rozhraní protokolování, které používáte.

Strukturované protokolování

Kromě protokolování společných vlastností uvedených výše klientské knihovny Azure při přidávání poznámek ke zprávám protokolu s dodatečným kontextem, pokud je to možné. Můžete například vidět protokoly ve formátu JSON obsahující az.sdk.message kontext napsané jako další kořenové vlastnosti, jak je znázorněno v následujícím příkladu:

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}

Když odesíláte protokoly do služby Azure Monitor, můžete je analyzovat pomocí dotazovacího jazyka Kusto . Následující dotaz obsahuje příklad:

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)

Další kroky

Teď, když víte, jak funguje protokolování v sadě Azure SDK pro Javu, zvažte kontrolu následujících článků. Tyto články obsahují pokyny ke konfiguraci některých nejoblíbenějších architektur protokolování v Javě pro práci s SLF4J a klientskými knihovnami Java:

• java.util.logging
• Zpětný protokol
• Log4J
• trasování