Java용 Azure SDK에서 로깅 구성

아티클
05/01/2024

이 문서에서는 Java용 Azure SDK를 사용하는 애플리케이션에서 로깅을 사용하도록 설정하는 방법에 대한 개요를 제공합니다. Java용 Azure 클라이언트 라이브러리에는 다음 두 가지 로깅 옵션이 있습니다.

임시 디버깅을 위한 기본 제공 로깅 프레임워크입니다.
SLF4J 인터페이스를 사용한 로깅 지원

SLF4J는 Java 에코시스템에서 잘 알려져 있으며 잘 문서화되어 있으므로 사용하는 것이 좋습니다. 자세한 내용은 SLF4J 사용자 설명서를 참조하세요.

이 문서는 널리 사용되는 많은 Java 로깅 프레임워크를 다루는 다른 문서로 연결됩니다. 이러한 다른 문서에서는 구성 예제를 제공하고 Azure 클라이언트 라이브러리에서 로깅 프레임워크를 사용하는 방법을 설명합니다.

어떤 로깅 구성을 사용하든, Java용 Azure 클라이언트 라이브러리의 모든 로깅 출력은 azure-core ClientLogger 추상화로 라우팅되므로 두 경우 모두 동일한 로그 출력을 사용할 수 있습니다.

이 문서의 나머지 부분에서는 사용 가능한 모든 로깅 옵션의 구성에 대해 자세히 설명합니다.

HTTP 요청/응답 로깅 사용

HTTP 요청 및 응답 로깅은 기본적으로 꺼져 있습니다. HTTP를 통해 Azure 서비스와 통신하는 클라이언트를 구성하여 수신하는 각 요청 및 응답(또는 예외)에 대한 로그 레코드를 작성할 수 있습니다.

OpenTelemetry를 사용하는 경우 HTTP 요청에 대한 로깅 대신 분산 추적을 사용하는 것이 좋습니다. 자세한 내용은 Java용 Azure SDK에서 추적 구성을 참조하세요.

환경 변수를 사용하여 HTTP 로깅 구성

환경 변수를 AZURE_HTTP_LOG_DETAIL_LEVEL 사용하여 HTTP 로그를 전역적으로 사용하도록 설정할 수 있습니다. 이 변수는 다음 값을 지원합니다.

NONE: HTTP 로그를 사용할 수 없습니다. 이 값은 기본값입니다.
BASIC: HTTP 로그에는 요청 메서드, 삭제된 요청 URL, 시도 횟수, 응답 코드 및 요청 및 응답 본문의 콘텐츠 길이가 포함됩니다.
HEADERS: HTTP 로그에는 모든 기본 세부 정보가 포함되며 로깅 용도로 안전한 것으로 알려진 헤더도 포함됩니다. 즉, 비밀이나 중요한 정보가 포함되지 않습니다. 헤더 이름의 전체 목록은 HttpLogOptions 클래스에서 사용할 수 있습니다.
BODY_AND_HEADERS: HTTP 로그에는 수준에서 제공하는 HEADERS 모든 세부 정보가 포함되며 16KB보다 작고 인쇄 가능한 한 요청 및 응답 본문도 포함됩니다.

참고 항목

요청 URL은 삭제됩니다. 즉, 값을 제외한 모든 쿼리 매개 변수 값이 api-version 수정됩니다. 개별 클라이언트 라이브러리는 허용 목록에 안전하다고 알려진 다른 쿼리 매개 변수를 추가할 수 있습니다.

예를 들어 Azure Blob Storage SAS(공유 액세스 서명) URL은 다음 형식으로 기록됩니다. 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

Warning

로깅 요청 및 응답 본문은 중요한 정보를 포함하고, 성능에 크게 영향을 미치고, 콘텐츠가 버퍼링되는 방식을 변경하고, 다른 부작용이 있을 수 있으므로 프로덕션에서 권장되지 않습니다.

코드에서 HTTP 로깅 구성

