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

Článek
05/01/2024

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

Integrovaná architektura protokolování pro dočasné účely ladění.
Podpora protokolování pomocí rozhraní SLF4J .

Doporučujeme používat SLF4J, protože je dobře známý v ekosystému Java a je dobře zdokumentovaný. Další informace najdete v uživatelské příručce k 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í.

Bez ohledu na konfiguraci protokolování, kterou použijete, je k dispozici stejný výstup protokolu v obou případech, protože veškerý výstup protokolování v klientských knihovnách Azure pro Javu se směruje prostřednictvím abstrakce jádra Azure ClientLogger .

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

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

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í

Proměnnou AZURE_HTTP_LOG_DETAIL_LEVEL prostředí můžete použít k globálnímu povolení protokolů HTTP. Tato proměnná podporuje následující hodnoty:

NONE: Protokoly HTTP jsou zakázané. Tato hodnota je výchozí.
BASIC: Protokoly HTTP obsahují metodu požadavku, adresu URL sanitizovaného požadavku, počet try, kód odpovědi a délku obsahu pro tělo 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, které HEADERS poskytuje úroveň, a také obsahují těla požadavků a odpovědí, pokud jsou menší než 16 kB a tisknout.

Poznámka:

Adresa URL požadavku je upravena – to znamená, že všechny hodnoty parametrů dotazu jsou redactovány s výjimkou api-version hodnoty. Jednotlivé klientské knihovny mohou do seznamu povolených přidat další parametry dotazu, o kterých je známo, že jsou bezpečné.

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

Upozorňující

Protokolování požadavků a odpovědí se nedoporučuje v produkčním prostředí, protože můžou obsahovat citlivé informace, výrazně ovlivnit výkon, změnit způsob ukládání obsahu do vyrovnávací paměti a mít další vedlejší účinky.

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 protokoly, předejte instanci HttpLogOptionshttpLogOptions metodě 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 povolí protokoly HTTP se záhlavími a přidá hlavičku Accept-Ranges odpovědi a label parametr dotazu do odpovídajících seznamů povolených. Po této změně by se tyto hodnoty měly objevit v vytvořených protokolech.

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

Výchozí protokolovací nástroj (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 k dispozici pro případy, kdy je aplikace nasazená a vyžaduje se protokolování, ale není možné aplikaci znovu nasadit s zahrnutým protokolovacím nástrojem SLF4J. Chcete-li povolit tento protokolovací nástroj, musíte nejprve mít jistotu, ž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í:

Úroveň protokolu	Povolené hodnoty proměnné prostředí
PODROBNÁ	`verbose`, `debug`
INFORMATIVNÍ	`info`, , `informationinformational`
UPOZORNĚNÍ	`warn`, `warning`
CHYBA	`err`, `error`

Po nastavení proměnné prostředí restartujte aplikaci, aby se proměnná prostředí projevila. 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í znovu vypnout, stačí odebrat proměnnou prostředí a restartovat aplikaci.

Protokolování SLF4J

Ve výchozím nastavení byste měli nakonfigurovat protokolování pomocí architektury protokolování podporované 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. Doporučujeme přidat aspoň následující pole, aby bylo možné řešit potíže s klientskými knihovnami Azure:

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)

Poznámka:

Protokoly klientské knihovny Azure jsou určené pro ad hoc ladění. Nedoporučujeme spoléhat se na formát protokolu pro upozorňování nebo monitorování vaší aplikace. Klientské knihovny Azure nezaručují stabilitu zpráv protokolu ani kontextových klíčů. Pro takové účely doporučujeme použít distribuované trasování. Agent Application Přehledy Java poskytuje záruky stability pro telemetrii požadavků a závislostí. Další informace najdete v tématu Konfigurace trasování v sadě Azure SDK pro Javu.

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:

Sdílet prostřednictvím