Udostępnij za pośrednictwem

Konfigurowanie rejestrowania w zestawie Azure SDK dla języka Java

  • Artykuł

Ten artykuł zawiera omówienie sposobu włączania rejestrowania w aplikacjach korzystających z zestawu Azure SDK dla języka Java. Biblioteki klienta platformy Azure dla języka Java mają dwie opcje rejestrowania:

  • Wbudowana struktura rejestrowania na potrzeby tymczasowego debugowania.
  • Obsługa rejestrowania przy użyciu interfejsu SLF4J .

Zalecamy użycie interfejsu SLF4J, ponieważ jest dobrze znany w ekosystemie Języka Java i jest dobrze udokumentowany. Aby uzyskać więcej informacji, zobaczpodręcznik użytkownika fasady SLF4J.

Ten artykuł zawiera linki do innych artykułów, które obejmują wiele popularnych platform rejestrowania języka Java. Te inne artykuły zawierają przykłady konfiguracji i opisują, jak biblioteki klienckie platformy Azure mogą używać struktur rejestrowania.

Niezależnie od używanej konfiguracji rejestrowania te same dane wyjściowe dziennika są dostępne w obu przypadkach, ponieważ wszystkie dane wyjściowe rejestrowania w bibliotekach klienta platformy Azure dla języka Java są kierowane za pośrednictwem abstrakcji azure-core ClientLogger .

W pozostałej części tego artykułu szczegółowo opisano konfigurację wszystkich dostępnych opcji rejestrowania.

Włączanie rejestrowania żądań HTTP/odpowiedzi

Rejestrowanie żądań HTTP i odpowiedzi jest domyślnie wyłączone. Można skonfigurować klientów komunikujących się z usługami platformy Azure za pośrednictwem protokołu HTTP w celu zapisania rekordu dziennika dla każdego odbieranego żądania i odpowiedzi (lub wyjątku).

Jeśli używasz biblioteki OpenTelemetry, rozważ użycie śledzenia rozproszonego zamiast rejestrowania dla żądań HTTP. Aby uzyskać więcej informacji, zobacz Konfigurowanie śledzenia w zestawie Azure SDK dla języka Java.

Konfigurowanie rejestrowania HTTP za pomocą zmiennej środowiskowej

Możesz użyć zmiennej środowiskowej AZURE_HTTP_LOG_DETAIL_LEVEL , aby włączyć dzienniki HTTP globalnie. Ta zmienna obsługuje następujące wartości:

  • NONE: dzienniki HTTP są wyłączone. Jest to wartość domyślna.
  • BASIC: Dzienniki HTTP zawierają metodę żądania, oczyszczony adres URL żądania, liczbę prób, kod odpowiedzi oraz długość zawartości dla treści żądań i odpowiedzi.
  • HEADERS: Dzienniki HTTP zawierają wszystkie podstawowe szczegóły, a także nagłówki, które są znane jako bezpieczne do celów rejestrowania — to znaczy, że nie zawierają wpisów tajnych ani poufnych informacji. Pełna lista nazw nagłówków jest dostępna w klasie HttpLogOptions .
  • BODY_AND_HEADERS: Dzienniki HTTP zawierają wszystkie szczegóły podane na HEADERS poziomie, a także zawierają treść żądania i odpowiedzi, o ile są mniejsze niż 16 KB i można je wydrukować.

Uwaga

Adres URL żądania jest czyszczone — oznacza to, że wszystkie wartości parametrów zapytania są redacted z wyjątkiem api-version wartości . Poszczególne biblioteki klienckie mogą dodawać inne parametry zapytania, które są znane jako bezpieczne dla listy dozwolonych.

Na przykład adres URL sygnatury dostępu współdzielonego usługi Azure Blob Storage jest rejestrowany w następującym formacie: 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

Ostrzeżenie

Jednostki żądań rejestrowania i odpowiedzi nie są zalecane w środowisku produkcyjnym, ponieważ mogą zawierać poufne informacje, znacząco wpłynąć na wydajność, zmienić sposób buforowania zawartości i mieć inne skutki uboczne.

Konfigurowanie rejestrowania HTTP w kodzie

Konstruktory klientów platformy Azure, które implementują interfejs HttpTrait<T> , obsługują konfigurację rejestrowania HTTP opartą na kodzie. Konfiguracja oparta na kodzie ma zastosowanie do poszczególnych wystąpień klienta i udostępnia więcej opcji i dostosowań w porównaniu z konfiguracją zmiennej środowiskowej.

Aby skonfigurować dzienniki, przekaż wystąpienie obiektu HttpLogOptions do httpLogOptions metody w odpowiednim konstruktorze klienta. Poniższy kod przedstawia przykład usługi App Configuration Service:

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

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