HttpTrait<T> 인터페이스를 구현하는 Azure 클라이언트 빌더는 코드 기반 HTTP 로깅 구성을 지원합니다. 코드 기반 구성은 개별 클라이언트 인스턴스에 적용되며 환경 변수 구성에 비해 더 많은 옵션 및 사용자 지정을 제공합니다.

로그를 구성하려면 HttpLogOptions 인스턴스를 해당 클라이언트 작성기의 httpLogOptions 메서드에 전달합니다. 다음 코드는 App Configuration 서비스에 대한 예제를 보여줍니다.

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

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

이 코드는 헤더를 사용하여 HTTP 로그를 사용하도록 설정하고 응답 헤더 및 label 쿼리 매개 변수를 해당 허용 목록에 추가 Accept-Ranges 합니다. 이 변경 후에는 이러한 값이 생성된 로그에 표시됩니다.

구성 옵션의 전체 목록은 HttpLogOptions 설명서를 참조하세요.

기본 로거(임시 디버깅용)

앞서 언급했듯이, 모든 Azure 클라이언트 라이브러리는 로깅에 SLF4J를 사용하지만 Java용 Azure 클라이언트 라이브러리에는 대체 기본 로거가 기본 제공됩니다. 이 기본 로거는 애플리케이션이 배포되고 로깅이 필요한 경우에 대해 제공되지만 SLF4J 로거가 포함된 애플리케이션을 다시 배포할 수는 없습니다. 이 로거를 사용하도록 설정하려면 먼저 SLF4J 로거가 존재하지 않는지 확인하고(우선하기 때문에) 환경 변수를 AZURE_LOG_LEVEL 설정해야 합니다. 다음 표에서는 이 환경 변수에 허용되는 값을 보여 줍니다.

로그 수준	허용되는 환경 변수 값
VERBOSE	`verbose`, `debug`
정보	`info`, , `informationinformational`
WARNING	`warn`, `warning`
오류	`err`, `error`

환경 변수를 설정한 후에는 환경 변수가 적용될 수 있도록 애플리케이션을 다시 시작합니다. 이 로거는 콘솔에 로그하고 롤오버 및 파일에 대한 로깅과 같은 SLF4J 구현의 고급 사용자 지정 기능을 제공하지 않습니다. 로깅을 다시 해제하려면 환경 변수를 제거하고 애플리케이션을 다시 시작합니다.

SLF4J 로깅

기본적으로 SLF4J 지원 로깅 프레임워크를 사용하여 로깅을 구성해야 합니다. 먼저 관련 SLF4J 로깅 구현을 프로젝트의 종속성으로 포함합니다. 자세한 내용은 SLF4J 사용자 설명서에서 로깅에 대한 프로젝트 종속성 선언을 참조하세요. 다음으로, 로그 수준 설정, 로그를 수행 및 기록하지 않는 클래스 구성 등 사용자 환경에서 필요에 따라 작동하도록 로거를 구성합니다. 이 문서의 링크를 통해 몇 가지 예제가 제공되지만, 자세한 내용은 선택한 로깅 프레임워크에 대한 설명서를 참조하세요.

로그 형식

로깅 프레임워크는 사용자 지정 로그 메시지 서식 및 레이아웃을 지원합니다. Azure 클라이언트 라이브러리 문제를 해결할 수 있도록 다음 필드를 포함하는 것이 좋습니다.

전체 자릿수가 밀리초인 날짜 및 시간
로그 심각도
로거 이름
스레드 이름
메시지

예를 들어 사용하는 로깅 프레임워크에 대한 설명서를 참조하세요.

구조적 로깅

이전에 멘션 공통 속성을 로깅하는 것 외에도 Azure 클라이언트 라이브러리는 해당하는 경우 추가 컨텍스트로 로그 메시지에 주석을 추가합니다. 예를 들어 다음 예제와 같이 다른 루트 속성으로 작성된 컨텍스트가 포함된 az.sdk.message JSON 형식 로그가 표시될 수 있습니다.

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}

Azure Monitor에 로그를 보낼 때 Kusto 쿼리 언어를 사용하여 구문 분석할 수 있습니다. 다음 쿼리는 예제를 제공합니다.

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)