Ten kod umożliwia dzienniki HTTP z nagłówkami i dodaje Accept-Ranges nagłówek odpowiedzi oraz label parametr zapytania do odpowiednich list dozwolonych. Po tej zmianie te wartości powinny pojawić się w wygenerowanych dziennikach.

Pełną listę opcji konfiguracji można znaleźć w dokumentacji protokołu HttpLogOptions .

Domyślny rejestrator (na potrzeby debugowania tymczasowego)

Jak wspomniano, wszystkie biblioteki klienckie platformy Azure używają bibliotek SLF4J do rejestrowania, ale istnieje rezerwowy domyślny rejestrator wbudowany w biblioteki klienckie platformy Azure dla języka Java. Ten domyślny rejestrator jest udostępniany w przypadkach, w których aplikacja jest wdrożona, a rejestrowanie jest wymagane, ale nie można ponownie wdrożyć aplikacji z dołączonym rejestratorem SLF4J. Aby włączyć ten rejestrator, musisz najpierw mieć pewność, że żaden rejestrator SLF4J nie istnieje (ponieważ ma pierwszeństwo), a następnie ustawić zmienną AZURE_LOG_LEVEL środowiskową. W poniższej tabeli przedstawiono wartości dozwolone dla tej zmiennej środowiskowej:

Poziom dziennika Dozwolone wartości zmiennej środowiskowej
PEŁNY verbose, debug
INFORMACYJNY info, , informationinformational
OSTRZEŻENIE warn, warning
BŁĄD err, error

Po ustawieniu zmiennej środowiskowej ponownie uruchom aplikację, aby umożliwić zastosowanie zmiennej środowiskowej. Ten rejestrator rejestruje się w konsoli i nie zapewnia zaawansowanych możliwości dostosowywania implementacji SLF4J, takich jak przerzucanie i rejestrowanie do pliku. Aby ponownie wyłączyć rejestrowanie, usuń zmienną środowiskową i ponownie uruchom aplikację.

Rejestrowanie SLF4J

Domyślnie należy skonfigurować rejestrowanie przy użyciu platformy rejestrowania obsługiwanej przez protokół SLF4J. Najpierw uwzględnij odpowiednią implementację rejestrowania SLF4J jako zależność od projektu. Aby uzyskać więcej informacji, zobacz Deklarowanie zależności projektu na potrzeby rejestrowania w podręczniku użytkownika SLF4J. Następnie skonfiguruj rejestrator tak, aby działał zgodnie z potrzebami w środowisku, na przykład ustawiając poziomy dzienników, konfigurując klasy, które nie są rejestrowane i tak dalej. Niektóre przykłady są udostępniane za pośrednictwem linków w tym artykule, ale aby uzyskać więcej informacji, zobacz dokumentację wybranej struktury rejestrowania.

Format dziennika

Struktury rejestrowania obsługują niestandardowe formatowanie i układy komunikatów dziennika. Zalecamy uwzględnienie co najmniej następujących pól, aby umożliwić rozwiązywanie problemów z bibliotekami klienta platformy Azure:

  • Data i godzina z dokładnością milisekund
  • Ważność dziennika
  • Nazwa rejestratora
  • Nazwa wątku
  • Komunikat

Przykłady można znaleźć w dokumentacji używanej platformy rejestrowania.

Rejestrowanie strukturalne

Oprócz rejestrowania typowych właściwości wymienionych wcześniej bibliotek klienckich platformy Azure dodawać adnotacje do komunikatów dziennika z dodatkowym kontekstem, jeśli ma to zastosowanie. Na przykład dzienniki az.sdk.message w formacie JSON mogą być wyświetlane z kontekstem zapisanym jako inne właściwości główne, jak pokazano w poniższym przykładzie:

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}

Podczas wysyłania dzienników do usługi Azure Monitor możesz użyć języka zapytań Kusto, aby je przeanalizować. Poniższe zapytanie zawiera przykład:

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)

Uwaga

Dzienniki biblioteki klienta platformy Azure są przeznaczone do debugowania ad hoc. Nie zalecamy polegania na formacie dziennika w celu alertu lub monitorowania aplikacji. Biblioteki klienckie platformy Azure nie gwarantują stabilności komunikatów dziennika ani kluczy kontekstowych. W takich celach zalecamy używanie śledzenia rozproszonego. Agent aplikacji Szczegółowe informacje Java zapewnia gwarancje stabilności dla danych telemetrycznych żądań i zależności. Aby uzyskać więcej informacji, zobacz Konfigurowanie śledzenia w zestawie Azure SDK dla języka Java.

Następne kroki

Teraz, gdy wiesz, jak działa rejestrowanie w zestawie Azure SDK dla języka Java, rozważ zapoznanie się z następującymi artykułami. Te artykuły zawierają wskazówki dotyczące konfigurowania niektórych bardziej popularnych struktur rejestrowania języka Java do pracy z bibliotekami SLF4J i bibliotekami klienta Java: